MCP · Building servers and clients · all subjects

tools: calling and results

8 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

SEP-1303: Input validation errors should be Tool Execution Errors not Protocol Errors

SEP-1303 (Final status, created 2025-08-05) establishes that input validation errors from tools should be returned as Tool Execution Errors with isError: true in the result, not as Protocol Errors. This allows language models to receive validation error feedback in their context window, enabling self-correction without human intervention. Protocol Errors are caught at the application level by the MCP Client and not forwarded to the model, so models cannot see them and cannot self-correct.

Tool Execution Error format for input validation

When a tool input validation fails, the server should return a JSON-RPC response with a result object containing isError: true and a content array with type 'text' describing the validation error. For example: { "result": { "content": [{ "type": "text", "text": "Dates must be in the future. Current date is 08/08/2025" }], "isError": true } }

Input validation errors should be Tool Execution Errors, not Protocol Errors

SEP-1303 clarifies that tool argument validation failures must be reported as Tool Execution Errors with isError: true rather than Protocol Errors. This allows language models to receive validation error feedback in their context window, enabling self-correction and improved task completion rates. The specification removes "invalid argument" from the Protocol Errors category and merges it under Tool Execution Errors as part of input validation errors.

Tool Execution Error structure for validation failures

When a tool input validation fails, the server must return a response with a result object containing an array of content objects and isError: true. The content should be of type "text" with a text field containing the validation error message. This response structure allows the error message to reach the model for self-correction.

Why models fail to self-correct with Protocol Errors

When validation errors are returned as Protocol Errors (JSON-RPC error responses), the model does not receive the error message in its context window. The error is caught at the application level by the MCP Client and does not get forwarded to the model. This prevents the model from understanding why the tool call failed and leads to repeated identical failing attempts.

Benefits of treating validation errors as Tool Execution Errors

Using Tool Execution Errors for input validation failures provides: higher task completion rates by allowing models to self-correct; better user experience with reduced failures; leveraging LLM capabilities for understanding error messages; and reduced API calls as models correct themselves on the first error rather than retrying blindly.

Example of model self-correction with Tool Execution Error

When a flight booking tool receives departureDate: "12/12/2024" (a past date), instead of returning Protocol Error -32602, the server returns a Tool Execution Error response with isError: true and error message text "Dates must be in the future. Current date is 08/08/2025". The model then receives this message, understands the issue, and retries with a corrected future date like departureDate: "12/12/2025".

Tool error handling categories after SEP-1303

Tools use two error reporting mechanisms: (1) Protocol Errors for unknown tools and server errors; (2) Tool Execution Errors reported in tool results with isError: true for API failures, input validation errors, and business logic errors.

Give your agent this brain