How Many Tools Can an AI Agent Handle? (2026 Data)

There is no single limit, but published guidance clusters between 20 and 50 tools: Anthropic documents degradation past 30–50, OpenAI recommends fewer than 20 per turn. A June 2026 study of a 584-tool catalog measured routing accuracy falling 16–23 points.

TL;DR

• The vendors have published numbers. Anthropic's tool search documentation states that "Claude's ability to pick the right tool degrades once you exceed 30–50 available tools."¹ OpenAI's function calling guide advises aiming "for fewer than 20 functions available at the start of a turn," calling it a soft suggestion.²
• The hard API ceilings are much higher than the useful ones. Gemini accepts up to 128 function declarations per request;³ Anthropic's tool search accepts up to 10,000 deferred tools per request.¹ Neither number tells you where accuracy breaks.
• One measurement uses a real production catalog. Researchers at Superhuman, Inc. evaluated three frontier models against a 110-agent, 584-tool catalog drawn from a deployed enterprise assistant, and found routing F1 on under-specified requests dropped 16–23 percentage points as the catalog scaled.⁴
• Deferred loading helps, but it does not close the gap. The same study found that even with perfect retrieval, an oracle ceiling still dropped about 10 points — a "confusion gap" that better search cannot fix.⁴

What You'll Learn

• The tool-count numbers Anthropic and OpenAI publish, and why they're different kinds of claim
• Why more tools degrade an agent through two separate mechanisms, not one
• What MCP tool definitions actually cost in tokens, using Anthropic's own server-by-server breakdown
• Which platforms actually document a maximum tool count — and why OpenAI's widely-quoted 128 is about to stop being true
• How tool search and defer_loading work, and the token reduction Anthropic measured
• Why tool search improves but does not solve selection accuracy — the confusion gap
• When splitting tools across sub-agents beats shortlisting, and when it doesn't
• When code execution with MCP is the better fix, and the security cost that comes with it
• A concrete way to measure your own agent's tool-selection accuracy instead of guessing

How many tools can an AI agent handle before accuracy drops?

Between roughly 20 and 50 tools, based on the guidance the two largest vendors publish. The two numbers are different kinds of claim, though, and it's worth keeping them apart.

Anthropic's tool search documentation describes an observed failure point: "Claude's ability to pick the right tool degrades once you exceed 30–50 available tools."¹ OpenAI's function calling guide offers a recommendation rather than a measurement — it lists "Keep the number of initially available functions small for higher accuracy" as a best practice, and suggests aiming "for fewer than 20 functions available at the start of a turn at any one time, though this is just a soft suggestion."² Neither page shows the evaluation the number came from, so both are best read as vendor rules of thumb rather than reproducible results.

The gap between the two figures is not necessarily a disagreement. One plausible reading — and this is interpretation, not something either vendor states — is that a raw count is a poor unit of measurement in the first place, because how confusable your tools are matters more than how many there are. Anthropic gestures at this when it names the failure mode directly, citing similar tool names such as notification-send-user versus notification-send-channel as a common source of wrong-tool selection.⁵

So the practical answer to how many tools an AI agent can handle is: treat 20–50 as the range where you should start measuring, not the point where things suddenly break.

Why do more tools make an AI agent worse?

Two independent mechanisms, and they need different fixes. The first is context cost: every tool definition is text that gets injected into the prompt. The second is selection difficulty: more candidates means more chances to pick the wrong one, even when context is not the constraint.

OpenAI states the first mechanism plainly — "callable function definitions count against the model's context limit and are billed as input tokens."² Tool definitions are not free metadata sitting outside the conversation. They occupy the same window your system prompt, conversation history, and tool results are competing for, and you pay input-token rates on them every single request.

The second mechanism is the more interesting half, and it is easy to overlook because it survives every context optimization you throw at it. The June 2026 Superhuman study decomposed the degradation with an oracle analysis: separating the retrieval gap (the model never sees the right tool) from the confusion gap (the model sees the right tool and still picks a different one). Even when the correct tool was guaranteed to be in the candidate set, the oracle ceiling still fell by about 10 percentage points as the catalog grew.⁴ The paper notes the practical confusion gap is likely larger still, because a real retriever surfaces semantically similar distractors, which are harder to disambiguate than the random ones used in the oracle setup.⁴

That distinction matters for what you do next. Context bloat is solved by loading fewer definitions. Confusion is solved by making your tools more distinguishable — different names, sharper descriptions, or merging tools that overlap.

How many tokens do MCP tool definitions actually consume?

About 55,000 tokens for a realistic five-server setup — though the per-tool cost varies widely. Anthropic published a server-by-server breakdown:⁵

Fifty-eight tools consume approximately 55K tokens before the conversation even starts.⁵ Anthropic's documentation uses the same setup and the same ~55k figure.¹ Add Jira — roughly 17K tokens on its own — and the overhead climbs toward six figures.⁵ Anthropic's own internal worst case: "we've seen tool definitions consume 134K tokens before optimization."⁵

Note the spread inside that table: Slack contributes ~21K tokens from 11 tools (roughly 1,900 each) while Sentry contributes ~3K from 5 (roughly 600 each). Anthropic doesn't explain the difference, but whatever drives it — schema size, parameter counts, description length — the practical implication is the same: token cost per tool varies by more than 3× across real servers, so a raw tool count tells you little about what your definitions actually cost. Measure the tokens.

Tool definitions are also only half the context story — intermediate tool results accumulate too. Anthropic's example of a two-hour meeting transcript passing through context twice puts that at an additional 50,000 tokens for a single workflow.⁶ If you're managing an agent's context budget more broadly, our walkthrough of Claude's memory tool and context-editing APIs covers the result side of that equation.

What is the maximum number of tools each API allows?

Where a ceiling is documented at all, it sits far above the point where accuracy degrades — so treat these as guardrails, not targets.

Two caveats on that table. The OpenAI row is the one most often quoted as "OpenAI's 128-tool limit," but it belongs to the Assistants API, which OpenAI has deprecated — its own documentation states the API "will shut down on August 26, 2026," about five weeks after this post.⁷ OpenAI's current function calling guide does not publish an equivalent hard ceiling; it gives the sub-20 recommendation instead.² If you're reading a 2024-era article that cites 128 as OpenAI's tool limit, check which API it means.

The second caveat matters more. The gap between any of these ceilings and the 20–50 accuracy range is the whole point. A request with 128 function declarations is a perfectly valid API call that will be accepted, billed, and answered — and it may still route to the wrong tool. Passing schema validation is not the same as being usable.

Anthropic's 10,000-tool ceiling comes with a structural requirement worth knowing: at least one tool must have defer_loading: false, normally the tool search tool itself. A request where every tool is deferred returns a 400 error.¹

What is tool search, and how much does it reduce tokens?

Tool search defers most tool definitions out of the initial context and loads only what a given request needs — Anthropic measured an 85% token reduction. Instead of injecting all definitions up front, you send the full catalog to the API but mark most entries defer_loading: true. Claude sees only the search tool plus your non-deferred tools, then searches when it needs more.¹

{
  "tools": [
    { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" },
    {
      "name": "github_create_pull_request",
      "description": "Create a pull request in a GitHub repository",
      "input_schema": { "type": "object", "properties": { "repo": { "type": "string" } } },
      "defer_loading": true
    }
  ]
}

Anthropic's published breakdown for a 50+ tool MCP setup: the traditional approach consumes ~77K tokens of context before any work begins, while with tool search the search tool costs ~500 tokens and the 3–5 tools discovered on demand cost ~3K, for a total of ~8.7K — which Anthropic says preserves 95% of the context window.⁵ Anthropic separately characterises the saving as "an 85% reduction in token usage,"⁵ and its documentation repeats that figure: tool search "typically reduces this by over 85 percent, loading only the 3–5 tools Claude needs for a given request."¹ (The two framings don't reconcile exactly — 8.7K against 77K is nearer 89% — so treat 85% as the vendor's conservative headline rather than a figure derived from those two numbers.)

Accuracy improved too, on Anthropic's internal MCP evaluations: Opus 4 went from 49% to 74%, and Opus 4.5 from 79.5% to 88.1%, with tool search enabled.⁵

Two status details are easy to get wrong. Tool search launched in beta on November 24, 2025 behind the advanced-tool-use-2025-11-20 header;⁵ Anthropic's documentation now describes it as generally available on the Claude API.¹ And this is not a single-vendor idea — OpenAI ships its own tool_search, supported on gpt-5.4 and later models.² The academic version predates both: the RAG-MCP paper, published May 6, 2025, proposed retrieving relevant tools before invoking the model and reported cutting prompt tokens by over 50% while more than tripling tool selection accuracy, from a 13.62% baseline to 43.13%.⁸

For MCP servers specifically, you set deferral once on the toolset rather than per tool:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": { "defer_loading": true },
  "configs": { "search_files": { "defer_loading": false } }
}

Anthropic recommends keeping your 3–5 most frequently used tools non-deferred so common operations don't pay for a search round-trip first.¹ Deferred tools are also excluded from the system-prompt prefix, so prompt caching survives — though a tool marked defer_loading: true cannot also carry cache_control, which returns a 400.¹

Does tool search fix tool-selection accuracy?

It closes the retrieval gap but not the confusion gap, and the difference is measurable. This is where the vendor narrative and the independent measurement diverge — worth understanding before you architect around deferred loading.

The Superhuman study compared four approaches across 51–584 tools, using GPT-5.4, GPT-5.1, and Claude Sonnet 4.5 as routing models. At full scale, with GPT-5.4 routing, tool-level embedding shortlisting reached 52.5%, platform tool search reached 50.3%, and flat routing with no shortlisting reached 42.1%.⁴ Shortlisting clearly wins.

But the ceiling it wins against is still far from where you started. Flat routing fell from 58.2% F1 at 51 tools to 42.1% at 584, and the decline was recall-driven: precision slipped from 68% to 60% while recall dropped more than twice as fast, 55% to 37%.⁴

To rule out query mix as the explanation, the authors re-scored a fixed cohort of 731 queries present at every scale point. That cohort degraded by a comparable 14.9 points (58.2% to 43.3%), which the paper reads as confirmation that the decline tracks catalog growth rather than shifting query composition.⁴

The paper's conclusion is explicit that retrieval is not a complete answer: the confusion gap of at least 10 points "is not recoverable by retrieval alone. Shortlisting narrows the candidate set but the router still confuses semantically similar tools."⁴

One finding deserves particular attention because it cuts against an intuitive configuration choice. In the same study, a BM25 shortlister performed worse than no shortlisting at all — 32.8% versus 42.1% at 584 tools, and below flat routing at every scale point tested. The stated reason is that enterprise productivity tools share vocabulary across agents, which makes lexical matching ineffective.⁴

Be careful how far you carry that result. The BM25 the paper tested was its own shortlisting implementation at k=20, evaluated as a separate condition from the "platform tool search" row — so this is evidence about lexical retrieval as a technique, not a benchmark of any vendor's specific search variant. Anthropic does offer a BM25 tool search variant alongside its regex one,¹ and the paper gives you a reason to evaluate the lexical option rather than assume it, particularly for catalogs where many tools describe similar actions on different objects. One study, one domain — measure it against your own tools before you ship it.

An earlier evaluation points the same way on retrieval being the bottleneck. LiveMCPBench, published in August 2025, stress-tested 95 real-world tasks across 70 servers and 527 tools and found that "retrieval errors account for nearly half of all failures."⁹ In that benchmark, Claude Sonnet 4 reached 78.95% task success while most of the 12 models tested landed at 30–50%.⁹ The model lineup has moved on since, but the failure distribution — retrieval, not reasoning — is the durable finding.

Should you split tools across multiple agents instead?

Sometimes — but the measured advantage over flat shortlisting is smaller than the architecture cost suggests. Splitting a large catalog into specialist sub-agents behind a router is the intuitive fix, and orchestration frameworks make it easy to reach for.

The Superhuman data complicates that intuition. At 584 tools, the pack-level approaches converged tightly: platform tool search reached 50.3%, pack-level embedding 49.1%, and hierarchical LLM routing 47.9% — all within 2.4 points of each other.⁴ Meanwhile tool-level retrieval consistently outperformed every pack-level approach, including hierarchical LLM routing.⁴ Grouping tools into agents and routing between agents did not beat simply retrieving the right individual tools.

That doesn't make sub-agents useless. They buy things retrieval doesn't: separate system prompts, independent permission scopes, isolated context windows, and the ability to give each specialist its own model tier. If your reason for splitting is governance or cost control, the case stands. If your reason is purely routing accuracy, this data suggests you would get more from a good tool-level retriever and sharper tool descriptions than from an agent hierarchy.

Worth noting how the surrounding ecosystem has grown, since it shapes what lands in your catalog: an analysis of 177,436 agent tools published on public MCP server repositories between November 2024 and February 2026 found software development accounts for 67% of all agent tools and 90% of MCP server downloads, with the share of "action" tools rising from 27% to 65% of usage over the sample period.¹⁰ Those are ecosystem-wide figures rather than measurements of any single agent, but the direction matters when you're deciding what to connect: the tools available to bolt on are increasingly ones that do things rather than just read them, which raises the cost of a wrong-tool call.

When is code execution with MCP the better fix?

When your problem is intermediate results rather than tool definitions. Tool search reduces the cost of having many tools. Code execution reduces the cost of using them, by letting the model write a program that calls tools and processes results in a sandbox, returning only the final output to context.

Anthropic reports that presenting MCP servers as a code API on a filesystem — letting the agent read only the tool files it needs — took one workflow from 150,000 tokens to 2,000, a 98.7% saving.⁶ For Programmatic Tool Calling, the API-level feature built on the same idea, Anthropic's internal testing reports average token usage dropping from 43,588 to 27,297 on complex research tasks (a 37% reduction) and GAIA benchmark performance rising from 46.5% to 51.2%.⁵ All of these are vendor-reported figures from Anthropic's own evaluations, not independent replications.

The security trade-off is real and comes from both directions. Anthropic's own post warns that "running agent-generated code requires a secure execution environment with appropriate sandboxing, resource limits, and monitoring."⁶ A February 2026 academic study of MCP design choices is blunter: it confirms code-execution MCP "significantly reduces token usage and execution latency" but "introduces a vastly expanded attack surface," identifying sixteen attack classes across five execution phases — including exception-mediated code injection and unsafe capability synthesis — and proposing containerized sandboxing plus semantic gating as mitigation.¹¹

So the decision rule is not "code execution is better." It's: if tool definitions are your token problem, defer them; if tool results are your token problem, execute in code and accept that you now own a sandbox. Given how much MCP's own security surface has shifted lately — see our breakdown of the stateless MCP protocol overhaul and enterprise authorization — that second option is a real infrastructure commitment, not a config flag.

How do you measure your own agent's tool-selection accuracy?

Build a labeled set of representative requests, record which tool the agent actually called, and score it as the catalog grows. None of the numbers above — vendor thresholds included — can tell you where your catalog breaks, because none of them were measured on your tools.

The Superhuman methodology is a good template because it's reproducible at small scale. They evaluated at fixed scale points — 10, 20, 30, 40, 60, 80, 100, and 110 agents, spanning 51 to 584 tools — so degradation could be attributed to catalog size rather than task difficulty, and validated the synthetic findings against 1,435 human-labeled production utterances scored by three annotators. On real traffic, the shortlisting recovery replicated at +10–17 points, though absolute performance ran 10–15 points lower than in the synthetic setup.⁴

The transferable pieces are: hold the query set constant while varying only catalog size, include under-specified requests (that's where degradation concentrates), and validate against real traffic because synthetic evaluations run optimistic.

A minimal harness looks like this:

# tool_routing_eval.py — score tool selection as the catalog grows
CASES = [
    {"utterance": "file a bug about the login 500s", "expected_tool": "jira_create_issue"},
    {"utterance": "who's on call right now?",        "expected_tool": "pagerduty_get_oncall"},
    # ...at least a few dozen, weighted toward under-specified phrasing
]

def score(catalog_size: int) -> float:
    hits = 0
    for case in CASES:
        called = run_agent(case["utterance"], tools=catalog[:catalog_size])
        hits += int(called == case["expected_tool"])
    return hits / len(CASES)

for n in (10, 25, 50, 100, len(catalog)):
    print(f"{n:>4} tools -> {score(n):.1%}")

Log the wrong answers, not just the score. If failures cluster on pairs of similarly-named tools, you have a confusion problem and shortlisting won't save you — rename and merge instead. If failures are cases where the right tool never entered the candidate set, you have a retrieval problem, and deferred loading or embedding shortlisting is the correct lever. Instrumenting this is much easier if your agent already emits spans per tool call; our guide to tracing Claude agent tool calls with OpenTelemetry covers that plumbing. And if you want to build the embedding-based shortlister that scored highest in the Superhuman comparison, a Postgres-backed vector store with pgvector is a reasonable place to start.

Bottom line

The tool count is a proxy, and a weak one. Anthropic's 30–50 and OpenAI's sub-20 are useful trailheads,¹² but the number worth internalizing is the 16–23 point degradation the Superhuman team measured — because it came from a controlled experiment on a catalog drawn from a real deployed assistant, and because the same team then validated their recovery findings against 1,435 human-labeled utterances from live traffic.⁴ Vendor guidance tells you roughly where to look; that study shows what the curve actually does.

Three next steps, in order of payoff:

1. Count your tokens before you count your tools. Sum your tool definitions. If they exceed 10K tokens, Anthropic's own guidance says you're a tool search candidate.¹
2. Audit for confusable pairs. Any two tools whose names differ only by a noun are a routing failure waiting to happen.⁵ Rename or merge them — the measured confusion gap says retrieval alone won't close it.⁴
3. Measure before you architect. Run the scale-point evaluation above. If your failures are retrieval failures, defer loading. If they're confusion failures, fix your tool surface — and note that Anthropic's docs suggest consistent namespacing (github_, slack_) so one search matches a whole group.¹

The agent-tooling ecosystem is still moving fast in this area — related shifts in agent memory architectures are attacking the same underlying constraint from the context side.