What you will be able to do
- Explain why a smaller, role-specific tool set gives more reliable tool selection than one large shared set
- Recognise how an out-of-role tool gets misused, and remove it rather than prompt around it
- Configure a subagent's tools and disallowedTools fields and predict the tool set that results
- Replace a generic capability with a constrained one, and add a narrow cross-role tool without reopening the whole tool set
- Choose between tool_choice auto, any and forced tool selection, and force a specific tool on the first request before returning to auto in follow-up turns
Key concept
Scoped tool access — Each agent gets the tools its role needs and nothing more, plus at most a few narrow tools from other roles for needs that come up often. Anything outside that set is left off the agent's tool list, so the agent can't choose it.
1.Why a smaller tool set gives better tool selection
Anthropic's guidance on multi-agent systems lists three situations where splitting work across agents reliably pays off. One of them is about tools: splitting helps when specialization improves tool selection or task focus. The same article is blunt about everything else. Outside those situations, the cost of coordinating agents usually outweighs the benefit. Specialization has a price, so on the exam, justify it by better tool selection or task focus, not by a diagram that looks tidier.
The exam guide states the principle directly: giving an agent access to too many tools degrades tool selection reliability by increasing decision complexity. Its illustration is an agent choosing from 18 tools against one choosing from 4 or 5. Every tool in the list is an option the model weighs on every turn, so each extra tool adds to the decision even when each tool is individually well described. Cutting the list down removes options the role never needs, and the ones left are easier to tell apart. The sources in this lesson don't publish the 18-versus-5 figures, so treat them as the exam's illustration of the principle rather than a measured threshold.
What the sources do document is how you act on the principle. Claude Code names enforcing constraints by limiting which tools a subagent can use as a core reason to create a subagent at all. Its built-in Explore and Plan subagents come with a reduced set: read-only tools, with Write and Edit denied. Anthropic's tool-design post makes the same point from the tool author's side. One of its key principles is choosing which tools to implement, and which not to. Fewer, better-chosen tools is the design goal on both sides: the tool author decides what exists, and the agent designer decides which agent sees it.
2.How an out-of-role tool gets misused
Anthropic's tool_choice cookbook includes a small, deliberately rigged demonstration. A sentiment-analysis function gets two tools, print_sentiment_scores and calculator, and tool_choice is left on auto. The function is then given a tweet that happens to contain some arithmetic: "I love my cats! I had four and just adopted 2 more! Guess how many I have now?"
Claude called the calculator with num1 = 4 and num2 = 2 and never scored the sentiment. The cookbook admits the setup was built to fail, but the failure is exactly the one the exam describes. A tool unrelated to the agent's job is sitting in its list, and an input that looks relevant pulls the model toward it.
A synthesis agent that holds a web-search tool is the same situation at a larger scale. Nothing in its role calls for new searches, but the tool is there, and a gap in its draft can look like a reason to use it. The fix that doesn't depend on the model behaving well is to take the tool away. The Agent SDK docs describe tool restriction as reducing the risk of unintended actions. Their doc-reviewer example gets only Read and Grep, so it can analyze documentation but never accidentally modify it. The guarantee comes from what's missing from the list, not from an instruction in the prompt.
3.Configuring each subagent's tool set
Scoped tool access is the practice of giving agents only the tools needed for their role, with limited cross-role tools for specific high-frequency needs. The first half is the allowlist you write for each subagent, covered here. The second half, the narrow cross-role tool, is covered in the last section. In both cases the tool set is something you configure explicitly, so start from what the role does and list only the tools that work needs.
In Claude Code, you set a subagent's tools in its definition file. The frontmatter below creates a code-improver agent that can find and read files but can't write them:
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---The Agent SDK's AgentDefinition has the same pair of fields. tools is an allowlist. disallowedTools removes tools from the set, and it also accepts MCP server patterns such as mcp__server__*, which strip every tool from that server. Scoping mistakes usually come from how the two fields combine:
| Fields set | Tool set the subagent gets |
|---|---|
| Neither | Every tool available to subagents |
| tools only | Only the listed tools |
| disallowedTools only | Every parent tool except the listed ones |
| Both | disallowedTools wins: a tool listed in both is removed |
The first row catches people out. Leaving tools out doesn't mean "no tools". It means the subagent inherits the full set. For a specialist, write the allowlist explicitly. The SDK's own example shows the split in practice: a code-reviewer gets Read, Grep and Glob, while a test-runner gets Bash, Read and Grep, because running tests needs a shell and reviewing code does not. Managed Agents offers the same starting-from-nothing option: set default_config.enabled to false, then turn on only the tools the role needs.
{
"type": "agent_toolset_20260401",
"default_config": { "enabled": false },
"configs": [
{ "name": "bash", "enabled": true },
{ "name": "read", "enabled": true },
{ "name": "write", "enabled": true }
]
}4.Replacing a generic tool with a constrained one
Removing a tool is one lever. Narrowing it is the other. The exam guide's example replaces a generic fetch_url with a load_document tool that checks that the URL really points to a document. The sources here don't show that particular tool, but they apply the same idea to built-in web tools. In Managed Agents, you can set allowed_domains on web_fetch so it can reach only the listed hosts. If the agent requests a URL outside those lists, the call doesn't quietly succeed. It returns an error result to the agent, with the error code url_not_allowed. Claude Code permission rules do the same thing for its own tool: WebFetch(domain:example.com) matches by domain.
The constrained version keeps the capability the role actually needs, such as reading documents from approved places, and drops the open-ended part that invites misuse. Because a rejected call comes back as an error the agent can read, the agent learns why the call failed instead of getting results it shouldn't have.
Sources7
5.Narrow cross-role tools, with complex cases routed through the coordinator
Strict scoping has a cost. Sometimes a specialist really does need a capability that belongs to another role, and needs it often. Sending every one of those requests back through the coordinator is expensive. Anthropic measured multi-agent implementations using roughly 3–10x more tokens than a single agent for the same task, mostly from duplicated context and handoffs. The exam guide's answer is to give the synthesis agent a narrow verify_fact tool for the frequent, simple check, and to send anything more involved back through the coordinator, which decides which specialist takes it.
The sources don't describe this pattern by name, but they provide the building blocks. Because tools is an explicit allowlist, adding one narrow cross-role tool is a one-line change, and everything else stays excluded. Handing work to another agent is itself a tool. In Claude Code, the rule Agent(Explore) matches a subagent type, and denying the Agent tool stops Claude from delegating at all. So which agent can route work to which is also something you configure, not something you hope for.
A classification subagent must always emit a structured label using one of its provided tools (e.g. tag_urgent, tag_normal, tag_spam) and must never return free-text commentary instead of a call, though which specific tag applies depends on the message content. Which tool_choice setting guarantees this behavior?
Correct answer: A — tool_choice: {"type": "any"}, which requires the model to call one of the provided tools without pinning it to a specific one
- A. Correct. "any" tells the model it must use one of the provided tools without forcing a particular one, guaranteeing a structured tool call while still letting the model pick the tag that matches the message.
- B. Incorrect. "auto" leaves the choice of calling a tool at all up to the model, which does not guarantee a structured tag is always produced, undermining the requirement for consistent structured output.
- C. Incorrect. Forcing a single named tool would apply the same tag on every message regardless of content, which contradicts the need for the correct tag to vary by message.
- D. Incorrect. "none" blocks tool calls entirely, so the model could only respond in prose, which is the opposite of the required structured-output guarantee.
6.tool_choice: auto, any and forcing a specific tool
Scoping decides which tools an agent can see. tool_choice decides how it must use them on a given request. The default is {"type": "auto"}: Claude determines on each turn whether to call a tool or respond directly. It calls a tool when the request maps to that tool's described capability and the answer isn't already in context, and it answers directly for stable knowledge and conversational turns. The docs note that you can nudge this boundary from the system prompt, with a line such as "Always call a tool first before responding." But if you need a tool call rather than a suggestion, they tell you to set tool_choice instead of relying on prompting.
| tool_choice | What Claude does |
|---|---|
| {"type": "auto"} | Decides whether to call any provided tool or respond with text (the default) |
| {"type": "any"} | Must call one of the provided tools, but picks which one |
| {"type": "tool", "name": "..."} | Must call the named tool |
Forced selection is the fix for the rigged sentiment example from earlier. Once the cookbook sets type to tool and supplies the tool name print_sentiment_scores, every prompt, including the tweet with the arithmetic in it, calls print_sentiment_scores. The exam guide's version of the pattern is a pipeline where extract_metadata must run before any enrichment tool. Force it on the first request. tool_choice is a parameter on each request, so the follow-up turns are yours to shape: your code runs the forced tool, sends its output back in a tool_result block, and the next request can drop the forced choice and return to auto so Claude picks among the enrichment tools itself. The tool-use overview shows that round trip with the default setting on both requests; a forced first step changes only the first request's tool_choice.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
# Ask for at most one tool call per turn.
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)The any option sits between the two. It guarantees a tool call without naming the tool. The cookbook's example is an SMS chatbot whose only channel to the user is a send_text_to_user tool, alongside a get_customer_info lookup. With tool_choice set to any, the bot always calls one of those tools and never returns a plain text response, which would be lost because nothing would deliver it. Even a gibberish message still produces a tool call, in that case a text asking the user to rephrase. Use any whenever conversational text is not an acceptable outcome, and use a forced tool when one specific tool must run.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Giving an agent extra tools is harmless: a well-prompted agent simply ignores the ones it doesn't need.Why is that wrong?
An available tool can be selected, and the cookbook shows an irrelevant calculator being called on a sentiment task. Restricting the tool set is what reduces the risk of unintended actions.
Covered in How an out-of-role tool gets misused
2.If you leave the tools field out of a subagent definition, the subagent gets no tools.Why is that wrong?
Leaving it out means the subagent inherits every tool available to subagents. A specialist needs an explicit allowlist.
Covered in Configuring each subagent's tool set
3.When a tool appears in both tools and disallowedTools, the allowlist wins and the subagent keeps it.Why is that wrong?
disallowedTools takes precedence, so the tool is removed.
Covered in Configuring each subagent's tool set
4.Setting tool_choice to any makes Claude call the one tool you have in mind.Why is that wrong?
any only guarantees that some provided tool is called; Claude still picks which. To force a particular tool you set type to tool and supply its name.
Covered in tool_choice: auto, any and forcing a specific tool
5.A strong system-prompt instruction is enough to guarantee that Claude calls a tool before answering.Why is that wrong?
Prompting steers the auto boundary but does not guarantee a call. When a tool call is required, the docs say to set tool_choice rather than rely on prompting.
Covered in tool_choice: auto, any and forcing a specific tool
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“when specialization improves tool selection or task focus”
↩︎ Why a smaller tool set gives better tool selection“Outside these situations, the coordination costs typically exceed the benefits.”
↩︎ Why a smaller tool set gives better tool selection“multi-agent implementations typically use 3-10x more tokens than single-agent approaches for equivalent tasks”
↩︎ Narrow cross-role tools, with complex cases routed through the coordinator - 2.https://code.claude.com/docs/en/sub-agentsOfficial docs
“Enforce constraints by limiting which tools a subagent can use”
↩︎ Why a smaller tool set gives better tool selection“Tools: read-only tools; Write and Edit are denied”
↩︎ Why a smaller tool set gives better tool selection“Enforce constraints by limiting which tools a subagent can use”
↩︎ Configuring each subagent's tool set“To prevent Claude from delegating to any subagent, deny the Agent tool itself with permissions.deny.”
↩︎ Narrow cross-role tools, with complex cases routed through the coordinator“Enforce constraints by limiting which tools a subagent can use”
↩︎ Key concept - 3.https://www.anthropic.com/engineering/writing-tools-for-agentsSecondary source
“Choosing the right tools to implement (and not to implement)”
↩︎ Why a smaller tool set gives better tool selection - 4.https://platform.claude.com/cookbook/tool-use-tool-choiceSecondary source
“Clearly, this current implementation is not doing what we want (mostly because we set it up to fail).”
↩︎ How an out-of-role tool gets misused“any tells Claude that it must use one of the provided tools, but doesn't force a particular tool”
↩︎ tool_choice: auto, any and forcing a specific tool“In addition to setting type to tool, we must provide a particular tool name.”
↩︎ tool_choice: auto, any and forcing a specific tool“Even if we try to trip up Claude with a "Math-y" tweet, it still always calls the print_sentiment_scores tool:”
↩︎ tool_choice: auto, any and forcing a specific tool“The idea is to create a chatbot that always calls one of these tools and never responds with a non-tool response.”
↩︎ tool_choice: auto, any and forcing a specific tool“Even if we send Claude a gibberish message, it will still call one of our tools:”
↩︎ tool_choice: auto, any and forcing a specific tool“In addition to setting type to tool, we must provide a particular tool name.”
↩︎ Exam trap 4 - 5.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“Tool restrictions: subagents can be limited to specific tools, reducing the risk of unintended actions.”
↩︎ How an out-of-role tool gets misused“ensuring it can analyze but never accidentally modify your documentation files”
↩︎ How an out-of-role tool gets misused“Array of allowed tool names. If omitted, inherits every tool available to subagents”
↩︎ Configuring each subagent's tool set“# Bash access lets this subagent run test commands”
↩︎ Configuring each subagent's tool set“Tool restrictions: subagents can be limited to specific tools, reducing the risk of unintended actions.”
↩︎ Exam trap 1“Array of allowed tool names. If omitted, inherits every tool available to subagents”
↩︎ Exam trap 2 - 6.https://code.claude.com/docs/en/tools-referenceOfficial docs
“Both set: disallowedTools takes precedence. A tool listed in both is removed.”
↩︎ Configuring each subagent's tool set“tools only: the subagent gets only the listed tools.”
↩︎ Narrow cross-role tools, with complex cases routed through the coordinator“Both set: disallowedTools takes precedence. A tool listed in both is removed.”
↩︎ Exam trap 3 - 7.
“allowed_domains (the tool can reach only these hosts)”
↩︎ Replacing a generic tool with a constrained one“a web_fetch call for a URL that its lists do not permit returns an error result to the agent”
↩︎ Replacing a generic tool with a constrained one - 8.
“With the default tool_choice of {"type": "auto"}, Claude determines on each turn whether to call a tool or respond directly.”
↩︎ tool_choice: auto, any and forcing a specific tool“To require a tool call rather than rely on prompting, set tool_choice.”
↩︎ tool_choice: auto, any and forcing a specific tool“a second request sends the result back in a tool_result block so Claude can reply with the answer”
↩︎ tool_choice: auto, any and forcing a specific tool“To require a tool call rather than rely on prompting, set tool_choice.”
↩︎ Exam trap 5