Task statement 2.3 · Tool design and MCP integration

Distribute tools appropriately across agents and configure tool choice

The support agent started with four tools. Marketing, billing and ops have each added a few, and now a refund request is sometimes answered with a discount code.

Why it's tested

The tempting fix for an agent that keeps handing work off is to give it more tools. Each extra tool is another candidate on every turn, and one outside the agent's role will sometimes be misused, so the fix trades a round trip for wrong calls. The second trap is reading "any" as "call the right tool": it guarantees that Claude calls one of its tools, but Claude still picks which.

KnowledgeEvery tool is a candidate on every turn

On each turn Claude reads the descriptions of all its tools and picks one, or none. The guide's figure is an agent with 18 tools where its role needs 4–5: the extra tools add decision complexity, so selection becomes less reliable. Tools outside the agent's specialization are the ones it tends to misuse, because a description that fits the words of a request can win even when the tool is wrong for the job. That is how the support agent reaches for the marketing tool apply_discount on a refund request. The remedy is scoped tool access: only the tools the role needs, plus limited cross-role tools for specific high-frequency needs, such as a read-only check_stock for replacement questions.

Interactive · the same refund request, two tool lists

A customer asks for a refund on order 10024871. The support agent picks one tool from its list. With 18 tools, including marketing, billing and ops tools, it calls apply_discount. Scoped to four support tools plus a read-only check_stock, the other 13 tools are not in its session and it calls process_refund. “Order 10024871 arrived broken. I want a refund.” Claude picks one tool support agent · 18 tools support agent · 5 tools removed from its list · not in its session get_customer lookup_order process_refund escalate_to_human check_stock send_promo_email apply_discount create_campaign list_invoices void_invoice update_account reset_password merge_accounts refund_report export_csv reorder_stock ping_warehouse schedule_pickup tool_use apply_discount: offers 15% off instead of the refund process_refund(10024871): the refund the customer asked for

Choose what the support agent holds.

Choose what the support agent holds.

Eighteen tools in one list: marketing, billing and ops tools compete with the support tools on every turn, and here apply_discount wins a refund request. Scoped: four support tools plus a read-only cross-role check_stock. The other 13 are not in this agent’s session, so none of them can be picked.

SkillRestrict each subagent's tool set to its role

Scoping holds only when it is set where the agent is defined, not requested in its prompt. In the Agent SDK, a subagent's AgentDefinition has a tools list: omit it and the subagent inherits every tool available to subagents, set it and a tool left out is not in the subagent's session at all. Suppose the support agent delegates "can I return this?" questions to a returns-checker subagent with no tools field. In testing it called process_refund on an order it was only asked to assess. Listing the one tool its role needs prevents that cross-specialization misuse and leaves the main agent unchanged.

agents: { "returns-checker": {
  description: "Checks whether an order can be returned.",
  prompt: "…",
  tools: ["mcp__support__lookup_order"]  // before: no tools field
} }

The separate disallowedTools field works the other way round, removing named tools, or a whole server with mcp__support__*, from what the subagent would otherwise get.

Knowledgetool_choice: auto, any, or a forced tool

tool_choice is a request parameter that sets whether Claude must call a tool on this turn. "auto", the default when tools are supplied, lets Claude answer in text instead. "any" guarantees a tool call rather than conversational text, while forced selection names the exact tool. With either, the API starts Claude's reply already inside a tool call, so no text comes before the tool_use block and the reply is safe to parse. The setting covers one request, so forcing get_customer on the first turn cannot stop an unverified process_refund later. Ordering across a whole conversation needs a hook, as 1.4 teaches.

"auto"

Default when tools are supplied.

{"type": "auto"}

Guarantees Nothing. Claude may answer in text.

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

Guarantees A tool call. Claude picks which.

forced
{"type": "tool",
 "name": "get_customer"}

Guarantees That tool, on this request.

"none"

Default when no tools are supplied.

{"type": "none"}

Guarantees A text-only reply.

More precise than the guide. On the newest Claude models (the current Opus, Sonnet, Fable and Mythos releases), "any" and forced tool_choice return a 400 error, and with manual extended thinking (thinking: {type: "enabled"}) they fail on any model. The docs suggest "auto" with strict tool use, or structured outputs, instead (checked 2026-10-01). Exam answer: "any" to guarantee a tool call, or a forced tool to make a specific tool run first.

Scenario switchThe guide's own examples here come from the Multi-Agent Research System, where a coordinator delegates to web search, document analysis, synthesis and report generation subagents. The section returns to the support agent at the rule.

SkillThe guide's examples: scoped, constrained and forced

A synthesis agent that holds the web search tools shows the misuse the guide describes. Asked to combine five sources, it runs web searches of its own, repeating the search subagent's work and citing sources nobody vetted. Without those tools, though, its simple fact checks, about 85% of its verifications, each need a round trip through the coordinator. The guide's fix is a scoped cross-role tool, verify_fact, which checks one claim such as "the plant opened in 2019", while complex verifications still route through the coordinator.

A single tool can also be too broad. A document analysis subagent with a generic fetch_url fetches whatever a link points to, so a citation that leads to a news homepage gets analysed as the report. A constrained load_document, which validates that the URL is a document first, turns that silent mistake into a clear error. On the support agent, update_shipping_address replaces a generic update_account(field, value) that could reach credit_balance.

In the guide's forced-selection example, extract_metadata must run before any enrichment tool. Forcing it on the first request guarantees that, and subsequent steps run in follow-up turns under a looser setting, because forcing it every time would trap the pipeline. "any" fits a turn that must end in a tool call when the right tool depends on the input.

// request 1
tool_choice: {"type": "tool", "name": "extract_metadata"}
→ extract_metadata  {"doc_type": "dataset", "published": "2026-03"}
// request 2: some tool, Claude picks
tool_choice: {"type": "any"}  → extract_dataset, not extract_findings
// follow-up turns: enrichment or text
tool_choice: {"type": "auto"}
For each tool an agent holds, ask: Does this agent's role explain why it holds this tool?
YesKeep it.
No, and the need is rare or complexRemove it. Route that work to its own agent or through the coordinator.
No, but the need is frequent and simpleGive a narrow cross-role tool instead, like check_stock or verify_fact.
Takeaway
  • Every tool an agent holds competes on every turn, so 4–5 role tools select more reliably than 18.
  • Scope a subagent with the tools list in its AgentDefinition. Omit the list and it inherits every tool.
  • "any" guarantees a tool call and a forced tool guarantees that tool, each for one request only.

check yourself

0 / 3 answered

In about 60% of return conversations the customer asks whether a replacement is in stock. The support agent cannot check, so it calls escalate_to_human and ops replies hours later. Ops runs a 9-tool agent that includes reorder_stock. Customers must get the stock answer in the same reply, with no hand-off to another agent, and stock changes must stay with ops.Which change best gives customers the answer while keeping stock changes with ops?

Select one.

A nightly job tags closed support transcripts by calling one of three tools: tag_refund, tag_billing or tag_account. About 1 run in 30 returns prose such as "This looks like a billing issue", and the parser fails. redact_pii must run before any tag tool. The model in use supports forced tool use.Which TWO tool_choice settings best meet both requirements?

Select two.

After the billing team's tools were added, the support agent holds 15 tools. A customer writes "I was charged twice for order 10031552" and the agent calls void_invoice, a billing-only tool. The logs show tool_choice is auto, process_refund's description names duplicate charges, and no process_refund call or error occurred.What is the most likely root cause?

Select one.

sources

  1. Claude Platform Docs, "Define tools", Forcing tool use: the four tool_choice options and their defaults, the prefilled reply under any and tool, and the 400 error on the newest Opus, Sonnet, Fable and Mythos models and under manual extended thinking. Checked 2026-10-01.
  2. Claude Code Docs, "Subagents in the SDK": AgentDefinition tools (omitted means every tool available to subagents; a tool left out "isn't in the subagent's session at all") and disallowedTools with mcp__server__* patterns. Checked 2026-10-01.
  3. The 18 versus 4–5 figure, the synthesis agent attempting web searches, verify_fact and the 85% figure, fetch_url / load_document, and extract_metadata before enrichment tools: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 2.3 and Sample Question 9. Scenario and tool names: the guide's Scenarios 1 and 3. The other tool names are this course's illustrations.