--- title: Tool Results and Errors for AI Agents: A Measured Guide description: A 46,253-token default list, a 12,689-token typo error, errors that say 'ask a human'. Five measured rules for MCP tool results and errors that agents can use. canonical: https://spiritroom.app/guides/tool-results-and-errors-for-agents/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/guides/tool-results-and-errors-for-agents/ for agents. Index: /llms.txt [Spirit Room](/) / [Guides](/guides/agent-ready-tools/) # 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 **TL;DR** - **Small by default.** A default list call returned 46,253 tokens; Claude Code refused 40 such results over its 25k limit. In a mock, lean defaults cut a call 20–60× with 10/10 passes kept. - **Errors that name the fix.** One argument typo returned a 12,689-token error; the same mistake on other tools cost 150 and 110 tokens. - **Don't say 'ask a human' for a typo.** Three malformed ids all came back as needing a person to decide. - **Know which half the model sees.** 27 of 34 read tools sent the data twice; Claude Code shows only the structured half, OpenCode only the text. - **Don't echo the agent back to itself.** 152 of 200 events in one activity feed were the agent's own tool calls. [Why results matter more than you think](#why)[Five rules at a glance](#rules)[1. Small by default](#small)[2. Errors that name the fix](#errors)[3. Honest next-step guidance](#guidance)[4. Text or structured](#halves)[5. No self-noise](#noise)[Guides in this section](#cluster)[How we measured](#how-we-measured)[FAQ](#faq) ## 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. agent calls toolresult sizewhich half shownerror wordingnext step 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 | Rule | What we measured | Fix | | --- | --- | --- | | Small by default | Default list: 46,253 tokens; 40 refusals in Claude Code | Summary + key fields + cursor | | Errors name the fix | One typo: 12,689 tokens | One line with allowed values | | Honest guidance | 3 of 3 malformed ids said “needs a person” | “retry with X” for fixable errors | | Know the half shown | 27 of 34 tools sent data twice | Equivalent text and structured halves | | No self-noise | 152 of 200 feed events were the agent's own calls | Filter the agent's own activity | ## 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. Overview, before *12,060 tok* Overview, lean *198 tok* List, before *11,776 tok* List, lean *546 tok* Full numbers and how to do it: [how to reduce MCP tool response size](/blog/reduce-mcp-tool-response-size/). Per-app caps: [MCP output limits by agent](/blog/mcp-tool-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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) 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](/blog/error-messages-for-ai-agents/). **See what your tool results do to agents.** We run your users' jobs through Claude Code, Codex and the other apps they use, measure every result and error, and show which ones stall, bloat or mislead the agent. [Test your MCP →](/#contact) ## 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](/blog/mcp-structuredcontent-vs-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](/blog/verbose-validation-errors-tokens/), [How much MCP output is waste](/blog/mcp-context-pollution/), [Next-step hints in results](/blog/next-step-hints-in-tool-results/), [Typed refusals](/blog/agent-refusal-states/). ## Guides in this section - [How to write error messages for AI agents](/blog/error-messages-for-ai-agents/) - [How to reduce MCP tool response size](/blog/reduce-mcp-tool-response-size/) - [structuredContent or text: which half the model sees](/blog/mcp-structuredcontent-vs-text/) - [MCP output limits by agent](/blog/mcp-tool-output-limits-by-agent/) - [The 12,689-token typo](/blog/verbose-validation-errors-tokens/) - [Results that say what to do next](/blog/next-step-hints-in-tool-results/) - [Typed refusals agents can act on](/blog/agent-refusal-states/) Up: [agent-ready tools](/guides/agent-ready-tools/). Method: [how to test an MCP server with real AI agents](/guides/test-mcp-servers-with-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. ## FAQ ### How should an MCP tool format its result for an LLM? Return the smallest result that answers the common question: a summary line (counts, what's next), the few fields agents need, and a cursor or filter for more. Put the same content in the half of the result your users' agent apps actually show the model. ### How should MCP tools report errors? For mistakes the model can fix, return a tool result with isError: true and one line naming the fix, such as the allowed values. The MCP spec says clients should pass these to the model. Keep protocol errors for unknown tools and malformed requests. ### Why are my MCP tool results being refused or truncated? Agent apps cap results. Claude Code refused results over 25,000 tokens and saved them to a file; Codex cut a 67,251-token print. Make the default call small. ### Does the model see structuredContent or text? It depends on the app. In our two-marker test Claude Code showed only structuredContent, OpenCode only text, and Codex both. Keep both halves equivalent, or know which your users' apps read. ### What is the most common result problem? On the server we tested, size: default calls returned tens of thousands of tokens of fields agents didn't need, plus the same data twice. **See what your tool results do to agents.** We run your users' jobs through Claude Code, Codex and the other apps they use, measure every result and error, and show which ones stall, bloat or mislead the agent. [Test your MCP →](/#contact) ## Keep reading - Up[How to make your MCP server or API agent-ready, with proof (guide hub)](/guides/agent-ready-tools/) - Related[How to write error messages for AI agents: before and after, from a production MCP server](/blog/error-messages-for-ai-agents/) - Related[How to reduce MCP tool response size: measured before and after](/blog/reduce-mcp-tool-response-size/) - Related[structuredContent or text: which half of an MCP result the model sees](/blog/mcp-structuredcontent-vs-text/) - Related[MCP output limits by agent: Claude Code, Codex, OpenCode and Grok Build compared](/blog/mcp-tool-output-limits-by-agent/) - Related[Next-step hints: make every tool result tell the agent what to do next](/blog/next-step-hints-in-tool-results/) - Related[Retry, fix the arguments, or ask the human? Refusal states agents can act on](/blog/agent-refusal-states/) - In this guide[The 12,689-token typo: how one validation error can eat an agent's context](/blog/verbose-validation-errors-tokens/) - In this guide[How much of your MCP output is waste? Measuring context pollution in agent runs](/blog/mcp-context-pollution/) - In this guide[Why agents call the same MCP tool twice (13 of 40 runs) and how to stop it](/blog/duplicate-tool-calls/)