Skip to content

[Server] Answer arguments the input schema refuses with a tool error from 2025-11-25 on - #764

Open
falisco wants to merge 1 commit into
modelcontextprotocol:mainfrom
falisco:tool-argument-validation-as-tool-error
Open

falisco wants to merge 1 commit into
modelcontextprotocol:mainfrom
falisco:tool-argument-validation-as-tool-error

Conversation

@falisco

@falisco falisco commented Nov 21, 2026

Copy link
Copy Markdown

Fixes #763.

Problem

CallToolHandler validates the arguments of tools/call against the tool's input schema before the tool runs, and answers a mismatch with the JSON-RPC error -32602.

That matched the specification up to 2025-06-18, whose "Error Handling" section of Tools lists "Invalid arguments" under protocol errors. Revision 2025-11-25 moved the case (SEP-1303, changelog item 5: "Clarify that input validation errors should be returned as Tool Execution Errors rather than Protocol Errors to enable model self-correction"). Its Error Handling section now lists "Input validation errors (e.g., date in wrong format, value out of range)" under tool execution errors, reported in the result with isError: true. Clients SHOULD hand those to the model and only MAY hand it protocol errors. 2026-07-28 keeps that text.

So on a session at 2025-11-25 or later, a model that sends "a" where the schema wants ^[A-Z]$ may never be shown why its call failed, while a value the tool itself refuses (ToolCallException) comes back as a result it can read.

Change

ProtocolVersion::reportsInvalidToolArgumentsAsToolError() is true from 2025-11-25 on. When the schema validation fails and the session's revision says so, CallToolHandler answers with a tool execution error whose text is the message the protocol error carried:

{
  "content": [
    {
      "type": "text",
      "text": "Invalid parameters for tool 'shout': Property '/letter': String does not match the required pattern: `^[A-Z]$`."
    }
  ],
  "isError": true
}

Sessions up to 2025-06-18 get -32602 with data.validation_errors, exactly as before. The RequestContext is now built before the validation, since the revision is read from it.

Not changed:

  • An unknown tool and a request that is not a valid CallToolRequest stay protocol errors on every revision, as the specification has them.
  • An argument that cannot be cast to its parameter type, and a missing argument found at that stage (RegistryException::isInvalidParams()), still answer -32602. Most of these are caught by the schema first, but not all: with the fixture of IntArgumentTest, {"qty": 0} is now a tool error and {"qty": 9300000000000000000} is still -32602. I left that branch alone because 0.10.0 set it on purpose ([Server] Stop integer arguments beyond the integer range from wrapping around #697, [Client][Docs][Server] Fix docs review findings and the SDK bugs behind them #705), IntArgumentTest asserts it, and the same path serves prompts and resources. Say the word and I move the tool side under the same predicate here, or in a follow-up.

How the other SDKs behave

All four answer an input-schema mismatch with a tool result, and none of the paths I read branches on the negotiated revision:

SDK On arguments the input schema refuses
TypeScript, packages/server/src/server/mcp.ts:341-358, 407-412 validateToolInput throws, the tools/call handler catches and returns isError: true
Python, src/mcp/server/mcpserver/tools/base.py:153-158 ValidationError is raised as ToolError, returned as is_error=True
Java, mcp-core/.../util/ToolInputValidator.java:39-51 CallToolResult with isError(true), on by default
Go, mcp/server.go:423-430 (typed AddTool) errRes.SetError(...), returned as a result

This pull request is more conservative than they are: it keeps -32602 for the revisions whose text asks for it, the way the handler already gates structuredContent and resource-not-found by revision.

Compatibility

A client on 2025-11-25 or later that matched on -32602 to detect refused arguments now gets a result with isError: true instead, and no longer gets data.validation_errors: the text holds the same summary, and the full list goes to the debug log, as validateStructuredContent() does for output. If you would rather keep the list on the result, _meta could carry it. The CHANGELOG entry is marked [BC Break].

Tests

  • CallToolHandlerTest: refused arguments are a tool execution error with the validation message on 2025-11-25, on 2026-07-28 and when no revision was negotiated; they stay -32602 with validation_errors on 2024-11-05, 2025-03-26 and 2025-06-18; the tool is never called. Written first and seen failing.
  • ProtocolVersionTest: the predicate, revision by revision.
  • StdioDualEraTest: the two tests that used -32602 as the sign of a refused argument, on both openings, now read the tool error.

Run locally: make cs, make phpstan, make deptrac, the unit, integration and interop suites, and the server conformance suites for 2025-11-25 (80/80) and 2026-07-28 (152/152). docs/servers/schemas.md ("Argument Validation") shows both answers.

…from 2025-11-25 on

SEP-1303, part of revision 2025-11-25, moved input validation errors from
protocol errors to tool execution errors, so that the model reads what was
wrong and can retry. Sessions up to 2025-06-18 keep -32602.

Fixes modelcontextprotocol#763

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Server] Answer arguments the input schema refuses with an isError result from revision 2025-11-25 on

1 participant