--- title: How Many MCP Tools Is Too Many? Token Costs in 5 Agents description: The same 99 MCP tools cost +0 tokens up front in Codex and +73,415 on every request in OpenCode 1. Measured in 5 agents, plus a 4-tool vs 99-tool test. canonical: https://spiritroom.app/blog/how-many-mcp-tools-is-too-many/ published: 2026-10-21 updated: 2026-10-21 --- > Markdown version of https://spiritroom.app/blog/how-many-mcp-tools-is-too-many/ for agents. Index: /llms.txt [Blog](/blog/) / [How agents load MCP tools](/guides/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 **TL;DR** - **There's no safe number, because apps load tools differently.** The same 99-tool list (68,286 tokens) added +0 tokens to the first request in Codex, +1,715 in Claude Code, +73,415 in OpenCode 1 and +107,541 in Claude Code with tool search off. - **Eager loading pays on every request.** OpenCode 1 resent all 63,245 tokens of definitions with each model request, about 230k tokens per question in live runs. - **Search-based loading trades tokens for misses.** Codex never found the tools in 8 of 80 live runs (5–19%) and spent about 40k tokens searching before its first call. - **Weight matters more than count.** Two of the 99 tools were about a third of the whole list. - **A start-here tool flattened the difference.** With it, a 4-tool and a 99-tool version of the server both scored 12/12 and 24/24 on picking the right first step (mock). [The short answer](#answer)[What 99 tools cost in each app](#per-app)[Search misses](#misses)[Weight, not count](#weight)[4 tools vs 99](#4-vs-99)[What to do](#what-to-do)[How we measured](#how-we-measured)[FAQ](#faq) ## 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. Codex 0.161.0 *+0* Claude Code 2.1.301 (default) *+1,715* OpenCode 1.18.34 *+73,415* Claude Code, tool search off *+107,541* How each app handled the same 99 tools, 16 Oct 2026 | Agent app | What the model sees first | Up-front cost | Paid again on each request? | | --- | --- | --- | --- | | Codex 0.161.0 (code mode) | No MCP tool names at all; the model searches tool metadata with code | +0 | No; search results enter the history | | Claude Code 2.1.301, tool search on | 113 tool names, about 1,258 tokens, no schemas | +1,715 | Only the definitions it loads (about 573 tokens each) | | Grok Build 1.0.60 | A 189-token note saying which servers exist and how many tools | small | Search returns full schemas of the top 10 hits (4,957 tokens) | | OpenCode 2.0.31 (interactive) | 16 of the 99 tools with one-line descriptions (881 tokens), plus a search function | first request about 5,270 in total | Only what its code prints | | OpenCode 1.18.34 | All 99 definitions (63,245 tokens in its rendering) | +73,415 | Yes, every request | | Claude Code 2.1.301, tool search off or behind a custom API URL | All 99 definitions | +107,541 | Yes, every request | 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](https://dev.to/yahhi/how-many-tools-should-an-mcp-server-have-i-measured-5-to-100-in-claude-code-codex-and-gemini-3hap)). 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. **Find where agents fail on your tools. Measure what fixes it.** Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes. [Test your MCP →](/#contact) ## 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. Mock server, 18 Oct 2026: right first step on job requests, and tokens before the first server call (median) | Setup | Claude Code 2.1.302 | Codex 0.161.0 | | --- | --- | --- | | 99 tools, start-here recipe | 24/24 (86–100%), 6.3k tokens | 24/24 (86–100%), 43.8k tokens | | 4 tools, start-here recipe | 12/12 (76–100%), 4.5k tokens | 12/12 (76–100%), 40.0k tokens | | 99 tools, start-here tool but no hint | 1/24 (1–20%) | 9/24 (21–57%) | 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](/blog/get-instructions-first-24-of-24/). 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](/guides/how-agents-load-mcp-tools/). For a checklist of the other metrics, see [how to measure MCP server quality](/blog/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](https://dev.to/yahhi/how-many-tools-should-an-mcp-server-have-i-measured-5-to-100-in-claude-code-codex-and-gemini-3hap), dev.to, October 2026: synthetic sweep and a survey of published thresholds, including the Cursor 40-tool limit being removed. - [VS Code issue #248021](https://github.com/microsoft/vscode/issues/248021): the 128-tool limit per chat request. - [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp): tool search and `ENABLE_TOOL_SEARCH`. ## FAQ ### Is there a limit on the number of MCP tools? The MCP protocol has no tool limit. Agent apps set their own: VS Code has been reported to cap a chat request at 128 enabled tools, and Cursor's earlier 40-tool limit has reportedly been replaced by on-demand loading. What matters more is how the app loads tools: all definitions on every request, or names first with search. ### How many tokens does an MCP tool definition use? It varies a lot. In a 99-tool production list the average was about 690 tokens per tool (68,286 in total), but two tools made up about a third of the list. Count your own tools/list with a named tokenizer and look at the heaviest tools first. ### Does Claude Code load all MCP tools into context? Not by default. In our capture, Claude Code 2.1.301 with tool search on showed the model tool names only and added 1,715 tokens for 99 tools. With tool search off, or behind a custom API base URL, it loaded every definition and added 107,541 tokens. ### Does Codex load MCP tools up front? No. Codex 0.161.0 in its default code mode added 0 tokens up front: the model searches tool metadata from code. The cost moves to the search, about 40k tokens before the first call in our runs, and the search can miss: 8 of 80 live runs never reached the server's tools. ### Should I split my MCP server into smaller servers? Split if your users' apps load every definition on every request and the list is heavy, or if unrelated jobs compete for the same words. Otherwise, first make tools easy to find (user vocabulary in names and first lines) and give the agent a clear place to start. In our mock test, 4 tools and 99 tools performed the same once a start-here tool was in place. **Find where agents fail on your tools. Measure what fixes it.** Bring your MCP server, CLI or API and the jobs your users need done. We run real agents against them, read every call, and hand back measured gaps and fixes. [Test your MCP →](/#contact) ## Keep reading - Up[How agent apps load MCP tools: what the model sees (guide)](/guides/how-agents-load-mcp-tools/) - Related[Why your MCP server fills the context window, and which agents actually pay for it](/blog/mcp-context-window-usage/) - Related[MCP tool-list token calculator: what your tools cost in Claude Code, Codex and OpenCode](/tools/mcp-token-cost/) - Related[Fewer, bigger tools or many small ones? What a 4-tool vs 99-tool test shows](/blog/consolidate-mcp-tools/) - Related[OpenCode 1 vs OpenCode 2: from a 63k-token tool preload to a 16-tool catalog](/blog/opencode-mcp-tool-loading/)