Task statement 2.1 · Tool design and MCP integration

Design effective tool interfaces with clear descriptions and boundaries

A customer writes "My account shows order 10024871 as delivered, but it never came", and the support agent calls get_customer instead of lookup_order. Neither tool is broken, but nothing the model read told the two apart.

Why it's tested

The tempting fixes all add machinery. Five to eight few-shot examples, meaning sample requests paired with the right tool, help only the phrasings they show, cost tokens on every request, and leave the thin descriptions in place. A keyword routing layer bypasses the model's language understanding and breaks on a message like this one, which mentions both an account and an order. Merging both tools into one lookup_entity can be sound design, but it is far more work than a first step warrants.

KnowledgeWhat the model reads when it picks a tool

When you send tools with a request, the API builds a system prompt from each tool's name, description and input schema, then adds your own system prompt. The input schema is written in JSON Schema, a machine-readable list of the fields a call may carry. It shows what a valid call looks like but not when to make one, so tool descriptions are the primary mechanism the model uses for tool selection. Anthropic's docs call the description "by far the most important factor in tool performance". Minimal descriptions therefore lead to unreliable selection among similar tools: "Retrieves order details" fits the delivery complaint no better than "Retrieves customer information" does.

Your system prompt is read in the same pass, so its wording steers selection too. A keyword-sensitive instruction such as "For anything about accounts, use get_customer" creates an unintended tool association between the word account and that tool, whatever the customer is asking. This customer says "account" but asks about a delivery, so the line sends the request to get_customer even after both descriptions are fixed. One such line can override well-written tool descriptions, so a misrouting review always reads the system prompt too.

Interactive · one message, three things the model can read

A customer message and the system prompt both flow down into tool selection, which also reads the two tool descriptions and routes the message to get_customer or lookup_order. Buttons switch between minimal descriptions, differentiated descriptions, and differentiated descriptions with a keyword-sensitive system prompt line. customer message "account shows 10024871 delivered" system prompt no routing instructions "Anything about accounts: get_customer" request read with the tools tool selection names + descriptions + prompt wrong tool here right tool here get_customer "Retrieves customer information" "By email, phone or C-ID. Not for orders." lookup_order "Retrieves order details" "8-digit order no. Missing deliveries." can land on either tool — nothing tells them apart routes to lookup_order — the boundaries decide it back to get_customer — the prompt line overrides

Minimal descriptions, neutral prompt.

Differentiated descriptions, neutral prompt.

Same descriptions, plus a keyword line.

Minimal: both descriptions are one line and neither names an input format or a boundary, so the delivery complaint can land on either tool. Production logs show it often lands on get_customer. Differentiated: get_customer says it is not for questions about one order, and lookup_order names the 8-digit input and missing deliveries, so the message has one obvious destination. Keyword line: the descriptions are unchanged, but the system prompt ties the word account to get_customer. The customer wrote "account", so the unintended tool association wins over the descriptions.

KnowledgeWhat a description has to say

A description that routes reliably differentiates its tool from similar ones. It states the purpose and outputs, the expected inputs with their input formats, one or two example queries, the edge cases that would otherwise fail, and a boundary explanation: when to use this tool versus the similar alternative, by name. Ambiguous or overlapping tool descriptions leave the model guessing, and a guess that is sometimes wrong is misrouting. As Anthropic's engineers put it, "When tools overlap in function or have a vague purpose, agents can get confused about which ones to use."

SkillFixing the misrouting: descriptions first, then the prompt

Production logs show order questions landing on get_customer. The cause is two one-line descriptions: both tools accept an ID, and neither says what it is not for. The fix rewrites both, with one sentence per item in the list above.

Before · what shipped

Both tools, one line each

get_customer
"Retrieves customer information"

lookup_order
"Retrieves order details"

Result: neither names the other, so the model has no basis to choose.

After · both rewritten
get_customer
"Look up one customer by email, phone
 or customer ID (C-4471). Returns the
 profile, account status and recent
 order numbers. Use it first to confirm
 who is writing. Not for questions
 about one order: an 8-digit number is
 an order number, so use lookup_order."

lookup_order
"Look up one order by its 8-digit
 number (10024871; customers may type
 #10024871). Returns items, status,
 delivery date and refund eligibility.
 Use for 'where is my order?', returns
 and missing deliveries. No number?
 Call get_customer to list orders."

Result: each boundary names the other tool and the input that belongs to it.

With both rewrites, the delivery complaint reaches lookup_order. If a message still misroutes, review the system prompt for keyword-sensitive instructions next. "For anything about accounts, use get_customer" becomes "Use get_customer to confirm who the customer is, and lookup_order for questions about a specific order", which names an intent rather than a word. Few-shot examples and routing layers come after these two cheaper fixes.

SkillWhen no description can fix it: split or rename

Some tools cannot be described clearly because they do several jobs. get_account_info returns a profile with no include argument, charge rows with include: "billing", and ticket ids with include: "tickets". Nothing tells the model which value gives which shape, so it guesses, and every later step must handle all three. Splitting generic tools into purpose-specific tools with defined input/output contracts gives each job one name, one set of inputs and one output.

One vague contract
get_account_info(customer_id,
                 include?)
→ no include:        a profile
→ include "billing": charge rows
→ include "tickets": ticket ids

The output shape depends on an argument the description never explains.

Three defined contracts
get_customer(customer_id)
→ profile + account status
get_billing_history(customer_id, months)
→ dated charge rows
list_open_tickets(customer_id)
→ ticket ids + statuses

Each tool has one job, one input contract and one output shape.

Scenario switchThe guide's examples for this skill come from its research scenario. They are walked here as the guide writes them.

In the guide's system, analyze_content and analyze_document had near-identical descriptions, so a request about web search results could land on either. The first fix is renaming tools and updating descriptions to eliminate functional overlap: analyze_content becomes extract_web_results with a web-specific description, so the names stop competing. The second splits the generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source, each stating what it takes and returns.

// before: near-identical (wording illustrative)
analyze_content   "Analyzes content."
analyze_document  "Analyzes a document."
// after (signatures illustrative)
extract_web_results(results)      → facts per web result, never uploaded files
extract_data_points(doc_id, fields) → {field: value}
summarize_content(doc_id, max_words) → summary text
verify_claim_against_source(claim, doc_id) → supported | contradicted | absent

KnowledgeSplitting versus consolidating

Anthropic's tool-use docs also recommend consolidating related operations, such as one tool with an action parameter instead of create_pr, review_pr and merge_pr, because fewer tools reduce selection ambiguity. Both directions pass one test: can the model predict what each call needs and returns? A consolidated tool passes when every action value is documented, and get_account_info fails because its include values are not. For misrouting, the guide's Sample Question 2 calls merging into lookup_entity "a valid architectural choice", but more effort than a first step warrants.

More precise than the guide. The guide teaches splitting generic tools, while Anthropic's Define tools page recommends one tool with an action parameter for related operations, and its engineering article suggests workflow tools such as get_customer_context (checked 2026-10-01). Exam answer: split a generic tool with unpredictable outputs into purpose-specific tools with defined input/output contracts, and fix descriptions before consolidating tools that misroute.

Before adding examples or a router, ask: What is the model reading that points it to the wrong tool?
Thin or near-identical descriptionsRewrite both: purpose, input format, example query, edge case and boundary. Rename a tool whose name competes.
A keyword instruction in the system promptRewrite the line around the customer's intent, not a word.
One tool whose output depends on a hidden argumentSplit it into purpose-specific tools with defined contracts.
Takeaway
  • Descriptions are the primary selection mechanism, so two one-line descriptions make similar tools interchangeable.
  • A system-prompt line keyed to a word such as "account" can override correct descriptions.
  • The guide splits generic tools, and the docs also accept one tool with a documented action parameter.

check yourself

0 / 3 answered

The system prompt says "If the customer mentions a refund, use process_refund." All four tool descriptions were rewritten last month and state their boundaries, and lookup_order's lists refund status among its outputs. A customer asks "Has my refund for order 10024871 gone through?", and the agent calls process_refund, issuing a second $80 refund.Which change most directly removes the cause of the duplicate refund?

Select one.

process_refund takes an undocumented type argument: "refund" returns a refund id, "credit" a store-credit code, and "exchange" a new order number. Customers who ask for their money back sometimes receive store credit instead. The payments team needs each kind of operation to appear under its own tool name in the tool-call audit log.Which TWO changes best stop the wrong operation while meeting the audit requirement?

Select two.

After a rewrite, lookup_order reads: "Look up one order by its 8-digit number (10024871). Use for delivery and return questions." Orders placed before 2024 carry numbers such as SO-4471902, which the tool also accepts. "Where is SO-4471902?" goes to get_customer, which finds no customer. The system prompt has no routing instructions.What is the most likely root cause?

Select one.

sources

  1. Claude Platform Docs, "Define tools": the tool-use system prompt built from tool definitions and your system prompt; descriptions as "by far the most important factor in tool performance", at least 3–4 sentences; consolidating related operations into one tool with an action parameter. Checked 2026-10-01.
  2. Anthropic Engineering, "Writing effective tools for agents": "When tools overlap in function or have a vague purpose, agents can get confused about which ones to use", and consolidated workflow tools such as get_customer_context. Checked 2026-10-01.
  3. The analyze_content / analyze_document examples, keyword-sensitive instructions and "unintended tool associations": Claude Certified Architect — Foundations Exam Guide v1.0, Domain 2.1. The lookup_entity option and "a valid architectural choice": Sample Question 2. Scenario and tool names: the guide's Scenario 1. The descriptions, get_account_info and the signatures are this course's illustrations.