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.
share
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
Choose what the support agent holds.
Choose what the support agent holds.
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.
Default when tools are supplied.
{"type": "auto"}Guarantees Nothing. Claude may answer in text.
{"type": "any"}Guarantees A tool call. Claude picks which.
{"type": "tool",
"name": "get_customer"}Guarantees That tool, on this request.
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.
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"}
| Yes | Keep it. |
| No, and the need is rare or complex | Remove it. Route that work to its own agent or through the coordinator. |
| No, but the need is frequent and simple | Give a narrow cross-role tool instead, like check_stock or verify_fact. |
- Every tool an agent holds competes on every turn, so 4–5 role tools select more reliably than 18.
- Scope a subagent with the
toolslist in itsAgentDefinition. 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.