Report MCP tool failures correctly: tool execution errors with isError versus JSON-RPC protocol errors

Documented steps

1. Classify the failure first. Request-structure problems that a model is unlikely to fix — unknown tool name, a request that fails the CallToolRequest schema, internal server errors — are PROTOCOL errors.
2. Return protocol errors as standard JSON-RPC error objects, e.g. {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Unknown tool: invalid_tool_name"}}.
3. Classify actionable failures — upstream API failures, input validation problems such as a date in the wrong format or a value out of range, and business-logic errors — as TOOL EXECUTION errors.
4. Return tool execution errors inside a normal successful JSON-RPC result with isError: true, resultType: 'complete', and a content array whose text explains what to fix, e.g. 'Invalid departure date: must be in the future. Current date is 08/08/2025.'
5. Write the error text for the model, not for a log file: name the offending parameter, the constraint violated, and the value that would work.
6. Client side: pass tool execution errors to the language model so it can self-correct and retry with adjusted parameters (SHOULD). Protocol errors MAY be surfaced to the model but are less likely to result in successful recovery.
7. For a stateful tool called with an expired or unknown handle, return a tool execution error saying so, so the model can recover by creating a new handle.
8. Validate all tool inputs, apply access controls, rate limit invocations and sanitize outputs on the server side regardless of which error path you take.
9. Confirm the split at https://modelcontextprotocol.io/specification/2026-07-28/server/tools