Blog / Tool results and errors

How to write error messages for AI agents: before and after, from a production MCP server

An agent sends a malformed ID. That's a routine mistake, and the fix is one line. Instead the server answers with its tool's entire input specification, 12,689 tokens of it, plus a note telling the agent to stop and ask a human. Here's what real production errors look like to an agent, and how to rewrite them.

Leonid Bugaev · Published 21 Oct 2026

Why errors for agents are different

A developer who hits a bad error opens the docs, searches the code or asks a colleague. An agent can't. All it has is the text of the error, the tool descriptions and what it has seen so far. Whatever the error says shapes its next call: fix and retry, try another tool, ask the user, or give up.

The MCP spec already separates two kinds of failure. Protocol errors (unknown tool, malformed request) are JSON-RPC errors that the model may never see. Tool execution errors (bad input, missing record, upstream failure) come back as a normal result with isError: true, and clients should show them to the model so it can self-correct. This post is about the second kind: what to put in them.

What bad errors cost, measured

We sent deliberately malformed arguments to a 99-tool production MCP server and counted the replies in tokens (o200k_base).

Tool C replied with its entire input specification, identical in 3 of 3 runs. That's more than many whole tool results, and the actual cause (“this ID isn't valid; get one from the list tool”) was buried somewhere inside. Agents make argument mistakes routinely, so every such slip can add about 12.7k tokens to the conversation and to every model request after it.

Size wasn't the only problem:

• Type dumps instead of hints. Validation errors were multi-line trees from the server's schema library, with internals like readonly and branded types, and lines like Expected "approved", actual "to_review" repeated three times. The one-line fix was never stated.
• Guidance that said “stop”. Each response carried a machine-readable guidance block. For all three malformed IDs it said state: "human_input", meaning a person must decide. Two of them added “Do not repeat the change automatically”, and a read with a wrong field name got the same text.
• Text and guidance that disagreed. On a stale-version conflict, the text correctly said “re-read the item, then retry”, while the guidance block still said human_input. An agent that follows the structured field would stop and ask the user about a routine retry.

Before and after

Field and tool names below are simplified. The shape of each “before” is what the server returned.

1. Invalid enum value

// Before: 15 lines of schema-library output
Invalid arguments: { readonly status?: ReadonlyArray<"approved" | "needs_review" | ...> ... }
└─ ["status"][0]
   └─ Expected "approved", actual "to_review"
   ...

// After: one line
status[0] "to_review" is not valid. Use one of: approved, needs_review, rejected.
("To review" in the app = needs_review.)

The “after” also bridges the word the user sees in the app to the value the API wants, which is exactly where agents went wrong.

2. Wrong field name on a read

// Before
Invalid arguments: { readonly itemId: The item id returned by list_items. } └─ ["itemId"] └─ is missing
guidance: { "state": "human_input",
            "reason": "Review the reported refusal before choosing another action. Do not repeat the change automatically." }

// After
get_item takes itemId (the "id" field from list_items), not personId.
guidance: { "state": "fix_args" }

3. Malformed ID on an update

// Before: the tool's full input specification, 12,689 tokens

// After
projectId "not-a-uuid" is not a valid id. Call list_projects and pass one of its ids.
guidance: { "state": "fix_args", "next": "list_projects" }

4. Stale version

// Before
The item changed since you read it ... Call get_item to re-read its current version, then retry.
guidance: { "state": "human_input", "reason": "... Do not repeat the change automatically." }

// After
The item changed since you read it (your version 7, current 9). Call get_item, then retry with expectedVersion 9.
guidance: { "state": "retry", "next": "get_item" }

In each “after”, the recovery step names a tool the agent can call. A recent study of 3,001 error messages from 150 public MCP servers also tested recovery: naming a server tool in the step, instead of a terminal command or a bare “wait”, raised recovery on expired credentials to 84% and on rate limits to 88% (arXiv, 2026).

Tell the agent what kind of error it is

A small set of typed states lets the agent pick the right move without parsing prose. Use the same field on every tool, and keep it consistent with the text.

A second production MCP server we looked at uses a similar set and its tool descriptions tell the agent that most refusals are answers to act on, not bugs to report. That framing is worth copying.

Results matter as much as errors: what a successful call should tell the agent next is in tool results and errors for agents. How size adds up across a whole run is in the 12,689-token typo (coming soon).

Checklist for agent-facing errors

1. Return tool failures as results with isError: true, not protocol errors.
2. Name the input that failed and the value that was sent.
3. Say what's allowed: the list of values, the format, or the range.
4. Say where to get a valid value, by tool name.
5. Say whether to fix arguments, retry, wait for a state, ask the user, or stop, in the text and in one consistent structured field.
6. Reserve “ask the user” for real decisions.
7. Show only the failing path, never the whole schema. Aim for tens of tokens, not thousands.
8. Bridge app words to API values where users and the API differ.
9. Test it: send malformed arguments to every tool and count the reply in tokens. See how to measure MCP server quality.

Go deeper: 5 ways to optimise your MCP tools.

How we measured

• Server: a 99-tool production MCP server, 16 Oct 2026. Reads went through a read-only proxy. A few deliberately invalid write calls (malformed IDs, a stale version) were refused by the server, so nothing changed.
• Probes: fixed malformed calls (an ID that isn't a UUID, an invalid enum value, a wrong field name, a stale version) on several tools. Replies were recorded as bodies only and counted with o200k_base. The 12,689-token reply was identical in 3 of 3 runs.
• Not measured here: how often agents recover with the old vs rewritten errors. That needs an A/B on a mock and is planned. For recovery rates, see the arXiv study linked above.
• Rewrites: the “after” examples are our proposals, with field and tool names simplified.

Sources

• Spirit Room error probes on a production MCP server, 16 Oct 2026.
• MCP specification: tools, error handling.
• MCP TypeScript SDK: errors and Python SDK: handling errors.
• MCP error messages written for developers hurt the most capable agents most, arXiv, 2026.
• RFC 9457: Problem Details for HTTP APIs.