Skip to content

Tool Distribution & Tool Choice

This module is about tool surface area control. The exam will test whether you know that tool selection reliability depends not only on good tool descriptions, but also on which tools each agent can see and how strongly tool use is constrained per turn.

Anthropic’s tool docs say Claude decides whether to call a tool based on the user request and the tool description; with default tool_choice: {"type": "auto"}, Claude may either use a tool or answer directly. For a hard guarantee, Anthropic exposes tool_choice controls. (Claude)

1. Core Idea

A good multi-agent system does not give every agent every tool.

Instead: 

Coordinator agent:
  Plans, delegates, routes, synthesizes.

Research agent:
  Search tools, source retrieval tools, citation tools.

Document extraction agent:
  Document loader, parser, schema extractor.

Synthesis agent:
  Summarization tools, maybe a lightweight verify_fact tool.

Action agent:
  Write/update/send tools, with confirmation and permission checks.

Heuristic:

Give each subagent only the tools required for its role, plus a small number of constrained cross-role tools for high-frequency needs.

2. Why Too Many Tools Degrade Selection Reliability

The official guide gives the exam example: 18 tools instead of 4–5 can degrade tool selection.

This happens for three reasons:

2.1 Decision Complexity

Every extra tool increases the model’s selection problem: 

Should I use a tool?
Which tool?
What arguments?
Is this tool better than a similar tool?
Should I call another tool first?

If a synthesis agent sees 18 tools, including web search, raw URL fetch, document parsing, database lookup, and email-sending tools, it may choose tools outside its intended role.

2.2 Tool Overlap

Selection gets worse when tools have similar names or broad descriptions: 

fetch_url
load_document
search_web
search_docs
retrieve_source
read_page

Anthropic’s advanced tool-use guidance highlights wrong tool selection and incorrect parameters as common failures when many tools with similar names are loaded; it also notes that large tool libraries consume significant context before the conversation even starts. (Anthropic)

2.3 Context Pressure

Tool definitions themselves consume context. Anthropic’s advanced tool-use article gives examples of large tool libraries consuming tens of thousands of tokens and recommends on-demand tool discovery when many tools or MCP servers are available. (Anthropic)

The concept is: 

Large tool surface area → more selection ambiguity + more context overhead.

3. Specialization: Agents Misuse Tools Outside Their Role

The official example is:

A synthesis agent attempting web searches.

Why is that bad?

A synthesis agent’s job is to combine already-collected evidence into a coherent answer. If it has search tools, it may:

start new research instead of synthesizing;
duplicate work already done by research agents;
introduce uncited or late-stage evidence;
expand scope after the coordinator decided research was sufficient;
increase latency and cost;
create inconsistent source quality.

Anthropic’s multi-agent research write up describes an orchestrator-worker pattern where a lead agent coordinates specialized subagents; subagents search different aspects and return compressed findings to the lead agent for synthesis. (Anthropic) That architecture only works if roles stay clean.

3.1 Rule

When an agent misuses tools outside its specialization, prefer: 

Restrict the agent’s tool set.
Route out-of-role needs through the coordinator.
Provide only constrained cross-role tools when justified.

Do not prefer: 

Add more instructions telling the agent not to misuse tools.
Give every agent all tools for flexibility.
Rely on the model to self-police.

4. Scoped Tool Access

Scoped tool access means each agent gets only tools relevant to its task. The synthesis agent can search, mutate systems, send messages, and handle documents. The chance of tool misuse is high.

Better design: 

Synthesis agent tools:
- summarize_findings
- verify_fact

The synthesis agent can do its main job and verify a small number of claims, but complex research goes back to the coordinator.

4.1 Example Scoped Architecture

Agent Main responsibility Tools
Coordinator Plan, delegate, decide next step create_research_task, create_extraction_task, route_to_action_agent
Research agent Find external/internal evidence web_search, search_docs, load_source
Document agent Extract structured content load_document, extract_metadata, extract_data_points
Synthesis agent Combine findings summarize_findings, verify_fact
Action agent Execute changes create_ticket, send_email, update_crm

This follows Anthropic’s broader guidance to keep agentic systems as simple as possible and increase complexity only when needed; workflows are better for predictable paths, while agents are better when model-driven decisions are needed. (Anthropic)

5. Limited Cross-Role Tools

The official guide says to provide scoped cross-role tools for high-frequency needs, such as a verify_fact tool for the synthesis agent.

This is an important nuance. Docs does not say “never give cross-role tools.” It says to scope them.

Bad cross-role tool: 

Synthesis agent gets web_search.

Problem: the synthesis agent can open-endedly research.

Better cross-role tool: 

Synthesis agent gets verify_fact.

Why better? 

It performs a narrow verification task.
It likely requires a claim and source IDs.
It does not open-endedly search the web.
It preserves coordinator control over complex research.

Heuristic:

If the cross-role need is frequent and narrow, add a constrained cross-role tool. If it is broad or complex, route it through the coordinator.

6. Replace Generic Tools with Constrained Alternatives

The official example:

Replace fetch_url with load_document that validates document URLs.

This is a very exam-worthy pattern.

Bad generic tool: 

{
  "name": "fetch_url",
  "description": "Fetch any URL.",
  "input_schema": {
    "type": "object",
    "properties": {
      "url": { "type": "string" }
    },
    "required": ["url"]
  }
}

Problems: 

Too broad.
Can fetch arbitrary sites.
May bypass source-type boundaries.
Does not validate allowed domains or document formats.
May be misused by agents that only need approved documents.

Better constrained tool: 

{
  "name": "load_document",
  "description": "Load a validated document URL from the approved document store. Use this for PDFs, internal docs, or approved source documents that must be parsed or cited. Do not use for arbitrary web browsing, news search, or external URL fetching. Rejects URLs outside the approved document domains.",
  "input_schema": {
    "type": "object",
    "properties": {
      "document_url": {
        "type": "string",
        "description": "Approved document URL from docs.company.com or files.company.com. Must point to a document, not a generic webpage."
      }
    },
    "required": ["document_url"]
  }
}

The constrained tool improves: 

tool selection;
security;
role separation;
validation;
auditability;
reliability.

Heuristic:

When you see a broad tool like: 

fetch_url
run_sql
execute_command
call_api
process_file

The fix is often: 

Replace it with a constrained, role-specific tool.

7. tool_choice Options

The guide names three options: 

auto
any
forced tool selection: {"type": "tool", "name": "..."}

Anthropic’s cookbook summarizes the same three options: - auto lets Claude decide whether to call tools, - any requires Claude to call one of the available tools, - tool forces a specific tool. (Claude)

7.1 tool_choice: {"type": "auto"}

Use when Claude should decide whether a tool is needed. 

{
  "tool_choice": { "type": "auto" }
}

With auto, Claude can either: 

call a tool;
or answer conversationally without a tool.

Anthropic’s docs say auto is the default tool choice and that Claude responds directly for stable knowledge, creative tasks, and conversational turns. (Claude)

Use auto for: 

general assistants;
mixed tasks;
situations where tool use is optional;
cases where direct answer may be better than tool call.

Heuristic:

auto does not guarantee tool use. If the task requires the model to call a tool first, use any or forced selection.

7.2 tool_choice: {"type": "any"}

Use when Claude must call some tool, but you let it choose which one. 

{
  "tool_choice": { "type": "any" }
}

Use any when: 

a tool call is mandatory;
several tools could be appropriate;
you need structured tool output instead of conversational text;
you want to prevent direct prose responses.

Important nuance: 

Any guarantees one of the available tools will be called.
It does not guarantee the correct tool will be called.

So any should be used with a small, scoped toolset. If you give Claude 18 tools and set tool_choice: "any", you may force a bad call.

7.3 Forced Tool Selection

Use forced selection when: 

the workflow has a mandatory first step;
you need metadata before enrichment;
you need a classifier before routing;
you need extraction before validation;
you need a safety/policy check before action.

Official guide example: 

Force extract_metadata before enrichment tools.
Then process subsequent steps in follow-up turns.

Example: 

# Turn 1: force metadata extraction
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    tools=[extract_metadata_tool],
    tool_choice={"type": "tool", "name": "extract_metadata"},
    messages=[
        {"role": "user", "content": "Prepare this document for enrichment."}
    ]
)

# Your application executes extract_metadata and returns tool_result.

# Turn 2: now allow enrichment tools
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    tools=[enrich_author_tool, enrich_company_tool, classify_document_tool],
    tool_choice={"type": "auto"},
    messages=messages_with_metadata_result
)

The key pattern: 

Force the mandatory first tool.
Execute it.
Feed back the result.
Then continue with a scoped tool set in a follow-up turn.

Heuristic:

Do not force a tool merely because you want “more reliable behavior.” Force a tool only when that tool is logically mandatory for the current step.

8.5 allowed_tools Vs tool_choice: Two Different Layers

These two controls are frequently confused. They operate at different layers of the stack.

  • allowed_tools is an Agent SDK permission: it gates which tools a (sub)agent CAN access at all. It controls availability.
  • tool_choice is a Claude API constraint applied per request: it constrains how Claude selects among the tools that are already available on that call.
Aspect allowed_tools tool_choice
Layer Agent SDK permission / configuration Claude API request parameter
Question it answers Which tools CAN this subagent access? On this call, must Claude call a tool, and which?
Scope Availability / permission gating Selection constraint for a single request
Granularity Per agent (the tool set it is allowed to see/use) Per request / per turn
Values List of permitted tool names or wildcards (e.g. mcp__github__*) auto (may answer in text), any (must call some tool), forced {"type":"tool","name":"..."} (must call that specific tool)
Failure if violated Tool is simply not available to the agent Constraint shapes whether/which tool is called

Key relationship:

A tool must be available (permitted via allowed_tools) before tool_choice can force it.

Forcing {"type":"tool","name":"extract_metadata"} only works if extract_metadata is in the agent's allowed/available toolset for that request.

Heuristic:

allowed_tools  → gates availability/permission (which tools the agent CAN use).
tool_choice    → constrains selection on a given call (auto / any / forced specific tool).

You cannot force a tool the agent is not allowed to access, and allowing a tool does not by itself force Claude to call it. Tool distribution (allowed_tools) and per-request constraint (tool_choice) solve different problems and are often combined.

9. Design Patterns

9.1 Pattern 1: Coordinator Agent Controls Breadth

The coordinator agent may know about many capabilities, but subagents should receive only scoped tools. 

User asks complex question
→ Coordinator decomposes task
→ Research agent gets search/retrieval tools
→ Document agent gets document tools
→ Synthesis agent gets summarization + verify_fact
→ Coordinator combines results

9.2 Pattern 2: Specialist Agents Get Specialist Tools

Research agent:
  web_search
  search_internal_docs
  load_source

Extraction agent:
  load_document
  extract_metadata
  extract_data_points

Synthesis agent:
  summarize_findings
  verify_fact

Action agent:
  create_ticket
  send_email

9.3 Pattern 3: Constrained Alternatives Replace Generic Tools

fetch_url → load_document
run_sql → query_customer_summary
execute_command → run_preapproved_diagnostic
send_message → send_approved_template

9.4 Pattern 4: Step-Gated Forced Tool Use

Turn 1: force extract_metadata.
Turn 2: based on metadata, expose only relevant enrichment tools.
Turn 3: synthesize or execute action.

12. High-yield D2.3 checklist

Memorize this:

1. Too many tools degrade selection reliability.
2. Aim for small, role-relevant tool sets per agent.
3. Agents misuse tools outside their specialization.
4. Synthesis agents should not do open-ended research.
5. Use scoped cross-role tools only for narrow, frequent needs.
6. Route complex cross-role work through the coordinator.
7. Replace generic tools with constrained alternatives.
8. fetch_url is often too broad; load_document with validation is safer.
9. auto lets Claude decide whether to use a tool.
10. any guarantees some tool call, not the correct tool.
11. Forced tool selection guarantees a specific tool call.
12. Use forced selection for mandatory first steps.
13. After a forced first tool, continue in follow-up turns with a scoped tool set.
14. tool_choice does not fix an overbroad tool list.
15. Tool scoping and tool_choice solve different problems.

Exam mental model

For D2.3, think:

Tool distribution controls what the agent can choose.
tool_choice controls whether or how strongly it must choose.

Best exam answers usually combine both:

Give each agent fewer, role-specific tools.
Use constrained alternatives instead of broad tools.
Allow narrow cross-role tools only when justified.
Use auto when tool use is optional.
Use any when some tool must be called.
Force a named tool only for deterministic required steps.
Test yourself on this topic Interactive questions for Task 2.3 — Tool Distribution & Tool Choice, with instant explanations and scoring.
Start quiz →