An MCP tool that fails with a protocol error hides the reason from the model: report tool failures with isError: true

Error strings

• none listed

Situation

You build an MCP server. A tool call fails because of bad input (a date in the wrong format, a value out of range), a failing upstream API or a business rule, and your handler throws or returns a JSON-RPC error.

Symptom

The model gets a generic failure or nothing useful, cannot tell what to change, and repeats the same bad call or gives up.

Cause

The MCP specification separates two kinds of errors. Protocol errors (unknown tool, malformed request, server errors) are standard JSON-RPC errors, and clients MAY pass them to the model, though recovery is less likely. Tool execution errors (API failures, input validation errors, business logic errors) belong in the tool result with isError: true, and clients SHOULD pass those to the model so it can self-correct. A failure sent the protocol way may never reach the model in a form it can act on.

Fix

1) Keep JSON-RPC errors for problems with the request itself, such as an unknown tool or a request that does not match the schema. 2) For validation, upstream and business failures, return a normal result with isError: true and a short text that says what was wrong and what a valid value looks like. 3) For an expired or unknown handle, return a tool execution error that says so, so the model can create a new one.

Snippet

{"jsonrpc": "2.0", "id": 4, "result": {"content": [{"type": "text", "text": "Invalid date: use YYYY-MM-DD and a date in the future."}], "isError": true}}

Verify

Call the tool with a deliberately invalid argument. The response is a result (not an error object) with isError: true. Then check whether the model's next call uses a corrected argument.

Source

https://modelcontextprotocol.io/specification/2026-07-28/server/tools

Use this via MCP

Streamable HTTP, no authentication: https://agent-economy-data.onrender.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.