What you will be able to do
- Explain the two costs of loading too many tool definitions: context consumption and lower tool selection accuracy
- Spot the signs of capability bloat in an agent configuration and in its tool-call metrics
- Reduce a bloated tool set by consolidating overlapping tools and namespacing the rest
Key concept
Capability bloat — An agent is given so many tools, or tools that overlap so much, that the definitions take up context and the model starts picking the wrong tool. More tools do not mean more capability. Past a certain point, each extra tool makes the agent worse at choosing.
1.What a bloated tool set costs
When you configure an agent, it is tempting to connect every server and expose every endpoint, in case the agent needs them. Anthropic's documentation names two separate costs of loading every tool definition up front.
The first is context consumption. Each definition takes up context-window space that the actual task could have used. The Agent SDK documentation says 50 tools can use 10–20K tokens, while the API documentation says a typical five-server MCP setup can consume about 55k. These are estimates for different setups, not a formula. The real cost depends on how many tools you load and how large their definitions are.
The second is selection accuracy. This is the more important cost when you evaluate a configuration. Claude's ability to pick the right tool degrades once you exceed 30–50 available tools. Treat that range as a guide rather than a precise cutoff. Having more tools does not mean the agent can do more, and beyond that range the agent becomes more likely to pick the wrong one.
Both costs come from the same constraint. Anthropic's context-engineering guidance describes *context rot*: as the context fills, the model recalls what is in it less accurately. It describes context as an "attention budget", where every new token depletes it by some amount. Tool definitions spend that budget just like documents and conversation history do. A configuration is bloated when it spends attention on capabilities the current task doesn't need.
Checkpoint 1 of 5· Check yourself
An architect argues that giving an agent 120 tools is harmless, because the context window easily holds all the definitions. What does this argument miss?
Context consumption and selection accuracy are separate problems. A tool set can fit in the window and still make the agent worse at choosing between tools.
“Tool selection accuracy degrades with more than 30-50 tools loaded at once.”Source: code.claude.com
Checkpoint 2 of 5· Exam question
A developer wants to build a code-review agent that must never edit files or run shell commands, even if Claude decides such actions would help, and must not fall back to interactive approval because it runs headless in CI. Which configuration achieves this?
Correct answer: A — Set allowedTools: ["Read", "Glob", "Grep"] with permissionMode: "dontAsk" so listed tools are approved and everything else is denied outright.
- A. Correct. In dontAsk mode, tools pre-approved by allowedTools run, and anything not pre-approved is denied outright without calling canUseTool, giving a fixed, headless-safe tool surface.
- B. Incorrect. This does block Edit, Write, and Bash, but bypassPermissions approves every other tool, including any MCP or future tools, which is broader than the intended read-only scope and not headless-safe by design.
- C. Incorrect. In default mode, unlisted tools fall through to the canUseTool callback, which requires interactive confirmation, defeating the headless requirement.
- D. Incorrect. acceptEdits auto-approves file edits and filesystem commands like rm and mv, which is the opposite of preventing edits, and Bash still prompting does not satisfy a fixed, non-interactive tool surface.
2.Diagnosing bloat in a configuration
Tool count is a rough signal. Ambiguity is a more reliable one. Anthropic calls bloated tool sets "one of the most common failure modes": sets that cover too much functionality or create unclear choices about which tool to use. The guidance gives a simple test. If a human engineer looking at the tool list can't say for certain which tool fits a situation, the agent won't do better.
Overlap matters as much as the total. When tools overlap in function or have a vague purpose, agents get confused about which ones to use. Two tools that both 'search tickets' slightly differently can cause more trouble than ten tools that are clearly distinct.
The second diagnostic is behavioural, and comes from measuring the agent while it runs. Anthropic recommends tracking more than task accuracy: runtime per tool call, the total number of tool calls, total token consumption, and tool errors. The patterns tell you different things:
- Many redundant tool calls suggest that pagination or token-limit parameters need adjusting. - Many invalid-parameter errors suggest that tool descriptions need clarifying or better examples. - Recurring call chains show workflows the agent keeps building by hand. These are candidates for consolidation into one tool.
The platform documentation adds a related point: find out *where* the tokens are going before you pick a remedy. Tool definitions and accumulated tool results both consume context, and they call for different fixes.
Checkpoint 3 of 5· Check yourself
Your agent's tool-call logs show many errors from invalid parameters across a few tools. What does Anthropic's guidance suggest this signals?
Invalid-parameter errors point to unclear tool descriptions. Redundant calls are the pattern that points to pagination or token-limit parameters.
“lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples.”Source: www.anthropic.com
Checkpoint 4 of 5· Check yourself
A support agent is configured with 18 tools, including search_tickets and find_issues. Both are described as 'look up customer problems', and traces show the agent alternating between them for the same request. A reviewer says the set can't be bloated because it is well under 30–50 tools. What is the best assessment?
Overlap and ambiguity cause wrong choices even in small sets. The two lookup tools should be clarified or consolidated so each has a distinct purpose.
“When tools overlap in function or have a vague purpose, agents can get confused about which ones to use.”Source: www.anthropic.com
3.Curating the tool set: consolidate, then namespace
One common way a configuration becomes bloated is mechanical: someone exposes each API endpoint as its own tool. Anthropic names this directly. Tools that merely wrap existing software functionality or API endpoints are a common error, because agents work differently from traditional software. Software can loop through every contact in a list cheaply. An agent that reads a full contact list token by token wastes its limited context.
The recommended approach is to start small. Build a few thoughtful tools aimed at specific high-impact workflows that match your evaluation tasks, and add more from there. A single tool can do several operations behind the scenes, which reduces both the number of tool definitions and the intermediate output in the agent's context.
| Bloated: one tool per endpoint | Consolidated: one tool per workflow |
|---|---|
| list_users, list_events, create_event | schedule_event (finds availability and schedules) |
| read_logs | search_logs (returns only relevant lines plus context) |
| get_customer_by_id, list_transactions, list_notes | get_customer_context (compiles recent, relevant information) |
| list_contacts | search_contacts or message_contact |
Some tools remain separate after consolidation, and an agent can still reach dozens of MCP servers. Namespacing helps here. Group tools under shared prefixes by service (asana_search, jira_search) and by resource (asana_projects_search, asana_users_search). The guidance warns that prefix and suffix naming had non-trivial effects in Anthropic's evaluations, and the effects vary by model. Choose the scheme by evaluation, not by habit.
The platform's context-management guidance also gives a starting point for infrastructure: add tool search once a tool set grows past roughly 20 tools or baseline context usage becomes noticeable.
Checkpoint 5 of 5· Match them up
Match each bloated tool set to the consolidated tool Anthropic suggests instead
Tap a term, then the definition that fits it.
Each consolidated tool handles a whole workflow behind the scenes. This reduces tool count and keeps intermediate output out of the agent's context.
“Instead of implementing a read_logs tool, consider implementing a search_logs tool which only returns relevant log lines and some surrounding context.”Source: www.anthropic.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Exposing every API endpoint as its own tool gives the agent maximum capability.Why is that wrong?
Anthropic names endpoint-wrapping as a common error. A few tools aimed at high-impact workflows reduce tool count and context, and lower the agent's error risk.
Covered in Curating the tool set: consolidate, then namespace
2.Capability bloat is just a raw tool count. A set under the limit can't be bloated.Why is that wrong?
Overlapping or vaguely described tools confuse agents even when there are few of them. Ambiguous decision points are themselves a failure mode.
Covered in Diagnosing bloat in a configuration
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Claude's ability to pick the right tool degrades once you exceed 30–50 available tools.”
↩︎ What a bloated tool set costs“Claude's ability to pick the right tool degrades once you exceed 30–50 available tools.”
↩︎ Key concept“A typical multiserver setup (GitHub, Slack, Sentry, Grafana, and Splunk) can consume ~55k tokens in definitions before Claude does any work.”
↩︎ Prediction - 2.
“Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work.”
↩︎ What a bloated tool set costs“Tool selection accuracy degrades with more than 30-50 tools loaded at once.”
↩︎ Checkpoint - 3.
“as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases.”
↩︎ What a bloated tool set costs“bloated tool sets that cover too much functionality or lead to ambiguous decision points about which tool to use.”
↩︎ Diagnosing bloat in a configuration“If a human engineer can’t definitively say which tool should be used in a given situation, an AI agent can’t be expected to do better.”
↩︎ Diagnosing bloat in a configuration - 4.https://www.anthropic.com/engineering/writing-tools-for-agentsSecondary source
“Tracking tool calls can help reveal common workflows that agents pursue and offer some opportunities for tools to consolidate.”
↩︎ Diagnosing bloat in a configuration“We recommend building a few thoughtful tools targeting specific high-impact workflows, which match your evaluation tasks and scaling up from there.”
↩︎ Curating the tool set: consolidate, then namespace“namespacing tools by service (e.g., asana_search, jira_search) and by resource (e.g., asana_projects_search, asana_users_search), can help agents select the right tools at the right time.”
↩︎ Curating the tool set: consolidate, then namespace“Effects vary by LLM and we encourage you to choose a naming scheme according to your own evaluations.”
↩︎ Curating the tool set: consolidate, then namespace“A common error we’ve observed is tools that merely wrap existing software functionality or API endpoints”
↩︎ Exam trap 1“When tools overlap in function or have a vague purpose, agents can get confused about which ones to use.”
↩︎ Exam trap 2“lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples.”
↩︎ Checkpoint“When tools overlap in function or have a vague purpose, agents can get confused about which ones to use.”
↩︎ Checkpoint“Instead of implementing a read_logs tool, consider implementing a search_logs tool which only returns relevant log lines and some surrounding context.”
↩︎ Checkpoint - 5.
“Tool definitions and accumulated tool_result blocks consume your context window.”
↩︎ Diagnosing bloat in a configuration“Add tool search once your toolset grows past roughly 20 tools or your baseline context usage becomes noticeable.”
↩︎ Curating the tool set: consolidate, then namespace