Blog / How agents load MCP tools

How many MCP tools is too many? Real token costs across five agents (2026)

Ninety-nine tools, 68,286 tokens of definitions. In one agent app that added nothing to the first request; in another it added 73,415 tokens to every request. Meanwhile Codex missed the tools entirely in 8 of 80 live runs. The useful question isn't how many tools. It's what each app does with them.

Leonid Bugaev · Published 21 Oct 2026

The short answer

Count is the wrong unit. What an MCP tool list costs, and whether agents find the right tool in it, depends on three things: how many tokens the definitions take, how each agent app loads them, and whether the words in your names and descriptions match what users ask for. Advice you'll find online ranges from “under 20 tools” to “128 is the cap”, but none of those numbers says which app your users run.

So we measured one real list: a 99-tool production MCP server, 68,286 tokens of definitions (o200k_base, compact JSON), in five agent configurations.

What 99 tools cost in each agent app

We captured the first request each app sent to its model for the prompt “say hi”, once with the server connected and once without, and stopped it before any model ran.

Up-front deltas use each app's own token count and are single runs. Grok Build and OpenCode 2 rows describe the captured first request rather than a with/without delta.

The eager-loading cost is real money. In 40 live OpenCode 1 runs on eight read questions, the app averaged 3.7 model requests per question, so about 230k tokens of tool definitions per question, and 341,615 input tokens per question overall by its own count. Claude Code and Codex averaged about 222k and 221k on the same questions.

Watch for configuration traps. Claude Code switched tool search off when it ran behind a custom API base URL, such as a gateway or proxy, and loaded every definition. Setting ENABLE_TOOL_SEARCH=true turned it back on (143,357 → 22,446 first-request tokens in our check). If your users run Claude Code through a company gateway, they may be in the expensive row without knowing it.

The catch with search: agents can miss your tools

Search keeps the context small, but it adds a new failure: the search has to find your tool. On the same production server, in live read-only runs:

• Codex never reached the server's tools in 8 of 80 runs (5–19%). It said no connection was available and tried a browser instead. The server had listed all 99 tools.
• Claude Code found them in 40 of 40 runs (91–100%) in the first round.
• Codex's first broad search returned 56,619 tokens of tool metadata, which it cut to 11,244 before the model saw it. In a controlled test it spent about 40k tokens before its first call to the server, whatever the server did.

A synthetic sweep published this month, with 5 to 100 invented file tools, found no accuracy loss on frontier models and concluded that names decide how much the model reads under deferred loading (dev.to, October 2026). Our production list adds the other half: a real tool list in real apps, where the search sometimes never got there. Our runs can't say how much of that was the tool wording and how much the app's search.

Weight, not count

The 99 tools averaged about 690 tokens each, but the average hides the problem. Two tools made up about a third of the whole list, because their descriptions carried a full query grammar. In an eager-loading app, those two tools were paid for on every request, by every user, whether or not the job touched them.

So before cutting tools, sort them by size. Moving reference material out of the two heaviest descriptions (into a playbook the agent fetches when it needs it) saves more than deleting twenty small tools.

4 tools vs 99 tools: what changed

In a controlled test we built a 4-tool version of the same server and compared it with the full 99 tools. Both had the same start-here tool, get_instructions, with a hint telling the agent to call it first.

Once the agent knew where to start, the number of tools stopped mattering for getting the job started. The small server only saved tokens. Without the hint, the agents went straight to whichever of the 99 tools looked relevant. These are mock results: they show how agents start a job, not how well they finish it.

What to do instead of picking a number

1. Measure your tool list in tokens. Count tools/list as compact JSON with a named tokenizer, and sort tools by size.
2. Find out which apps your users run, and how each loads tools. If any of them load everything on every request, the total size is a per-request bill. If they search, discovery is your risk.
3. Slim the heaviest tools first. Move long reference text out of descriptions and into a playbook tool.
4. Make tools findable. Put the words users say in tool names and in the first line of each description; test paraphrases of the same job.
5. Give the agent a start-here tool and say so in the server instructions. See make the agent read your playbook first.
6. Re-measure on every release of your server and of the apps. OpenCode 1 and OpenCode 2 load the same list in completely different ways.

For the full per-app picture, see how Claude Code, Codex, Grok and OpenCode load MCP tools. For a checklist of the other metrics, see how to measure MCP server quality.

How we measured

• Tool list: the tools/list of a 99-tool production MCP server, recorded 16 Oct 2026, counted as compact JSON with o200k_base.
• Up-front cost: for each app, the first model request for “say hi” with and without the server, captured before any model ran. Codex, Claude Code and OpenCode 1 deltas are each app's own usage figures, single runs (the Codex control repeated identically in 4 of 5 runs). Grok Build and OpenCode 2 figures are o200k_base counts of the captured request.
• Live runs: 8 read-only questions × 5 runs per round through a proxy that only forwarded read tools; Codex and Claude Code two rounds (80 runs), OpenCode 1 one round (40). 0 write attempts.
• 4 vs 99: a local mock serving the same 99 definitions or a 4-tool subset, 232 runs on 18 Oct 2026; ranges are 95% Wilson intervals, somewhat optimistic because repeat runs of the same prompt were often identical.
• Not yet measured: a sweep across 10, 25, 50 and 100 real tools in each app. We'll update this page with it.

Sources

• Spirit Room captures and live read-only runs, 16 Oct 2026; controlled mock experiment, 18 Oct 2026 (see How we measured).
• How many tools should an MCP server have? I measured 5 to 100, dev.to, October 2026: synthetic sweep and a survey of published thresholds, including the Cursor 40-tool limit being removed.
• VS Code issue #248021: the 128-tool limit per chat request.
• Claude Code MCP documentation: tool search and ENABLE_TOOL_SEARCH.