Domain 2 · Lesson 1 · Tool Design & MCP (18%)
Designing Tool Interfaces
Task Statement 2.1 — the description IS the interface, and how overlap causes misrouting.
Course progress: Domain 2 ▸ lesson 1 of ~4
The model does not read your code. It reads your tool descriptions. Those descriptions are the primary — often the only — signal it uses to pick a tool. Weak descriptions are the number-one cause of tool-selection failures.
What a good description contains
"Retrieves order details" is a distractor-grade description. A production description states:
- Purpose — what the tool does and why.
- Input formats it accepts (e.g., order IDs like
#12345 vs emails).
- Example queries that should route here.
- Edge cases and boundaries — and crucially, when to use this tool vs a similar one.
Root-cause rule
When two similar tools get confused (e.g., get_customer vs lookup_order, both "Retrieves … information"), the correct first step is to expand the descriptions to differentiate purpose, inputs, and boundaries — not to add a routing layer, not to consolidate tools, and not (as a first move) to add few-shot examples.
Why not the other options?
| Tempting fix | Why it's not the first step |
|---|
| Add few-shot examples of correct routing | Adds token overhead without fixing the root cause (thin descriptions). A later refinement, not the first lever. |
| Build a routing layer that pre-selects tools by keyword | Over-engineered; bypasses the LLM's own language understanding. |
Consolidate into one lookup_entity tool | Valid architecture eventually, but heavier than a "first step" when the real problem is inadequate descriptions. |
Splitting vs renaming
Two structural techniques the exam expects you to apply:
- Rename + re-describe to kill overlap:
analyze_content → extract_web_results with a web-specific description.
- Split a generic tool into purpose-specific tools with defined I/O contracts:
analyze_document → extract_data_points, summarize_content, verify_claim_against_source.
Watch the system prompt too
Subtle trap
Keyword-sensitive system-prompt wording can override even a well-written tool description. If the prompt says "when users mention documents, analyze them," it may create an unintended association pulling calls to the wrong tool. Review the system prompt for keyword coupling as part of debugging tool selection.
Check yourself
Two tools with minimal near-identical descriptions get confused on ambiguous requests. The most effective first step is to:
- Expand each description with inputs, examples, and use-vs boundaries
- Add five to eight few-shot routing examples to the system prompt
- Insert a keyword routing layer that pre-selects the tool per turn
- Merge both tools into one that infers the backend internally
Correct: option 1. Descriptions are the primary selection signal; thin descriptions are the root cause, and expanding them is the low-effort, high-leverage first fix. Few-shot (2) is overhead without fixing the cause; a routing layer (3) is over-engineered; consolidation (4) is heavier than a first step warrants.
A generic analyze_document tool is used inconsistently for extraction, summarization, and verification. The cleanest structural fix is to:
- Add a mode parameter and describe each mode inside one tool
- Split it into purpose-specific tools with defined I/O contracts
- Force tool_choice so the document tool always runs first each turn
- Move its logic into the system prompt as inline instructions
Correct: option 2. Splitting a generic tool into specific tools (extract / summarize / verify) with clear contracts removes ambiguity at the selection layer. A mode param keeps the ambiguity inside one description; forcing order and inlining don't address selection clarity.
Decision rules
Tool confusion → fix descriptions first. Persistent overlap → rename/re-describe or split into specific tools. Still misrouting → audit system prompt for keyword coupling.
Ask your teacher. Want a worked before/after of a bad vs good tool description? Ask.