Tool Distribution & tool_choice

Estimated time: 25 minutes

An agent with too many tools loses the ability to pick the right one. tool_choice gives you explicit control over selection. This lesson covers how to scope toolsets per subagent, when to force tool calls, and how constrained tools beat permissive ones.

Tool Count Affects Selection Quality

An agent given 18 tools to choose from picks worse than the same agent given 4. The model has to reason over the entire toolset for every call; more tools means more confusion, especially for tools with overlapping purposes. Restricting each subagent's toolset to its role is the simplest fix.

tool_choice Options

ValueBehaviorUse when
"auto"Model may return text or call any toolStandard conversational flow
"any"Must call SOME tool (model picks which)Forcing structured output via tool_use
{ "type": "tool", "name": "x" }Must call this specific toolGuaranteeing a particular step runs (e.g., always call extract_metadata first)

Forced Selection for Structured Output

If you need structured output, give the agent a tool whose schema is the structure you want and set tool_choice: "any". The model is forced to call a tool, the tool's schema dictates the structure, and you get reliable JSON instead of probabilistic text generation.

Constrained Tools Beat Permissive Ones

A generic fetch_url tool is too permissive — agents misuse it for things outside the intended scope. Replace it with load_document that validates the URL is in your approved domain list. The model can't bypass the validation; the tool simply rejects invalid inputs.

Scoping Subagent Toolsets

If a synthesis subagent needs simple fact verification 85% of the time and complex web search 15% of the time, give it a scoped verify_fact tool for the common case. Route the complex 15% through the coordinator (which has full search tools). The synthesis subagent stays focused; the coordinator handles edge cases.

Routing Pattern

User: "Verify that the iPhone was launched in 2007"

Synthesis subagent: calls verify_fact(claim="iPhone launched in 2007")
verify_fact returns: { verified: true, source: "Apple press release, 2007-01-09" }

User: "What was Steve Jobs's keynote about at the iPhone launch event?"

Synthesis subagent: detects this requires more than fact verification.
Returns control to coordinator.
Coordinator: dispatches to research subagent with full web search.

Skills to Develop

  1. Restrict each subagent's allowedTools to the minimum set its role requires.
  2. Replace generic tools with scoped alternatives that validate inputs.
  3. Use tool_choice: "any" to guarantee structured output via tool schemas.
  4. Use forced tool selection ({ type: "tool", name: "…" }) to ensure prerequisite steps run before dependent ones.
Exam tip (Q9): A synthesis agent that needs simple fact verification 85% of the time should get a scoped verify_fact tool. Complex 15% of cases route through the coordinator. Don't give the synthesis agent full web search tools — that's overprovisioning.
← Back to Module