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

Element	Example
What it returns	"Returns the full order record including line items, shipment status, and payment state."
Input format, precisely	"Requires an exact order ID in the format `ORD-XXXXXXXX`."
When to use it — example queries	"Use when the customer references a specific order number, e.g. 'where is order ORD-10023841'."
Edge cases	"Returns an empty record if the order exists but has been archived after 7 years."
Explicit boundaries against neighbours	"Does NOT search by customer name, email, or date range — call `get_customer` first to obtain order IDs."

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:

Before	After
`analyze_document`	`extract_data_points`
	`summarize_content`
	`verify_claim_against_source`

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.

🧠 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:

Option	Verdict
Give the synthesis agent a narrowly scoped `verify_fact` that checks claims against already-collected sources	✅ Correct. Covers the 85% case with least privilege; the remaining 15% routes back through the coordinator
Give it full web-search access	❌ Grants far more capability than the need requires; invites scope creep into research
Give it a general `fetch_url` tool	❌ Same problem, plus no validation — see below
Route all verification back to the coordinator	❌ Adds a round trip for the 85% common case

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.

Form	Behaviour
`{"type": "auto"}`	Model decides whether to call a tool and which one. The default.
`{"type": "any"}`	Model must call one of the available tools; it chooses which
`{"type": "tool", "name": "extract_invoice"}`	Model must call that specific tool

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.

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.

Answer and reasoning

Two conceptually distinct tools with one-line descriptions and overlapping names is the textbook description problem. The model has no basis for discriminating. Expanding both descriptions with formats, examples, and explicit mutual boundaries is low-effort, addresses the root cause directly, and is the guide's own prescription.

A — Might be defensible eventually, but it's a redesign, and it discards a real distinction. Not a first step.
C — Adds a whole component to solve a wording problem. Over-engineering (Reflex 2), plus the routing agent would face the same ambiguity.
D — Forcing a tool requires your code to already know which one is right, which means you've moved the decision out of the agent entirely. That defeats the purpose and doesn't scale past two tools.

Reflex applied: #3 (descriptions are the selection mechanism) and #2 (lowest-effort root-cause fix).

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).