Chapter 05 — Tool Interface Design

Domain 2: Tool Design & MCP Integration (18%) — task statements 2.1, 2.4

One idea dominates this domain: the tool description is the primary mechanism by which the model selects tools. Almost every Domain 2 item is a consequence of that.

1. Descriptions are the selection mechanism

The model does not have access to your implementation, your team's naming conventions, or your intent. When it decides which tool to call, it is reading the tool's name and description. Nothing else.

Therefore: a tool-selection bug is a description bug until proven otherwise.

🎯 What a good description contains

The last element is the one people omit and the one the exam cares most about. A description that only says what a tool does leaves the model to infer what it doesn't do.

🚫 Overlapping descriptions cause misrouting

The guide's example: two tools named analyze_content and analyze_document. Both descriptions plausibly cover "look at this thing and tell me about it." The model routes inconsistently between them — sometimes correctly, sometimes not, with no pattern the team can debug.

The root cause is semantic overlap, not model error. The fix is to make the boundary explicit in both descriptions, or to eliminate the overlap by restructuring the tools.

🎯 Renaming and splitting generic tools

A tool named analyze_document is generic: "analyze" covers extraction, summarization, verification, classification, and more. The model can't tell which of those you meant, and neither can a reviewer.

The guide's remedy — split it into purpose-specific tools:

Each of the three now has an unambiguous purpose, a distinct input schema, and a description that can state a real boundary. This is the structural fix; rewriting the description is the cheaper fix.

📎 Renaming and re-describing — the guide's own worked example

There is a third move between "rewrite the description" and "split the tool," and the guide gives it by name: rename the tool and update its description together, to eliminate the functional overlap.

The guide's example, from the Multi-Agent Research scenario. Two tools overlap:

The fix is not to split either tool. It's to rename the web-facing one to reflect what it actually does and rewrite its description to match:

Now the two names occupy different semantic territory, and the descriptions reinforce rather than blur the boundary. Overlap eliminated without restructuring anything.

⚠️⚠️ The trap, and it is a real one. Renaming alone is a weak fix — a better name with the same vague description leaves the model with the same ambiguity to resolve, and it will keep misrouting. That is why "just rename the tools" appears as a distractor in some items. But renaming together with a matching, scope-specific description is exactly what the guide prescribes.

🧠 So read the option text carefully:

🧠 Which one does the exam want? Follow Reflex 2 — lowest-effort change that removes the root cause:

• If the tools are conceptually distinct and only the wording is ambiguous → rewrite the descriptions. This is the answer to the published sample question on misrouting: expand the descriptions with input formats, example queries, and boundaries. Low effort, high leverage.
• If a single tool is genuinely doing several unrelated jobs → split it. No wording can disambiguate a tool whose purpose is actually plural.

Read the stem for which situation you're in. "Two similar tools are confused with each other" → descriptions. "One tool is used for four different purposes and behaves inconsistently" → split.

⚠️ Audit the system prompt too

A less obvious cause of misrouting: keyword-sensitive instructions in the system prompt. If the system prompt says "when the user asks about a document, use the document tool," and the user says "look at this file," the phrasing mismatch can push the model to the wrong tool. When descriptions look clean but routing is still wrong, check whether the system prompt is fighting them.

2. Tool distribution across agents

Task statement 2.4.

🎯 The number matters

The guide is explicit and quantitative: giving an agent 18 tools instead of 4–5 measurably degrades selection accuracy. More tools means more opportunities for semantic overlap and more candidates to discriminate among.

So tool distribution is a design decision, not a convenience:

❌ Every agent gets every tool ("simpler to configure")
   → degraded selection, agents wandering outside their specialization

✅ Each agent gets the tools its role requires
   → 4–6 tools per agent, clean boundaries, reliable selection

🚫 Agents misuse tools outside their specialization

Give the synthesis agent full web access and it will start doing its own research instead of synthesizing what it was given. This isn't misbehaviour — it's the predictable result of handing a capability to an agent whose prompt doesn't scope it.

🎯 Scoped variants beat general tools

The highest-value pattern in this section, and the subject of a published sample question.

Situation: the synthesis agent needs to verify facts. Occasionally — say 15% of the time — verification requires fetching a source it doesn't already have. 85% of the time, the fact can be verified against material already collected.

The options and why they rank as they do:

The rule: scope the common case into a purpose-built tool; route the exception. Least privilege isn't only a security posture here — it's an accuracy technique, because a narrower toolset selects better.

⚠️ Replace unvalidating tools with validating ones

A generic fetch_url accepts anything and returns whatever comes back. The guide's preferred replacement is a load_document that validates — checking that the target is an acceptable type and that the content is usable before it enters the agent's context. Prefer the tool that fails cleanly at the boundary over the one that passes garbage inward.

3. tool_choice — controlling whether tools are used

📎 Three forms. This is bare recall; know it exactly.

Mapping to intent:

• Agentic operation → auto. The agent needs the freedom to answer directly when it has enough information.
• Every turn must produce a tool call → any. Less common; used when text-only replies are never valid.
• Structured output → forced specific tool. You're using the tool's input_schema as an output contract rather than as an action. This is the Chapter 10 mechanism.

⚠️ Under any or a forced tool, the model cannot respond with "nothing applies here." If your extraction schema needs to express absence, that must live in the schema as nullable fields or an "unclear" enum value — not in a relaxed tool_choice.

🎯🎯 Forced selection to control tool ordering

This is the tool_choice use most candidates miss, and the guide names it explicitly in both Domain 2 and Domain 4. Forcing a tool isn't only for structured output — it's also how you guarantee that a particular tool runs first.

The guide's example: you need extract_metadata to run before any enrichment tools. Prompt instructions like "always call extract_metadata first" have a non-zero failure rate (Reflex 1). The deterministic version:

# Turn 1 — force the prerequisite. The model has no option to skip it.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    tools=[extract_metadata, enrich_company, enrich_financials],
    tool_choice={"type": "tool", "name": "extract_metadata"},
    messages=messages,
)

# Turn 2+ — hand back the tool_result and relax to auto so the model
# chooses the enrichment steps itself.
messages += [assistant_turn, tool_result_turn]
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    tools=[extract_metadata, enrich_company, enrich_financials],
    tool_choice={"type": "auto"},
    messages=messages,
)

📎 The two-part shape is the examinable content: force the first tool on the first turn, then process the subsequent steps in follow-up turns with auto. Forcing every turn would trap the agent — it could never terminate, because it must always call something.

🧠 Contrast with the two neighbouring mechanisms, because all three appear as options in the same item:

⚠️ Forced tool_choice controls ordering at the start. It does not enforce a precondition mid-conversation — once you relax to auto, nothing stops the model calling a tool out of order. For guarantees that must hold on every call (refunds, writes, anything irreversible), you still need the hook.

🎯 Setting any when the document type is unknown

One more mapping the guide states directly: when you hold several extraction schemas and you don't know which document type has arrived, use tool_choice: "any". The model must produce structured output, but it picks which schema fits. Forcing one specific tool would be wrong — you'd be asserting a document type you haven't determined.

4. Worked example

A research system has two tools: analyze_content, which the team intended for web pages, and analyze_document, intended for uploaded PDFs. Logs show the agent frequently calls analyze_content on PDFs and analyze_document on web pages. Both tools have one-line descriptions. What is the most effective first step?

A. Consolidate both into a single analyze tool that handles either input type. B. Expand both tool descriptions to specify accepted input formats, example queries, and explicit boundaries against each other. C. Add a routing subagent that classifies the input type and selects the tool. D. Use tool_choice to force the correct tool on each call.

5. Decision reflexes (reproduce from memory)

• Tool descriptions are the primary tool-selection mechanism. Misrouting = description problem first.
• A good description states: what it returns, exact input format, example queries, edge cases, and explicit boundaries against neighbouring tools.
• Two similar tools confused → rewrite descriptions. One generic tool doing several jobs → split it (analyze_document → extract_data_points / summarize_content / verify_claim_against_source).
• If descriptions look fine, audit the system prompt for keyword-sensitive routing instructions.
• 18 tools instead of 4–5 degrades selection. Distribute by role; 4–6 per agent.
• Scope the common case with a narrow purpose-built tool; route the exception through the coordinator. Least privilege improves accuracy, not just security.
• Prefer validating tools (load_document) over permissive ones (fetch_url).
• tool_choice: auto (default) · any (must call something) · {"type":"tool","name":...} (forced → structured output).