Blog / Tool results and errors
The 12,689-token typo: how one validation error can eat an agent's context
Agents make argument mistakes all the time: a wrong ID format, a label instead of an enum value, a date without a time. What your server sends back decides whether that costs 50 tokens or 12,000.
What happened
We sent an update tool on a 99-tool production MCP server a malformed ID, a mistake agents make routinely. The server replied with the tool's entire input specification.
Identical in all 3 runs. Nowhere in it was a single line saying which field was wrong and what to send.
Find your most expensive errors.
We send fixed bad calls to every tool on your server and measure what each error costs agents, then show the one-line version.
Why errors balloon
- Schema echo. The validator prints everything it expected. The bigger the tool's schema, the bigger every error.
- Type trees. Another tool's error was a 15-line tree of internals (
readonly, branded types) ending inExpected "qualified", actual "to_review", three times. - It compounds. The error stays in the conversation and is resent with every later request. See MCP context window usage.
Small versus large, on a mock
On a made-up task-tracker server we tried both error styles.
Runs with at least one error went from 4/30 (5–30%) to 0/30 (0–11%) with the fixed surface. That surface also accepted date-only input that used to fail, so the drop isn't from wording alone. Every errored run recovered either way: big errors cost tokens, not answers, here.
The one-line error
Before: Invalid arguments: { readonly playId: ...; readonly expectedRevision: ...; ... 47 KB ... }
After: playId "abc" is not an id. Use an id from list_plays. Nothing was changed.- Field, expected, got, where to get a valid value.
- Say that nothing changed, so the agent retries instead of stopping.
- Don't tell the agent to ask the user about a typo. See agent refusal states.
- Accept harmless variants (date-only, a screen label) instead of erroring. See UI words vs API values.
Full guide: error messages for AI agents. Back to tool results and errors for agents.
Go deeper: Reduce tool response size, How much MCP output is waste, MCP scorecard.
How we measured
- Live: fixed bad calls sent directly to the production server, 3 identical runs, 16 Oct 2026, o200k_base tokens.
- Mock: a made-up task tracker, 3 apps × 10 runs per surface, 21 Oct 2026; error sizes computed from the server directly. 95% Wilson ranges.
- Limits: one production server; the example field names are generalised.
FAQ
Why are MCP validation errors so large?
Many validation libraries print the whole expected schema, or a full type tree, when input doesn't match. For a tool with a big input schema, that's thousands of tokens. On the server we tested, one malformed ID returned 12,689 tokens.
Does a big error hurt the agent?
It adds the whole error to the conversation, which is resent with every following request, and buries the cause. On the server we tested each such mistake added about 12.7k tokens.
What should an MCP validation error contain?
The field, the expected value or format, what was sent, and where to get a valid value, in one line. For example: playId "abc" is not an id; use an id from list_plays.
Find your most expensive errors.
We send fixed bad calls to every tool on your server and measure what each error costs agents, then show the one-line version.