Evaluate tool/agent configuration for capability bloat
Recognize when an agent carries more tools or capabilities than its role needs, explain why that degrades tool selection and widens the blast radius, and fix it by removing, consolidating or scoping tools rather than logging, confirming or prompting around them.
Key points
- 1
Capability bloat has two costs: the model chooses among overlapping tools less accurately, and every tool definition (name, description, schema) is sent as input tokens on every request, so a bloated toolset adds latency and cost even when unused.
- 2
Anthropic's guidance is to build a few thoughtful tools targeting high-impact workflows rather than wrapping every API endpoint. Too many or overlapping tools distract agents from efficient strategies.
- 3
Consolidate fixed multi-step workflows into one tool (for example
schedule_eventinstead oflist_users+list_events+create_event), and namespace tools by service (crm_contacts_search,tickets_contacts_search) so similar tools are distinguishable. - 4
Least privilege (official sample 1): if a role only reads tickets and drafts replies, remove refund and delete tools from that role's configuration. Logging is detective and a confirmation prompt is compensating; neither removes unnecessary privilege. Model size is unrelated to authorization scope.
- 5
When one agent serves several roles, build the
toolsarray per request from the authenticated caller's role instead of sending the union of every role's tools. - 6
MCP connector: an
mcp_toolsetenables every server tool by default. Prefer an allowlist (default_config: { enabled: false }plus explicitconfigs) for read-only or narrow assistants; a denylist leaves tools the vendor adds later enabled until someone notices. - 7
Pair tool-list scoping with credential scoping: connect MCP servers with tokens scoped to the access the role needs, so a tool that becomes visible unexpectedly still cannot act beyond the credential.
- 8
Agent SDK:
allowedToolspre-approves listed tools but does not remove others; unlisted tools fall through to the permission mode, andbypassPermissionsapproves them. To take a capability away, put its bare name indisallowedTools, which strips the definition from the request and holds in every mode. - 9
Claude Code: a bare-name
denyrule (for exampleBash) removes the tool from Claude's context; scoped rules such asBash(rm *)keep the tool but block matching calls. - 10
When a large tool catalogue must remain reachable, load core tools eagerly and mark rarely used tools
defer_loading: truebehind the tool search tool, rather than putting every definition in every request. - 11
Prompt-level fixes ("never use tool X", "you are talking to an applicant") are probabilistic and are the classic distractor; a capability that should not exist for a role must be removed from the configuration.
- 12
Audit toolsets periodically: tools never called in production, near-duplicate descriptions and write tools in read-only assistants are the signs of bloat.
Read the source
Test yourself on Evaluate tool/agent configuration for capability bloat
Ten questions, with the answer and explanation after each one.