What you need to know
Fewer tools, better choices
Every tool an agent can see is another option to weigh on every turn. An agent with 18 tools chooses less reliably than one with 4 or 5, and an agent holding tools outside its specialty will use them: a synthesis agent with a web search tool starts searching instead of synthesising.
Scoped tool access gives each agent the tools its role needs, set in its AgentDefinition tools list.
| Subagent | Tools |
|---|---|
| Web search | web_search, fetch_page |
| Document analysis | read_document, extract_tables |
| Synthesis | verify_fact (one narrow cross-role tool) |
Narrow cross-role tools
Sometimes a role genuinely needs a little of another role's ability. The synthesis agent may need to check a date or a figure many times per report; sending each check back through the coordinator is slow. Give it a scoped tool such as verify_fact for simple lookups, and keep complex research routed through the coordinator.
Constrain open-ended tools
A fetch_url tool that accepts any URL gets used for API endpoints, binary files and internal admin pages. Replace it with a constrained alternative, such as load_document, that validates the URL against an approved pattern before fetching. The constraint lives in the tool, so it holds regardless of what the model tries.
tool_choice
| Setting | Effect | Use when |
|---|---|---|
{"type": "auto"} | Claude may call a tool or reply in text | The default for conversational agents |
{"type": "any"} | Claude must call a tool, but chooses which | You need structured output and there are several possible schemas |
{"type": "tool", "name": "extract_metadata"} | Claude must call that tool | A specific step must run first |
Forced selection applies to one request. A common pattern is to force extract_metadata on the first call, then process its result and let later steps (such as enrichment) run in follow-up turns with auto or any.
first = client.messages.create(model=MODEL, max_tokens=1024, tools=TOOLS,
tool_choice={"type": "tool", "name": "extract_metadata"},
messages=[{"role": "user", "content": doc}])In the exam
Expect a system where every agent has every tool, an agent misusing a tool from another role, a broad tool being abused, or a step that must run first. Map: role-scoped tools, a narrow cross-role tool, a constrained replacement, any to guarantee a tool call, a forced tool to guarantee order.
Check your understanding
A synthesis subagent keeps attempting web searches and failing. Every subagent has all 16 tools. What should you change?
Show answer
Answer: A. Agents use the tools they hold. Scoping each subagent's tool list to its role removes the misuse at its source, while search stays available to the agent that needs it.
Every request must produce an extraction, but the document type is unknown and there are three extraction tools. Which tool_choice fits?
Show answer
Answer: C. any guarantees a tool call (no prose answers) while leaving the choice of schema to Claude. Forcing one tool would apply the wrong schema to other document types.
extract_metadata must run before any enrichment tool. How do you guarantee it?
Show answer
Answer: D. A forced tool_choice makes that specific tool the first call. List order and prompt instructions influence the choice but do not guarantee it; any still lets Claude pick another tool.
Apply it: Scope Whitfield's tools
All of Whitfield's subagents receive the full catalogue of 16 tools. Redesign the distribution.
- Assign tools to each subagent (search, document analysis, synthesis, report) and keep each list at five or fewer.
- Add one cross-role tool where it is justified, and say what stays routed through the coordinator.
- Replace one open-ended tool with a constrained version.
- Choose tool_choice for the report subagent, which must always produce a rendered report.
Show model answer
1. Tools
| Subagent | Tools |
|---|---|
| Web search | web_search, fetch_page |
| Document analysis | read_document, extract_tables |
| Synthesis | verify_fact |
| Report | render_report |
| Coordinator | Task, plus nothing domain-specific |
2. Cross-role tool. verify_fact(claim) for synthesis: checks one date, figure or name against a trusted reference and returns supported or not. Anything needing new research (a missing subtopic, a new source) still goes back to the coordinator.
3. Constrained tool. fetch_page(url) becomes fetch_article(url), which accepts only http(s) URLs to HTML or PDF documents and rejects API endpoints, internal hosts and binaries.
4. tool_choice. Force render_report ({"type": "tool", "name": "render_report"}), because the report subagent has exactly one job and must never answer in prose.