---
title: How to Reduce MCP Tool Response Size (Measured)
description: One MCP list call returned 46,253 tokens by default; Claude Code refused it in 23 of 40 runs. How to shrink results: slim defaults, summaries, counts.
canonical: https://spiritroom.app/blog/reduce-mcp-tool-response-size/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/reduce-mcp-tool-response-size/ for agents. Index: /llms.txt

[Blog](/blog/) / [Tool results and errors](/guides/tool-results-and-errors-for-agents/)

# 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

**TL;DR**

- **Measure the default call, not the documented one.** A production list tool's default (no arguments) returned 20 items as 46,253 tokens, about 2,300 per item. Asking for 1 item still cost 3,168.
- **Big results break agents, not just budgets.** Claude Code refused 40 results over its 25,000-token limit in 23 of 40 live runs, saved them to files, and read them back in pieces: 138 extra reads.
- **Summary tools get used for status questions, so keep them small.** Agents reached for a 14,517-token overview in 4 of 5 status runs to read a handful of numbers.
- **Lean defaults held accuracy and cut size 20–60×.** On a mock, a slim default list (546 tokens instead of 11,776) and a small overview (198 instead of 12,060) passed 10/10 in all three models tested, as the full versions did.
- **The recipe:** few fields by default, counts and a summary on top, a next-page hint, details on request, and counts tools for “how many” questions.
[Measure the default call](#measure)[What big results do to agents](#break)[Why results get big](#why)[How to shrink them](#fix)[Before and after on a mock](#test)[How we measured](#how-we-measured)[FAQ](#faq)

## 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:

limit 1*3,168*

Default (20 items)*46,253*

limit 50 (47 items)*110,721*

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](/blog/mcp-tool-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.

**Find out how big your tool results really are.**

We run your users' jobs through Claude Code, Codex and the other apps they use, record every result's size and what the agent did with it, and test leaner defaults against the current ones, with pass rates.

[Test your MCP →](/#contact)

## Why results get big

Causes we found in one production server

| Cause | Example |
| --- | --- |
| Full objects in list items | Every item carried its whole record, about 2,300 tokens each |
| Guidance repeated per call | Counts and advice on every call, 3,168 tokens even for 1 item |
| The same data twice | Text and `structuredContent` both carried the data in 27 of 34 read tools; see [structuredContent or text?](/blog/mcp-structuredcontent-vs-text/) |
| Feeds full of the agent's own activity | In one feed call, 56 of 106 events were the server logging the agent's own tool calls |
| Errors that dump everything | One validation error returned 12,689 tokens; see [error messages for AI agents](/blog/error-messages-for-ai-agents/) |

## 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](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/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:

Default-call sizes, o200k\_base tokens

| Call | Full version | Lean version |
| --- | --- | --- |
| `list_items {}` | 11,776 (all 36 tasks, full objects) | 546 (10 slim + summary + next page) |
| `list_items` for one project | 2,753 | 486 |
| `get_workspace {}` | 12,060 | 198 |

Same jobs, 10 runs per cell (mock, 21 Oct 2026)

| Model | Full: pass · median input | Lean: pass · median input |
| --- | --- | --- |
| Claude Code | 10/10 · 20,293 | 10/10 · 20,249 |
| Codex | 10/10 · 89,101 | 10/10 · 78,126 |
| Small free model (OpenCode) | 10/10 · 20,756 | 10/10 · 17,168 |

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](/blog/per-model-mcp-tool-surfaces/).

**Go deeper:** [Tool results and errors for AI agents](/guides/tool-results-and-errors-for-agents/), [Context pollution](/blog/mcp-context-pollution/), [What's in an agent's context window](/blog/mcp-context-window-usage/).

## 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.

## FAQ

### How do I reduce MCP tool response size?

Return a few fields per item by default, cap the default page at about 10 to 20 items, put counts and a one-line summary at the top, add a next-page hint, and offer details through a fields or include argument or a get-one tool. Measure the default call with no arguments, because that's how agents usually call it.

### What is Claude Code's MCP output limit?

In our live runs, Claude Code refused tool results over 25,000 tokens, saved them to a local file, and had the model read the file in pieces. That happened to 40 results in 23 of 40 runs on one production server, adding 138 local read calls.

### How many tokens should an MCP tool result be?

Small enough that the default call fits comfortably under the smallest limit among your users' apps, which in our runs was Claude Code's 25,000 tokens. In practice, aim for hundreds to a few thousand tokens for a default list.

### Does shrinking tool results hurt agent accuracy?

Not in our mock test. A slim default list and a small overview passed 10 of 10 runs in Claude Code, Codex and a small model, the same as the full-size versions, while using far fewer tokens.

### Why are my MCP tool results so large?

Usually full objects in every list item, long default page sizes, prose explanations repeated per item, the same data sent twice as text and structured content, and feeds that include the agent's own activity.

**Find out how big your tool results really are.**

We run your users' jobs through Claude Code, Codex and the other apps they use, record every result's size and what the agent did with it, and test leaner defaults against the current ones, with pass rates.

[Test your MCP →](/#contact)

## Keep reading

- Up[Tool results and errors for AI agents (guide)](/guides/tool-results-and-errors-for-agents/)
- 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[How much of your MCP output is waste? Measuring context pollution in agent runs](/blog/mcp-context-pollution/)
- Related[Why your MCP server fills the context window, and which agents actually pay for it](/blog/mcp-context-window-usage/)