SEP-2145: Standardize `tools/call` failure reporting by KKonstantinov · Pull Request #2145 · modelcontextprotocol/modelcontextprotocol · GitHub

Summary

This SEP extends tools/call error handling so that additional failure modes — tool resolution failures and output validation failures — are reported as Tool Execution Errors (CallToolResult with isError: true) rather than JSON-RPC Protocol Errors.

Key Changes

Tool resolution failures (unknown tool, tool not callable/disabled) → Tool Execution Error
Output validation failures (missing or non-conforming structuredContent when outputSchema is declared) → Tool Execution Error
Protocol Errors reserved for malformed requests, unsupported methods, and unrecoverable server failures
Aligns specification with existing Python and TypeScript SDK behavior

Add a error schema to tools/list

Schema change (schema/draft/schema.ts and docs):

  interface ListToolsResult {
    tools: Tool[];
    nextCursor?: string;
    errorSchema?: JSONSchema; // NEW: applies to ALL tool errors
  }

Then, something in the spec like

If isError: true and structuredContent is present:
- If errorSchema exists, it MUST conform to errorSchema.
- Clients SHOULD validate error results against errorSchema.

Why? it is very common to have a server-wide error format. e.g. OpenAI ErrorResult. Doing so would prevent one of three bad choices:

have no way to know the shape of an error (not validated)
force error to be the same shape as the success (weird)
complicated oneOf for every tool.

Fix the “error text disappears on validation failure”

If validation fails, clients MUST still surface content.
Clients MAY drop/ignore invalid structuredContent, but MUST NOT replace the tool’s error message with a schema error.

Why? this prevents replacing a good but pedantically incorrect error message with an unusable one. modelcontextprotocol/typescript-sdk#1428 is an example of this, but it can also happen in proxies, just like normal REST apis sometimes a proxy overrides the error response in CDN conditions.

It would be find to make it a detailed field. If we don't do something like that it requires JSON-RPC level debug which is not easy for people to do.

modelcontextprotocol/typescript-sdk#1428 ran into this, and I wonder if there is a way to return the actual content on output validation fail.

If we had the content sent back, mistakes are easier to identify and correct. Mistakes are sometimes in the raw server code, other times in proxies.

Text mentions that models can handle stale tool lists by re-listing tools. Client hosts rarely provide a mechanism for models to do this. Only code mode style integrations allow for this out of the box. The example shown explicitly tells the model to re-run "tools/list" which the model usually cannot.

In 'basic' SDK driven integrations it is the client host that lists tools, and providing an easily handled error code at the JSON-RPC level allows the host to do this. This doesn't happen currently but JSON-RPC does allow for new error codes, and we could define one for this.

Alternatively an additional property in the payload could be introduced in addition to isError, so that the error handling accomodates both standard and code mode integrations.

Considering "unknown tool" purely a model concern prevents the host from handling this and may confuse models when they cannot re-list or otherwise adapt to the error (other than telling the user the tool failed).

Hi,

TL;DR on this SEP:

Python and Typescript SDK have this behavior for a long time, but the wording on the November SEP that got in did not describe these scenarios; Getting this SEP in will just clarify language, bit it would not lead to any tangible behavior or code change on the SDKs. Happy to be corrected on this, but checked it back in Oct/Nov, and believe it's still the situation.

PS.

modelcontextprotocol/typescript-sdk#1389 -> brought TS SDK back to spec.
modelcontextprotocol/python-sdk#1872 -> Pending on Python SDK to bring it back to spec.

This SEP would make the agent "aware" that a tool does not exist; while Protocol-level errors means the agent is unaware (this is the behavior Claude web has).

It's valuable context for the agent in some scenarios to know this, but it'll depend on whether this SEP gets reviewed/accepted.

State Transition: proposal → draft

This SEP has been transitioned from proposal to draft.

@pcarleton has been assigned as the sponsor for this SEP.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 16 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

The PR diff doesn't include this schema.ts change. The current CallToolResult.isError JSDoc still says errors in finding the tool should be reported as an MCP error response, which directly contradicts the resolution-failure MUST above. Needs the schema hunk plus a regenerate.

The proposed wording here includes "Clients SHOULD provide tool execution errors to language models…" but the actual tools.mdx diff in this PR doesn't add that sentence. Either the diff or this block should be brought in line.

A few more drift items in the same block: the tools.mdx diff drops the "arguments do not match tool inputSchema" clause from the input-validation bullet, reorders output-validation before input-validation, and uses different example message formats than the templates and Examples section here. Probably easiest to regenerate the tools.mdx hunk from this block verbatim once it settles.

This is now backwards: typescript-sdk#1389 merged in March to bring the TS SDK back to the current spec (protocol error for unknown tool), and python-sdk#1872 proposes the same. So today the TypeScript SDK does the opposite of what this SEP mandates. Is that intended?

I think this needs to be reconciled with the earlier TS change I mentioned. That PR brought the TS SDK into conformance with the current spec (protocol error for unknown tool); this SEP would make that change wrong. Which one reflects the intended direction?

tools.mdx already has "Servers MUST provide structured results that conform to outputSchema / Clients SHOULD validate." Worth a cross-reference here so it's clear how this server-side SHOULD-report relates to that pair (defense-in-depth, or shifting the validator role?).

There's also InvalidParamsError in schema.ts whose JSDoc Tools bullet asserts the opposite, plus schema/draft/examples/InvalidParamsError/unknown-tool.json and invalid-tool-arguments.json which render into the Schema Reference. Without updating those, schema.mdx will contradict tools.mdx after this lands.

Suggested change

      
            - `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.
          
            - `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.
          
            - `schema/draft/schema.ts` documentation for `InvalidParamsError` (Tools bullet) and the associated example files (`examples/InvalidParamsError/unknown-tool.json`, `invalid-tool-arguments.json`) so the generated Schema Reference matches.

Hi @localden , missed notification about this one. I'll review the comments and address/resolve them tomorrow; PR also needs updating with latest, as it has some conflicts.

EDIT: Comments addressed

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 20 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

I ran a census against the live registry to see what this SEP would actually land on, and one number seems load-bearing for the output-validation clause specifically.

Method. Walked registry.modelcontextprotocol.io/v0/servers (60,892 entries, 609 pages) and took server.remotes[].url — 21,396 entries carry remotes, 10,559 unique endpoints, 10,500 probed. 5,722 of those completed an initialize handshake. I harvested tools/list from those 5,722; 5,014 returned a parseable tool list. Full response bodies are stored so the verdict is derived downstream rather than at probe time. One endpoint reported a tool list and would not parse; it stays in the denominator as a failure rather than being dropped.

Write tools. 2,355 of those servers expose at least one mutating tool (readOnlyHint: false, or a mutating verb where no annotation is declared — counted separately, 11,639 by annotation and 2,076 by verb inference). 13,715 write tools total.

The number:

	count	share of write tools
declare inputSchema	13,715	100%
declare outputSchema	1,535	11.19%
declare no output contract at all	12,180	88.81%

Every write tool in the registry says precisely what to send it. Fewer than one in nine says what comes back.

That matters here because "output validation failures (missing or non-conforming structuredContent when outputSchema is declared) → Tool Execution Error" is conditioned on a declared outputSchema. On the current write surface that clause is inert for roughly seven of every eight tools. Not an argument against it — the direction looks right to me — but if the SEP is partly motivated by making failures legible to clients, it is worth knowing that the population it reaches is about 11% of writes today, and that the other 89% will keep returning isError: false with an undeclared shape regardless of what this standardises.

A gap that remains after this SEP, which I think is orthogonal to it. Every failure mode enumerated here is one the server itself detects: unknown tool, disabled tool, malformed request, output that fails its own schema. There is no vocabulary for the case where the server did everything correctly, got an acknowledgement from a third party, validated cleanly, and the far side never committed. That call returns isError: false and is fully conformant. The success artifact and the silent-failure artifact are byte-identical by specification rather than by anyone's sloppiness — which means it cannot be found by reading your own logs, because your logs are you telling yourself what you already believe.

I went looking for anyone expressing that third state and want to publish the search honestly, including its noise. A regex for unverified/unconfirmed/indeterminate/pending-confirmation over declared output schemas returned 6 of 13,715, and on inspection I judge 5 of the 6 to be false positives — domain vocabulary rather than delivery semantics:

get_auto_insurance_quote, get_home_insurance_quote, get_bundle_insurance_quote — matched "uncertain", which is quote confidence
refresh_wallet_balance, check_swap — matched "unverified", which is token/contract status
start_free_diagnostic — matched "pending_confirmation"; this one may be real

So the honest count is 0–1 in 13,715, and I would rather show you the five I threw out than report a clean 6. My own crawler's false-positive rate on a different corpus measured 56% when I finally checked it, so I no longer trust a number of mine that arrives without its noise attached.

Happy to share the raw harvest or the classifier if either is useful to the SEP discussion, and happy to be told the third-state case belongs somewhere other than this thread.

Building on @siliroid's census above, which covers the remote surface. I measured the local one, and the two turn out to be close to disjoint: they probed hosted endpoints and read declared metadata, I installed and executed npm/PyPI stdio servers and tested behaviour against inputs.

The SEP argues that reclassifying tool resolution failures "aligns specification with existing Python and TypeScript SDK behavior." Here is how much alignment already exists.

Method. Every registry server that is locally installable, uses stdio, and declares no required credentials: 6,106 of a 17,432-server snapshot. Each launched in an isolated container and sent a tools/call for a tool name that does not exist, graded against the protocol version it negotiated.

Result. Of the 3,685 that completed a handshake, 88.4% (95% CI 87.3–89.4) answered with isError: true rather than a JSON-RPC protocol error.

SDK family	servers	answer with isError
official TypeScript SDK	2,347	90%
official Python SDK	645	88%
FastMCP (Python)	375	100%

The official reference servers behave the same way. The minority emitting protocol errors are mostly TypeScript-SDK servers, so the specified behaviour is reachable in the SDK but is not its default. Holding one server per publisher (3,913 publishers, largest ships 305) gives 85.2%, so this is not an artifact of templated bulk publishing.

Why it might matter. The alignment already covers roughly nine in ten servers, so adopting this ratifies existing behaviour and the migration cost falls on the ~11.6% minority rather than the majority. That is a different cost profile from "change the ecosystem to match the spec." I have no position on which mechanism is correct.

One thing that may bear on @siliroid's third-state gap. Sending a wrong-typed value for a required argument a server's own inputSchema declares, 129 servers executed the tool anyway and returned ordinary-looking output. A code-scanning tool asked to scan the integer 12345 replied CLEAN. isError: false, well-formed, no signal. Different cause from an unacknowledged third party, same artifact: a success response byte-identical to a real one. Suggests that shape is not only a distributed-systems problem.

Data, harness and raw transcripts: https://github.com/Ahmad-Faraj/mcp-conformance. Any server re-checkable with python driver/mcpprobe.py --cmd "<launch command>". Happy to re-run against a revised rule.

Disclosure: the measurement pipeline and write-up were built with substantial AI assistance; the data, method and this comment are mine and I am answerable for them.

Maintainer Activity Check

Hi @pcarleton!

You're assigned to this SEP but there hasn't been any activity from you in 20 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

SEP - standardize tools/call failure reporting

453de55

KKonstantinov mentioned this pull request Jan 23, 2026

SEP-2140: Standardize tools/call Failure Reporting (Tool Resolution + Output Validation) #2140

Closed

KKonstantinov marked this pull request as ready for review January 23, 2026 16:39

KKonstantinov requested a review from a team as a code owner January 23, 2026 16:39

KKonstantinov changed the title SEP - standardize tools/call failure reporting SEP-2145: Standardize tools/call failure reporting Jan 23, 2026

localden added proposal SEP proposal without a sponsor. SEP labels Jan 24, 2026

github-project-automation Bot added this to SEP Review Pipeline Jan 24, 2026

Merge branch 'main' into sep/standardize-tools-call-failure-reporting

eba76ea

SamMorrowDrums reviewed Jan 24, 2026

View reviewed changes

joshrotenberg mentioned this pull request Jan 29, 2026

[proposal] SEP-2145: Standardize tools/call failure reporting joshrotenberg/tower-mcp#147

Closed

codefromthecrypt mentioned this pull request Feb 2, 2026

fix(client): skip output schema validation on error results modelcontextprotocol/typescript-sdk#1428

Closed

9 tasks

codefromthecrypt reviewed Feb 2, 2026

View reviewed changes

codefromthecrypt mentioned this pull request Feb 2, 2026

fix: skip output schema validation when tool result isError modelcontextprotocol/inspector#1045

Closed

7 tasks

Merge branch 'main' into sep/standardize-tools-call-failure-reporting

7ab9982

Merge branch 'main' into sep/standardize-tools-call-failure-reporting

ff36c4c

KKonstantinov mentioned this pull request Mar 2, 2026

fix: throw ProtocolError as JSON-RPC error for tool not found modelcontextprotocol/typescript-sdk#1567

Closed

pcarleton self-assigned this Mar 13, 2026

sep-automation-bot Bot added draft SEP proposal with a sponsor. and removed proposal SEP proposal without a sponsor. labels Mar 13, 2026

KKonstantinov and others added 3 commits March 19, 2026 10:24

Merge branch 'main' into sep/standardize-tools-call-failure-reporting

51a78e0

add SEP as md file

d7614b7

run generate:seps

e7b67aa

KKonstantinov requested a review from a team as a code owner March 19, 2026 08:34

mcp-virtual-tpm Bot added this to the 2026-06-30-RC milestone Apr 17, 2026

localden added in-review SEP proposal ready for review. and removed draft SEP proposal with a sponsor. labels Apr 22, 2026

localden moved this to In Review in SEP Review Pipeline Apr 22, 2026

localden reviewed Apr 29, 2026

View reviewed changes

This was referenced Apr 30, 2026

2026-07-28 Spec Compliance modelcontextprotocol/csharp-sdk#1539

Closed

SEP-2145: Standardize tools/call failure reporting modelcontextprotocol/csharp-sdk#1551

Closed

KKonstantinov added 2 commits May 14, 2026 15:37

address comments

730f6ea

resolve conflicts with main

65d5db3

localden removed this from the 2026-06-30-RC milestone May 19, 2026

This was referenced Jul 3, 2026

Admin server-side backfill (My Work sync button) + admin-gated update_plan SaplingLearn/canopy#9

Merged

feat(weave-mcp): read-only MCP server + shipped skill over fleet-retro/release-events misty-step/weave#33

Merged

coderabbitai Bot mentioned this pull request Jul 12, 2026

Starlight Memory → production: cross-agent MCP, Honcho adapter, Memory Observatory frankxai/starlight-memory#6

Merged

coderabbitai Bot mentioned this pull request Jul 14, 2026

Task-aware multi-provider router + RAG semantic memory + cost CLI 93jessycollin93-del/jacky#2

Merged

coderabbitai Bot mentioned this pull request Aug 18, 2026

release: v4.5.2 - version bump rakaarwaky/qwen-web-arwaky#142

Closed

qodo-code-review Bot mentioned this pull request Aug 29, 2026

Harden the final judge workflow tobias-minibot/pricemcp#2

Merged

+                - Treat "Unknown tools" (tool name resolution) as a Tool Execution Error for `tools/call`.
+                - Add explicit categories for "tool not callable" and "output schema validation failures" as Tool Execution Errors.
+                - Keep Protocol Errors focused on malformed `CallToolRequest` and server-level failures.
+              - `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.

+                - Treat "Unknown tools" (tool name resolution) as a Tool Execution Error for `tools/call`.
+                - Add explicit categories for "tool not callable" and "output schema validation failures" as Tool Execution Errors.
+                - Keep Protocol Errors focused on malformed `CallToolRequest` and server-level failures.
+              - `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.

+                  "content": [
+                    {
+                      "type": "text",
+                      "text": "Input validation error: Invalid arguments for tool book_flight: Invalid departure date, must be in the future. Current date is 08/08/2025."


		## Rationale

		- Aligns with existing SDK behavior: As noted in the Nov 7 discussion, both the Python and TypeScript SDKs already return `CallToolResult` with `isError: true` for unknown tools, disabled tools, and various output schema failures. Making this behavior normative improves interoperability and reduces host-specific divergence.


		This SEP does not change JSON-RPC framing or introduce new required fields.

		However, it is a behavioral change for servers that currently return Protocol Errors for tool resolution and output validation failures. Clients that rely on a JSON-RPC error response for these cases will need to handle `CallToolResult.isError: true` equivalently.

+                 - Exceptions thrown by the tool implementation.
+                 - Timeouts or cancellations that occur during tool execution (if the server can still return a `CallToolResult`).
+. **SHOULD** report output validation failures as Tool Execution Errors when a tool declares an `outputSchema`, including:

	- `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.
	- `schema/draft/schema.ts` documentation for `CallToolResult.isError` to remove/adjust language suggesting that "errors in finding the tool" should be protocol errors, aligning it with the above requirements.
	- `schema/draft/schema.ts` documentation for `InvalidParamsError` (Tools bullet) and the associated example files (`examples/InvalidParamsError/unknown-tool.json`, `invalid-tool-arguments.json`) so the generated Schema Reference matches.

SEP-2145: Standardize `tools/call` failure reporting by KKonstantinov · Pull Request #2145 · modelcontextprotocol/modelcontextprotocol · GitHub

Uh oh!

SEP-2145: Standardize tools/call failure reporting - #2145

Conversation

KKonstantinov commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Related

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codefromthecrypt left a comment

Choose a reason for hiding this comment

Add a error schema to tools/list

Fix the “error text disappears on validation failure”

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PederHP commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KKonstantinov commented Feb 3, 2026

Uh oh!

KKonstantinov commented Mar 13, 2026

Uh oh!

sep-automation-bot Bot commented Mar 13, 2026

State Transition: proposal → draft

Uh oh!

sep-automation-bot Bot commented Mar 30, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot Bot commented Apr 13, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot Bot commented Apr 27, 2026

Maintainer Activity Check

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

localden Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KKonstantinov May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sep-automation-bot Bot commented May 11, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot Bot commented May 25, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot Bot commented Jun 8, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot Bot commented Jun 22, 2026

Maintainer Activity Check

Uh oh!

KKonstantinov commented Jan 23, 2026 •
edited
Loading

PederHP commented Feb 3, 2026 •
edited
Loading

localden Apr 29, 2026 •
edited
Loading

KKonstantinov May 6, 2026 •
edited
Loading

Ahmad-Faraj commented Jul 31, 2026 •
edited
Loading