Expose only tools each role needs

Learning objective

Identify how oversized tool menus cause selection mistakes and distribute tools using least privilege and role-specific access.

Core idea

A tool menu is a set of decisions Claude must make, not a catalogue you must expose in full. Each additional tool brings another name, description, input contract, and possible path through the task. When several tools appear relevant, the agent can choose the wrong operation even when every individual tool works correctly.

Anthropic’s tool-design guidance identifies too many tools and overlapping tools as sources of distraction and inefficient strategies. Design the menu around the specialist’s assignment. A synthesis agent needs to reconcile supplied evidence; unrestricted search gives it an opportunity to abandon synthesis and start an investigation that belongs to another role.

Least privilege means exposing the capabilities the role needs and retaining resource authorization in the implementation. It does not mean giving every agent every tool and writing a stronger instruction to be careful. A role prompt explains the assignment; the tool menu determines which operations the model can request.

How it works

Make tool exposure explicit

For a Messages API workflow, the request’s top-level tools array supplies client-tool definitions. Each definition has a name, description, and input_schema. Construct that array for the role making the request instead of copying the application’s complete tool registry into every inference.

For an Agent SDK subagent, AgentDefinition.tools specifies its tool names. The field is tools in both the Python and TypeScript SDKs. If you omit it, the subagent inherits every tool available to subagents, subject to the documented background-run filtering. An omitted list therefore expresses inheritance, not an intentionally narrow role.

Alternatively, use AgentDefinition.disallowedTools to remove specific tools from an inherited set; mcp__server or mcp__server__* removes every tool from the named MCP server. The Python SDK also spells this field disallowedTools, retaining camelCase to match the wire format.

A document-review specialist can use tools: ["Read", "Grep", "Glob"] in TypeScript, or tools=["Read", "Grep", "Glob"] in Python. This list lets the specialist inspect files without adding Edit or Bash to its menu. The subagent’s description tells the parent when to delegate, while its prompt explains the review criteria. See 1.3.1 for the broader specialist contract.

Do not substitute the parent query’s allowedTools for this restriction. The SDK documentation labels allowedTools in TypeScript and allowed_tools in Python as auto-approval settings. A tool omitted from that approval list can still exist. See 0.6 for availability and permission gates; this lesson’s decision is which capabilities belong in the role’s menu.

Remove ambiguity as well as count

Reducing a menu from eighteen entries to five helps only if the five have distinct jobs. Two tools named get_document and fetch_document still require the agent to infer a difference that might exist only in your implementation. Use the description to explain what each returns, when to choose it, and which tasks it excludes.

Anthropic also recommends namespacing tools by service or resource when their purposes overlap. Names such as policy_search and case_search communicate different evidence domains more directly than two generic search names. These are application-defined examples, not Anthropic built-in tools.

Consolidate operations that form one coherent workflow when that reduces unnecessary intermediate choices. Do not merge unrelated privileges into a catch-all tool merely to make the count smaller. A single admin_action tool can expose more authority than several carefully scoped read operations. Menu size and operation scope must be assessed together.

Evaluate the choices the role actually makes

Use realistic assignments to compare a shared menu with a role-specific menu. Anthropic’s evaluation guidance recommends examining task success, tool calls, invalid parameters, tool errors, and redundant calls. A successful final answer can hide an unnecessary search or an attempted write that another component rejected.

Inspect whether the specialist chooses operations inside its role and whether the returned information supports its decision. If synthesis repeatedly requests search, first ask whether it lacks required evidence or whether search is an unnecessary escape route. Repair the handoff when evidence is missing; remove search when investigation belongs to the coordinator.

The exam guide’s example of eighteen tools versus four or five illustrates decision complexity. It is not an API quota or a universal optimal count. Choose the smallest sufficient menu for the assignment and use observed failures to refine it.

Defer loading when one role needs a large catalog

Anthropic’s tool-search documentation gives the scale at which count alone hurts: Claude’s ability to pick the right tool degrades once more than 30–50 tools are available. Its remedy is on-demand loading. Add a tool search tool, tool_search_tool_regex_20251119 or tool_search_tool_bm25_20251119, to tools, and set defer_loading: true on the definitions that should not load up front. Claude’s context starts with only the non-deferred tools; when it needs another, it searches, and the API expands up to 5 matching definitions per search by default. At least one tool must stay non-deferred. Claude Opus 4.1 and earlier models do not support the tool search tool, and on Amazon Bedrock it is available only through the InvokeModel API, not Converse.

Deferred loading manages context for a large catalog; it is not least privilege. A deferred tool is still one search away from the role that holds it, so remove a tool from the role’s tools array when the role should never call it.

Key distinctions and trade-offs

Role guidance versus capability exposure: AgentDefinition.prompt describes what the specialist should do. AgentDefinition.tools determines the tool set it receives. Use both; a prompt alone leaves irrelevant operations available.

Tool access versus resource authorization: Exposing Read or a custom loader does not establish which documents the caller may read. The operation’s implementation still checks the resource being requested. A small menu can contain a dangerously broad tool; see 2.3.2.

Specialization versus repeated handoffs: Excessively narrow roles can require coordinator involvement for every small question. A bounded cross-role check can remove that friction without exposing a complete research menu; see 2.3.3.

Count versus clarity: Fewer distinct, well-described tools reduce choices. Fewer vague tools move ambiguity into parameters. Evaluate the full operation contract rather than rewarding a lower count alone.

Architecture / decision scenario

A multi-agent research application initially gives its researcher, synthesizer, and evidence reviewer the same eighteen custom tools. Traces show the synthesizer starts fresh searches instead of reconciling the supplied findings, while the evidence reviewer occasionally selects a publishing operation.

The architect constructs separate Messages tools arrays. The researcher receives discovery and document-loading operations. The synthesizer receives the supplied findings in its prompt and one bounded fact-check operation in its tool menu. The evidence reviewer receives evidence-inspection operations. Publishing remains with the coordinator’s approved path. Each role’s descriptions state the relevant evidence domain and expected result.

For a file-based review variant built with the Agent SDK, the architect explicitly assigns AgentDefinition.tools to each specialist. The document reviewer receives Read, Grep, and Glob; it does not inherit the parent’s entire tool set. The parent retains the delegation contract taught in 1.3.1.

The team evaluates both menus on assignments that previously caused mistakes. It inspects inappropriate tool selections and redundant searches alongside final-answer quality. If the narrow menu prevents a legitimate task, the architect adds a specific missing operation or repairs delegation rather than restoring the whole registry. The result is a role-specific capability surface whose boundaries match the work.

Common exam traps

• Treating eighteen versus four or five tools as a published service limit.
• Treating defer_loading: true as access control rather than context management.
• Leaving the full menu available and relying only on a role prompt.
• Omitting AgentDefinition.tools while expecting a restricted subagent.
• Confusing allowedTools pre-approval with tool-set restriction.
• Replacing many narrow tools with one unrestricted administrative tool.
• Giving synthesis agents broad search merely because research agents need it.

Where the exam guide differs

What to remember

Construct tool menus from role responsibilities. Use Messages tools or subagent AgentDefinition.tools to make exposure explicit, and use names and descriptions to separate operations. Evaluate selection mistakes as well as final answers. Least privilege depends on the scope of each operation, not only the number of entries.

Knowledge check

References

• Anthropic, Define tools
• Anthropic, Tool search tool
• Anthropic, Subagents in the SDK
• Anthropic, Configure permissions
• Anthropic, Create custom subagents
• Anthropic, Writing effective tools for agents
• Anthropic, Claude Certified Architect – Foundations Exam Guide