Spirit Room / Guides

Tool results and errors for AI agents: design outputs that move the job forward

Most MCP advice is about tool names and descriptions. But once an agent calls your tool, the result is what decides the next step: answer, retry, or give up. On a 99-tool production server, the results were correct and still got in the way. This guide collects what we measured and the rules that follow.

Leonid Bugaev · Published 21 Oct 2026

Why results matter more than you think

An agent reads your result and decides what to do next. If the result is too big, the app refuses it or cuts it. If an error is a type dump, the agent burns turns guessing. If the error says “ask a human”, a well-behaved agent stops. Your data can be right and the job still fails.

The rules below come from live, read-only runs on a 99-tool production MCP server and small mock experiments. Each links to a page with the full numbers.

Five rules at a glance

1. Small by default

The list tool's default call (no arguments, 20 items) returned 46,253 tokens, about 2,300 per item. Claude Code refused 40 results like this in 23 of 40 runs (42–71%) because they were over its 25,000-token limit, then read them back from files with 138 extra local reads.

In a mock A/B we made the defaults lean: a summary line, a few fields per item, and a cursor. A default list went from 11,776 to 546 tokens and an overview from 12,060 to 198. Across three apps and both variants, every cell still passed 10/10.

Full numbers and how to do it: how to reduce MCP tool response size. Per-app caps: MCP output limits by agent.

2. Errors that name the fix

One wrong argument on an update tool returned a 12,689-token error, mostly the schema echoed back. The same kind of mistake on two other tools cost 150 and 110 tokens. Another validation error was a 15-line type tree that never said, in one line, which values were allowed.

Before: 15-line type tree … Expected "qualified", actual "to_review" (×3)
After:  stage "to_review" is not valid; use one of: qualified, needs_review, disqualified

The MCP spec already says to return fixable errors as tool results with isError: true, so the model can correct itself. The wording is up to you. See error messages for AI agents.

3. Honest next-step guidance

The server added a guidance block to every refusal. For three deliberately malformed ids, all three said the state was “human input”: a person must decide. A typo in a read is not a decision. A version conflict that the text itself said to fix by re-reading and retrying got the same guidance. Agents that follow guidance stop and ask the user about a routine retry.

Fix: use distinct states, for example fix arguments, retry after re-reading, and needs a person, and keep the last one for real decisions such as spending.

4. Know which half of the result the model sees

An MCP result can carry text and structuredContent. On this server 27 of 34 read tools put the same data in both, so the default list call was 25,806 tokens of text plus 20,447 structured. In our two-marker test, Claude Code showed the model only the structured half, OpenCode only the text, and Codex both. See structuredContent or text.

5. Don't echo the agent back to itself

Asked for recent activity with a limit of 200, the feed returned 200 events, and 152 were records of the same connection's own tool calls. The whole response was 98,512 tokens. Every call adds another event, so the more an agent checks, the noisier it gets. Fix: leave out the caller's own tool-call events by default.

Go deeper: The 12,689-token typo, How much MCP output is waste, Next-step hints in results, Typed refusals.

Guides in this section

• How to write error messages for AI agents
• How to reduce MCP tool response size
• structuredContent or text: which half the model sees
• MCP output limits by agent
• The 12,689-token typo
• Results that say what to do next
• Typed refusals agents can act on

Up: agent-ready tools. Method: how to test an MCP server with real AI agents.

How we measured

• Server snapshot: direct calls to a 99-tool production MCP server, 3 identical runs, 16 Oct 2026; tokens counted with o200k_base.
• Live agent runs: Claude Code 2.1.301 and Codex CLI 0.161.0, 8 read-only jobs × 5 runs each, writes blocked by a proxy, 16 Oct 2026.
• Mock A/B: a local stand-in server with before and lean variants, Claude Code 2.1.304, Codex 0.161.0 and OpenCode 1.18.34, 10 runs per cell, 21 Oct 2026. Ranges are 95% Wilson intervals.
• Limits: one production server; the mock is small and deterministic. Tool names and values in examples are simplified.