Tool Distribution & Tool Choice

Official Exam Guide Objectives

Task 2.3: Distribute tools appropriately across agents and configure tool choice.

Knowledge of

• The principle that giving an agent access to too many tools (e.g., 18 instead of 4-5) degrades tool selection reliability by increasing decision complexity
• Why agents with tools outside their specialization tend to misuse them (e.g., a synthesis agent attempting web searches)
• Scoped tool access: giving agents only the tools needed for their role, with limited cross-role tools for specific high-frequency needs
• tool_choice configuration options: "auto", "any", and forced tool selection ({"type": "tool", "name": "..."})

Skills in

• Restricting each subagent's tool set to those relevant to its role, preventing cross-specialization misuse
• Replacing generic tools with constrained alternatives (e.g., replacing fetch_url with load_document that validates document URLs)
• Providing scoped cross-role tools for high-frequency needs (e.g., a verify_fact tool for the synthesis agent) while routing complex cases through the coordinator
• Using tool_choice forced selection to ensure a specific tool is called first (e.g., forcing extract_metadata before enrichment tools), then processing subsequent steps in follow-up turns
• Setting tool_choice: "any" to guarantee the model calls a tool rather than returning conversational text

What You Need to Know

How many tools an agent holds is not a packaging question. It changes how often the agent picks the right one, which makes it an architectural decision with production consequences.

The Tool Overload Problem

Hand a single agent 18 tools and selection reliability falls away. Each addition widens the choice the model has to make, and the error rate rises with it. What works is 4-5 tools per agent, chosen for that agent's job.

Count is only half of it. What the tools are for matters as much as how many there are. A synthesis agent should NOT have web search tools. A web search agent should NOT have document analysis tools. Equip an agent beyond its remit and it will find occasions to reach outside it — a synthesis agent holding web_search starts searching for itself rather than working from the results it was given, repeating work that is already done and spending context to do it.

Stated as a rule: an agent's toolkit stops at the boundary of its role, and anything past that boundary is an invitation to cross it.

The tool_choice Configuration

How the model engages with the toolkit is set by tool_choice. Three settings, three distinct jobs.

"auto" (default) The decision belongs to the model — a tool call or a text reply, whichever fits. Right for general operation, where answering conversationally is sometimes the correct behaviour.

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

"any" A tool call is required; which tool is not. Right when structured output is non-negotiable and several schemas could apply, because plain text stops being a possible outcome.

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

Extraction is where this pays. Holding separate schemas for invoices, receipts and contracts against a document whose type nobody has established, "any" guarantees one of them is used rather than the model describing what it found in prose.

Forced selection One named tool, and no discretion about it. Right for a step that must not be skipped or reordered.

{
  "tool_choice": { "type": "tool", "name": "extract_metadata" }
}

This is how ordering gets enforced. If nothing may run before metadata extraction, forcing the call removes the possibility of the model deciding otherwise and starting with enrichment. Once that call has happened, later turns can return to "auto" for whatever follows.

Scoped Cross-Role Tools

Occasionally an agent needs a capability that belongs to somebody else's role. Sending every such request back through the coordinator looks correct and costs 2-3 extra hops each time, which can add 40% or more to latency.

The alternative is a scoped cross-role tool: a deliberately narrowed version of that capability, handed to the agent that keeps needing it.

Consider a synthesis agent checking facts continuously while it writes. Routed through the coordinator, every check becomes a delegation to the search agent, a wait, and a return trip. For the 85% of checks that are trivial lookups resolvable in milliseconds, the entire round trip is overhead.

Give that agent a scoped verify_fact covering simple lookups and those resolve where they arise. Anything genuinely hard — several sources, cross-referencing, a judgement call — still goes through the coordinator. The common case gets the short path and the difficult 15% keeps the full pipeline.

The exam tests this pattern directly (Q9).

Replacing Generic Tools with Constrained Alternatives

fetch_url will retrieve anything from anywhere. load_document, which accepts document URLs and validates them, will not. Substituting the second for the first:

• Prevents misuse (the agent cannot fetch arbitrary URLs)
• Makes the tool's purpose clearer (the description is specific, not generic)
• Reduces the risk of unintended side effects (no fetching of non-document resources)

Note that the second benefit feeds selection quality as well as safety: a narrow tool can be described precisely, and precise descriptions are what tool selection runs on. What that amounts to is least privilege applied to tool design: reach is granted to the extent the role needs it and no further.

Role-Specific Tool Scoping in Practice

Here is how tool distribution looks in a well-designed multi-agent research system:

Every agent's list stops at what its role requires. Synthesis carries the scoped verify_fact for the trivial cases. The coordinator holds no domain tools whatever — its job is running the workflow, and giving it the means to do the work itself is how coordinators start doing the work itself.

Deep Dive

tool_choice has four types, not three — and each has a default

The lesson's three headline modes (auto, any, forced) are three of four documented tool_choice types. The Messages API reference defines all four: auto — "The model will automatically decide whether to use tools" (default when tools are provided); any — "The model will use any available tools"; tool — "The model will use the specified tool with tool_choice.name"; and none — "The model will not be allowed to use tools" (default when no tools are provided). none is the one this lesson doesn't otherwise mention: it's how you force a pure-text turn — a synthesis or proofreading pass, say — even when the request still carries a tools array for later turns.

{ "tool_choice": { "type": "none" } }

Sourcesplatform.claude.com › messagesplatform.claude.com › define-toolsfetched 2026-07-30

Forced selection suppresses commentary, not just tool choice

With tool_choice set to any or tool, "the API prefills the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before tool_use content blocks, even if explicitly asked to do so." Under plain auto, Claude commonly adds a short text block explaining what it's about to do before or alongside a tool call — forced selection removes that entirely. If your pipeline logs or displays Claude's reasoning before a forced first step, expect that field to be empty.

Sourceplatform.claude.com › define-toolsfetched 2026-07-30

Forced tool_choice is incompatible with manual extended thinking

A configuration trap worth knowing cold: "When using manual extended thinking (thinking: {type: \"enabled\"}) with tool use, tool_choice: {\"type\": \"any\"} and tool_choice: {\"type\": \"tool\", \"name\": \"...\"} are not supported and result in an error. Only tool_choice: {\"type\": \"auto\"} ... and tool_choice: {\"type\": \"none\"} are compatible with manual extended thinking." A document-analysis agent that both reasons with manual extended thinking and needs to force extract_metadata as its mandatory first step cannot do both on the same call — the forcing has to happen without manual extended thinking enabled, or not at all. Note the scope carefully: the restriction is specific to manual extended thinking. The same page adds that "adaptive thinking, including on models where thinking is on by default such as Claude Opus 5, supports forced tool use."

Sourceplatform.claude.com › define-toolsfetched 2026-07-30

disable_parallel_tool_use lives inside tool_choice, not at the top level

Parallel tool calls are on by default. To turn them off you set disable_parallel_tool_use: true, but it is "not a top-level request parameter" — it's a field inside the tool_choice object, and its effect depends on the enclosing type:

{ "tool_choice": { "type": "any", "disable_parallel_tool_use": true } }

Sourceplatform.claude.com › parallel-tool-usefetched 2026-07-30

Changing tool_choice between turns has a prompt-caching cost

A coordinator that forces extract_metadata on turn one, then switches to auto for later turns (exactly the pattern this lesson recommends), pays a caching price for the switch: "changes to the tool_choice parameter will invalidate cached message blocks. Tool definitions and system prompts remain cached, but message content must be reprocessed." Worth knowing when estimating latency/cost for a workflow that toggles forced-then-auto tool_choice on every run.

Sourceplatform.claude.com › define-toolsfetched 2026-07-30

Bloated tool sets are a named failure mode in Anthropic's context-engineering guidance

The 4-5-tools-per-agent guideline isn't just a selection-accuracy heuristic — Anthropic's context-engineering guidance names it directly as a top failure mode: "One of the most common failure modes we see is bloated tool sets that cover too much functionality or lead to ambiguous decision points about which tool to use." Framed this way, every extra overlapping tool costs two things at once — more decision complexity and more context budget spent on descriptions the agent will rarely use. That reframes "scope tools to the agent's role" as a context-engineering discipline, not only a routing-accuracy one.

Sourceanthropic.com › effective-context-engineering-for-ai-agentsfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Configure Tool Distribution Across a Multi-Agent System

Difficulty: Intermediate (2/4)

45 minutes

1. Design three agent roles (web search, document analysis, synthesis) and assign 4-5 tools to each, scoped to its role

Why: Tool overload degrades selection reliability. The exam tests the principle that each agent should have 4-5 tools scoped to its specific role. Giving a single agent 18 tools is a known anti-pattern that causes misrouting.

You should see: A configuration object or table listing three agents, each with exactly 4-5 tools. No tool appears in more than one agent role (except scoped cross-role tools added later). Tool names clearly indicate their purpose and scope.

2. Add a scoped verify_fact tool to the synthesis agent that handles simple lookups directly

Why: Routing every fact verification through the coordinator adds 2-3 round trips and up to 40% latency. The exam tests the scoped cross-role tool pattern — give the agent a constrained version of a capability for the 85% simple case, routing only complex cases to the coordinator.

You should see: A verify_fact tool added to the synthesis agent toolset with a description that explicitly limits it to simple single-source lookups and states that complex multi-source verifications should be escalated to the coordinator.

3. Configure tool_choice forced selection on the document analysis agent to ensure extract_metadata runs as the mandatory first step

Why: Forced selection enforces workflow ordering. The exam tests your knowledge of all three tool_choice modes: auto lets the model choose freely, any guarantees a tool call, and forced selection guarantees a specific tool call. This prevents the model from skipping mandatory steps.

You should see: A document analysis agent configuration where the first API call uses tool_choice with type: tool and name: extract_metadata, and subsequent calls switch to tool_choice: auto for the remaining analysis steps.

4. Replace a generic fetch_url tool with a constrained load_document that validates document URLs only

Why: This applies the principle of least privilege to tool design. A generic fetch_url tool can fetch anything from anywhere, enabling misuse. A constrained load_document that validates URLs prevents the agent from fetching arbitrary resources. The exam tests this pattern directly.

You should see: A load_document tool definition that includes URL validation logic (checking for document file extensions or trusted domains) and rejects non-document URLs with a clear error message.

5. Test with a query that requires all three agents and verify that no cross-role tool misuse occurs

Why: End-to-end testing validates that your tool distribution works in practice. Cross-role misuse — such as a synthesis agent running its own web searches instead of using provided results — is a common failure the exam expects you to prevent through proper scoping.

You should see: A test run log showing: the web search agent using only its tools, the document analysis agent starting with extract_metadata (forced), and the synthesis agent using compile_report plus verify_fact for simple checks. No agent calls a tool outside its assigned set.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.3 — Anthropic
• Tool use — Anthropic API Documentation — Anthropic
• Claude Agent SDK — Tool Configuration — Anthropic
• Messages API reference — Anthropic
• Define tools — Anthropic API Documentation — Anthropic
• Parallel tool use — Anthropic API Documentation — Anthropic
• Effective context engineering for AI agents — Anthropic — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Design three agent roles (web search, document analysis, synthesis) and assign 4-5 tools to each, scoped to its role

Why: Tool overload degrades selection reliability. The exam tests the principle that each agent should have 4-5 tools scoped to its specific role. Giving a single agent 18 tools is a known anti-pattern that causes misrouting.

You should see: A configuration object or table listing three agents, each with exactly 4-5 tools. No tool appears in more than one agent role (except scoped cross-role tools added later). Tool names clearly indicate their purpose and scope.

const agentToolsets = {
  webSearch: {
    role: "Finds and retrieves web content",
    tools: [
      { name: "search_web", description: "Searches the web for a query and returns ranked results" },
      { name: "fetch_page", description: "Fetches the full content of a web page by URL" },
      { name: "extract_links", description: "Extracts all hyperlinks from a web page" },
      { name: "save_snippet", description: "Saves a text snippet with source URL for later use" }
    ]
  },
  documentAnalysis: {
    role: "Analyses document structure and content",
    tools: [
      { name: "extract_metadata", description: "Extracts title, author, date, and document type" },
      { name: "extract_data_points", description: "Extracts structured data fields (dates, amounts, names)" },
      { name: "summarise_content", description: "Produces a concise summary of key arguments" },
      { name: "verify_claim", description: "Checks if a claim is supported by the source document" }
    ]
  },
  synthesis: {
    role: "Compiles findings into reports",
    tools: [
      { name: "compile_report", description: "Assembles research findings into a structured report" },
      { name: "format_citation", description: "Formats a source reference in the required citation style" },
      { name: "assess_coverage", description: "Evaluates whether all research questions have been addressed" }
    ]
  }
};

AGENT_TOOLSETS = {
    "web_search": {
        "role": "Finds and retrieves web content",
        "tools": [
            {"name": "search_web", "description": "Searches the web for a query and returns ranked results"},
            {"name": "fetch_page", "description": "Fetches the full content of a web page by URL"},
            {"name": "extract_links", "description": "Extracts all hyperlinks from a web page"},
            {"name": "save_snippet", "description": "Saves a text snippet with source URL for later use"},
        ],
    },
    "document_analysis": {
        "role": "Analyses document structure and content",
        "tools": [
            {"name": "extract_metadata", "description": "Extracts title, author, date, and document type"},
            {"name": "extract_data_points", "description": "Extracts structured data fields (dates, amounts, names)"},
            {"name": "summarise_content", "description": "Produces a concise summary of key arguments"},
            {"name": "verify_claim", "description": "Checks if a claim is supported by the source document"},
        ],
    },
    "synthesis": {
        "role": "Compiles findings into reports",
        "tools": [
            {"name": "compile_report", "description": "Assembles research findings into a structured report"},
            {"name": "format_citation", "description": "Formats a source reference in the required citation style"},
            {"name": "assess_coverage", "description": "Evaluates whether all research questions have been addressed"},
        ],
    },
}

Step 2. Add a scoped verify_fact tool to the synthesis agent that handles simple lookups directly

Why: Routing every fact verification through the coordinator adds 2-3 round trips and up to 40% latency. The exam tests the scoped cross-role tool pattern — give the agent a constrained version of a capability for the 85% simple case, routing only complex cases to the coordinator.

You should see: A verify_fact tool added to the synthesis agent toolset with a description that explicitly limits it to simple single-source lookups and states that complex multi-source verifications should be escalated to the coordinator.

// Add to synthesis agent tools
const scopedVerifyFact = {
  name: "verify_fact",
  description: "Verifies a simple factual claim against a single source document. Use for quick checks during report compilation. For complex verifications requiring multiple sources or cross-referencing, escalate to the coordinator.",
  inputSchema: {
    type: "object",
    properties: {
      claim: { type: "string", description: "The factual claim to verify" },
      sourceId: { type: "string", description: "ID of the source document to check against" }
    },
    required: ["claim", "sourceId"]
  }
};
agentToolsets.synthesis.tools.push(scopedVerifyFact);

# Add to synthesis agent tools
scoped_verify_fact = {
    "name": "verify_fact",
    "description": (
        "Verifies a simple factual claim against a single source document. Use "
        "for quick checks during report compilation. For complex verifications "
        "requiring multiple sources or cross-referencing, escalate to the "
        "coordinator."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "claim": {"type": "string", "description": "The factual claim to verify"},
            "source_id": {
                "type": "string",
                "description": "ID of the source document to check against",
            },
        },
        "required": ["claim", "source_id"],
    },
}
AGENT_TOOLSETS["synthesis"]["tools"].append(scoped_verify_fact)

Step 3. Configure tool_choice forced selection on the document analysis agent to ensure extract_metadata runs as the mandatory first step

Why: Forced selection enforces workflow ordering. The exam tests your knowledge of all three tool_choice modes: auto lets the model choose freely, any guarantees a tool call, and forced selection guarantees a specific tool call. This prevents the model from skipping mandatory steps.

You should see: A document analysis agent configuration where the first API call uses tool_choice with type: tool and name: extract_metadata, and subsequent calls switch to tool_choice: auto for the remaining analysis steps.

// First turn: forced selection
const firstTurn = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  tools: agentToolsets.documentAnalysis.tools,
  tool_choice: { type: "tool", name: "extract_metadata" },
  messages: [{ role: "user", content: "Analyse this document: ..." }]
});
// Subsequent turns: auto selection
const nextTurn = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  tools: agentToolsets.documentAnalysis.tools,
  tool_choice: { type: "auto" },
  messages: [...previousMessages]
});

# First turn: forced selection
first_turn = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=AGENT_TOOLSETS["document_analysis"]["tools"],
    tool_choice={"type": "tool", "name": "extract_metadata"},
    messages=[{"role": "user", "content": "Analyse this document: ..."}],
)

# Subsequent turns: auto selection
next_turn = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=AGENT_TOOLSETS["document_analysis"]["tools"],
    tool_choice={"type": "auto"},
    messages=previous_messages,
)

Step 4. Replace a generic fetch_url tool with a constrained load_document that validates document URLs only

Why: This applies the principle of least privilege to tool design. A generic fetch_url tool can fetch anything from anywhere, enabling misuse. A constrained load_document that validates URLs prevents the agent from fetching arbitrary resources. The exam tests this pattern directly.

You should see: A load_document tool definition that includes URL validation logic (checking for document file extensions or trusted domains) and rejects non-document URLs with a clear error message.

const loadDocument = {
  name: "load_document",
  description: "Loads a document from a validated URL. Only accepts URLs ending in .pdf, .docx, .md, .txt, or .html from trusted domains. Use instead of fetch_url for document retrieval.",
  handler: async ({ url }: { url: string }) => {
    const validExtensions = [".pdf", ".docx", ".md", ".txt", ".html"];
    const trustedDomains = ["docs.internal.com", "wiki.company.com"];
    const parsed = new URL(url);
    const hasValidExt = validExtensions.some(ext => parsed.pathname.endsWith(ext));
    const isTrusted = trustedDomains.includes(parsed.hostname);
    if (!hasValidExt || !isTrusted) {
      return {
        isError: true,
        content: [{ type: "text", text: `Rejected: ${url} is not a valid document URL. Must be a document file from a trusted domain.` }]
      };
    }
    // Fetch and return document content
    return { content: [{ type: "text", text: `Document content from ${url}` }] };
  }
};

from urllib.parse import urlparse

VALID_EXTENSIONS = (".pdf", ".docx", ".md", ".txt", ".html")
TRUSTED_DOMAINS = {"docs.internal.com", "wiki.company.com"}


def load_document(url: str) -> dict:
    """Loads a document from a validated URL.

    Only accepts URLs ending in .pdf, .docx, .md, .txt, or .html from trusted
    domains. Use instead of fetch_url for document retrieval.
    """
    parsed = urlparse(url)
    has_valid_ext = parsed.path.endswith(VALID_EXTENSIONS)
    is_trusted = parsed.hostname in TRUSTED_DOMAINS
    if not has_valid_ext or not is_trusted:
        return {
            "isError": True,
            "content": [
                {
                    "type": "text",
                    "text": (
                        f"Rejected: {url} is not a valid document URL. "
                        "Must be a document file from a trusted domain."
                    ),
                }
            ],
        }
    # Fetch and return document content
    return {"content": [{"type": "text", "text": f"Document content from {url}"}]}

Step 5. Test with a query that requires all three agents and verify that no cross-role tool misuse occurs

Why: End-to-end testing validates that your tool distribution works in practice. Cross-role misuse — such as a synthesis agent running its own web searches instead of using provided results — is a common failure the exam expects you to prevent through proper scoping.

You should see: A test run log showing: the web search agent using only its tools, the document analysis agent starting with extract_metadata (forced), and the synthesis agent using compile_report plus verify_fact for simple checks. No agent calls a tool outside its assigned set.

async function runMultiAgentQuery(query: string) {
  const log: Array<{ agent: string; tool: string }> = [];
  // Simulate coordinator dispatching to agents
  for (const [agentName, config] of Object.entries(agentToolsets)) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 1024,
      tools: config.tools, // Only this agent's tools
      messages: [{ role: "user", content: query }]
    });
    for (const block of response.content) {
      if (block.type === "tool_use") {
        log.push({ agent: agentName, tool: block.name });
      }
    }
  }
  // Verify no cross-role usage
  for (const entry of log) {
    const agentTools = agentToolsets[entry.agent].tools.map(t => t.name);
    console.log(`${entry.agent}: ${entry.tool} — ${agentTools.includes(entry.tool) ? "VALID" : "CROSS-ROLE VIOLATION"}`);
  }
}

def run_multi_agent_query(query: str) -> None:
    log = []
    # Simulate coordinator dispatching to agents
    for agent_name, config in AGENT_TOOLSETS.items():
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            tools=config["tools"],  # Only this agent's tools
            messages=[{"role": "user", "content": query}],
        )
        for block in response.content:
            if block.type == "tool_use":
                log.append({"agent": agent_name, "tool": block.name})

    # Verify no cross-role usage
    for entry in log:
        agent_tools = [t["name"] for t in AGENT_TOOLSETS[entry["agent"]]["tools"]]
        verdict = "VALID" if entry["tool"] in agent_tools else "CROSS-ROLE VIOLATION"
        print(f"{entry['agent']}: {entry['tool']} — {verdict}")

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the configuration you actually wrote.