Distribute tools appropriately across agents and configure tool choice

Every tool you expose to an agent is another branch the model must weigh on each turn. Selection reliability degrades as the option count grows: an agent handed roughly 18 tools makes noticeably worse choices than one scoped to the 4-5 it actually needs. The decision space widens, similar-sounding tools compete, and the model misroutes.

The fix is not a smarter router bolted on top of the model. It is reducing the number of options the model has to reason about in the first place. Treat 4-5 relevant tools per agent as a working guideline, and be suspicious of any single agent that accumulates a large, general-purpose tool registry 'for flexibility.'

This is why multi-agent designs partition tools: each subagent sees only its slice. The coordinator, not any individual worker, holds the overall picture and decides who to invoke.

Agents given tools outside their specialization tend to misuse them. A synthesis agent whose job is to combine findings, if handed a full web-search toolset, will start running searches instead of synthesizing, blurring the separation of concerns the architecture depends on. The tool being available is itself the temptation.

Restrict each subagent's tool set to what its role requires. A web-search agent gets search and document-loading tools; a document-analysis agent gets extraction and reading tools; a synthesis agent gets report-writing tools. In the Claude Agent SDK you express this per subagent through its AgentDefinition, whose tools field lists exactly the tools that agent may call. Claude Code exposes the same idea through allowedTools / disallowedTools.

Scoping is a correctness mechanism, not just tidiness: it makes cross-specialization misuse structurally impossible rather than merely discouraged by the prompt.

Strict scoping can create latency if an agent constantly needs one small capability owned by another agent. In a research system, a synthesis agent frequently needs to verify a date, name, or statistic while combining findings. Routing every check back through the coordinator to the web-search agent adds round trips and can inflate latency substantially.

The right answer is a narrow, purpose-built cross-role tool, not full access to the other agent's toolbox. Give the synthesis agent a scoped verify_fact tool that handles the common simple case (the 85% of checks that are quick lookups), while genuinely complex investigations still delegate back through the coordinator to the search specialist.

This is the principle of least privilege applied to agents: grant the minimum extra capability that removes the bottleneck, and keep the escalation path for the hard cases. Handing the synthesis agent the entire web-search toolset to 'save round trips' over-provisions it and reintroduces the misuse problem you scoped away.

A generic tool invites generic (and unsafe) use. A fetch_url tool that will retrieve any URL lets an agent wander onto arbitrary pages; the model has no built-in sense of what a valid target is. Replacing it with a constrained load_document tool that validates the URL is a document source narrows both the surface area and the failure modes.

Constraining the tool is often better than adding a prompt instruction telling the agent not to misuse the generic tool, because the constraint is enforced in code rather than probabilistically obeyed. The tool's contract does the work.

This pairs with tool-description quality (task 2.1): a tightly scoped tool with a precise description is far easier for the model to select correctly than a broad tool whose description has to enumerate everything it might do.

tool_choice is a Messages API request parameter that controls whether and which tool the model must use on that request. There are three behaviors to know cold:

• {"type": "auto"} (the default when tools are provided): the model decides whether to call a tool or reply with plain text. It may return conversational text and skip tools entirely.
• {"type": "any"}: the model must call one of the provided tools, but chooses which. It cannot return a text-only answer. Use this when you need to guarantee a tool call, for example to force structured output instead of prose.
• {"type": "tool", "name": "extract_metadata"}: forced selection. The model must call that specific named tool.

{
  "model": "claude-sonnet-4-5",
  "tools": [ ... ],
  "tool_choice": {"type": "tool", "name": "extract_metadata"}
}

A useful related flag is disable_parallel_tool_use: true, which restricts the model to a single tool call. Note that forcing a tool (any or a specific tool) is not compatible with extended thinking.

Keep two mechanisms separate in your head. Tool distribution decides which tools an agent has (set once via AgentDefinition.tools or allowedTools). tool_choice decides what the model must do with the tools it has on a single request. They solve different problems: distribution prevents misuse and improves selection; tool_choice guarantees behavior on a given call.

Forced selection only governs the first tool call. You cannot express 'call extract_metadata, then call enrich, then finish' in one tool_choice. To enforce an order, force the first tool on the first request, take its result, and then make a follow-up request (often with tool_choice: auto) for the subsequent steps. Trying to encode a multi-step pipeline into a single forced tool_choice is a category error.

So the pattern for 'run extract_metadata before any enrichment tool' is: request 1 forces extract_metadata; you execute it and return the result; request 2 lets the model proceed with enrichment.