Blog / Tool results and errors

How to reduce MCP tool response size: a 46,253-token default list and how to fix it

Agents call your list tool the lazy way: no arguments. Whatever your default returns is what they get, every time. On one production server that was 46,253 tokens for 20 items, too big for Claude Code to accept. Here's how to measure your defaults and cut them down.

Leonid Bugaev · Published 21 Oct 2026

Measure the default call

Most size advice assumes the agent passes a sensible limit. Our recorded calls say otherwise: agents usually call list tools with {}. So the first measurement is the default call, with no arguments, counted in a named tokenizer.

On a 99-tool production MCP server, the main list tool's default returned 20 items:

About 2,300 tokens per item. The same default returned the same size in 3 of 3 snapshot runs. Even a single item cost 3,168 tokens, mostly counts and guidance repeated on every call.

What big results do to agents

• Claude Code refuses them. In 8 live read-only jobs × 5 runs, Claude Code rejected 40 results over its 25,000-token limit in 23 of 40 runs, saved each to a local file, and read it back in chunks: 138 extra read and search calls. Every one of those refusals was this list tool. See MCP output limits by agent.
• Agents skip the work. In lab runs on the same server, agents said the list was too large to pull in one call and skipped judging the items they were asked to review.
• Codex truncates and calls again. On the activity feed, Codex's first raw print of a result (67,251 tokens) was cut, so it called the tool again with the same arguments, in 5 of 5 runs.
• Summary tools get reached for anyway. For “what's the status?”, agents called a 14,517-token overview in 4 of 5 runs to read a few numbers.

Why results get big

How to shrink them

1. Slim items by default. id, name, status, owner, one or two key fields. Offer fields or include, or a get-one tool, for the rest.
2. Small default pages (10–20) with a total and a next-page hint the agent can follow: "showing 10 of 36, next: offset=10". The MCP spec's cursor pagination covers list operations; the same idea works inside tool results.
3. Counts tools for “how many” questions, so agents don't page through lists to count.
4. Summary modes by default on overview tools; full detail on request.
5. Send the data once: full data in structuredContent, a short text summary.
6. Filter noise out of feeds, such as the agent's own calls, unless asked.
7. Never truncate silently. If you cut, say so and say how to get the rest.

{"summary": "36 tasks: 10 open, 5 blocked, 9 in review, 12 done. Showing 10.",
 "items": [{"id": "it008", "title": "Fix login crash on Android", "status": "blocked", "assignee": "u3"}, ...],
 "next": "list_items(offset=10)"}

Before and after on a mock

We tested a lean default on a mock task tracker with synthetic data. Two versions had the same descriptions; the second also had slim defaults, a small overview and short errors:

Accuracy didn't move (each 10/10, 72–100%). Where the agent called the heavy overview, the lean version saved the most: two overview calls returned 80,216 characters in the full version and 944 in the lean one, for both Codex and the small model. Claude Code barely changed because, with good descriptions, it used the small counts tool instead. The lean version also accepted plain dates, so part of the saving is fewer errors; the jobs were short lookups. More in per-model MCP tool surfaces.

Go deeper: Tool results and errors for AI agents, Context pollution, What's in an agent's context window.

How we measured

• Production sizes: recorded responses from a 99-tool production MCP server, 16 Oct 2026, counted in o200k_base (text plus structured content); default-call snapshot repeated 3 times with identical results.
• Agent behaviour: 8 read-only jobs × 5 runs each in Claude Code 2.1.301 and Codex 0.161.0 on the production server, through a read-only allowlist proxy, 16 Oct 2026.
• Mock A/B: synthetic task tracker, 21 tools, Claude Code 2.1.304, Codex 0.161.0 and OpenCode 1.18.34 with a free small model, 5 jobs × 2 runs per cell, 21 Oct 2026. Sizes from the server's own code; run results checked in code and read by hand.
• Limits: one production server; the mock's lean version changed size and error handling together.