2.3 Tool distribution across agents, and tool_choice
Fewer tools, better selection
Giving one agent 18 tools instead of 4–5 degrades selection reliability by increasing decision complexity. Agents with tools outside their specialization tend to misuse them — a synthesis agent handed web search will start searching.
Scoped tool access — the principle of least privilege applied to tools: each agent gets only what its role needs, plus limited cross-role tools for specific high-frequency needs.
web-search agent : WebSearch, WebFetch
doc-analysis agent : Read, load_document, extract_data_points
synthesis agent : verify_fact <- scoped cross-role tool (85% case)
coordinator : Task, everything routed through it (15% complex case)
That verify_fact example is the canonical answer to "synthesis needs verification, round trips cost 40% latency, 85% are simple fact checks": give the narrow tool for the common case, keep the coordinator path for the rest. Giving synthesis all web search tools over-provisions it and violates separation of concerns.
Constrained replacements for generic tools
Replace a generic tool with a validating one: fetch_url → load_document, which validates that the URL is a document.
tool_choice
Parameter reference: define tools.
| Value | Behaviour | Use when |
|---|---|---|
{"type": "auto"} | Model may call a tool or return text | Conversational agents; the default |
{"type": "any"} | Model must call a tool, but chooses which | Guarantee structured output when several extraction schemas exist and the document type is unknown |
{"type": "tool", "name": "extract_metadata"} | Model must call that specific tool | Force a required first step (metadata before enrichment) |
Forcing a specific tool constrains one turn — process subsequent steps in follow-up turns.
- TypeScript
- Python
// Guarantee a tool call rather than conversational text.
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
tools: [extractInvoice, extractContract, extractReceipt],
tool_choice: { type: "any" },
messages: [{ role: "user", content: documentBlocks }],
});
# Guarantee a tool call rather than conversational text.
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
tools=[extract_invoice, extract_contract, extract_receipt],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": document_blocks}],
)
Quiz
- Question 1
The synthesis agent frequently needs to verify claims, currently routing each verification back through the coordinator to the web search agent — 2–3 extra round trips and 40% more latency. Evaluation shows 85% are simple fact-checks (dates, names, statistics) and 15% need deeper investigation. What is the most effective approach?
- Question 2
Each of your four subagents is configured with all 18 tools in the system, so any agent can in principle handle any request. Selection accuracy has fallen: the synthesis agent runs its own web searches, the report generator loads raw PDFs, and the error rate tracks the number of tools in the prompt. What is the right correction?
- Question 3
Your support agent delegates address validation to a shipping subagent. In practice about 90% of validations are a straightforward domestic postcode-format check, and routing those through the subagent adds roughly 1.4 seconds each. The remaining 10% are international addresses that genuinely need the shipping agent’s carrier tools. What should you do?
- Question 4Select all that apply (2)
Your document-analysis subagent has fetch_url, which retrieves any URL it is given. It has started retrieving search result pages and social media threads and analysing them as though they were source documents. Which two statements are correct? Select two.
Links
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
- https://code.claude.com/docs/en/agent-sdk/permissions
- https://en.wikipedia.org/wiki/Principle_of_least_privilege