2.1 Designing Tool Interfaces

In Domain 1 you gave an agent tools and let it choose which to call. We glossed over a crucial question: HOW does the model decide which tool fits a request? The answer surprises people, and it's the foundation of all of Domain 2 — the model chooses a tool almost entirely by reading its DESCRIPTION. Not the tool's name, not some hidden wiring; the plain-language description you wrote is the primary thing the model uses to pick.

Think of it like a new employee on their first day, handed a drawer of unlabelled keys. They have no idea which key opens which door — they'll fumble, try the wrong ones, maybe unlock something they shouldn't. Now give each key a clear tag: 'front entrance', 'supply closet — NOT the server room.' Suddenly they choose correctly every time. A tool's description is that tag. Write vague tags and the model fumbles; write precise ones and it picks the right tool reliably.

This reframes tool design entirely. Designing a good tool isn't mainly about the code behind it — it's about writing a description clear enough that the model never has to guess. Task Statement 2.1 is about exactly that craft: writing descriptions that differentiate tools, and fixing the misrouting that vague descriptions cause.

So what does a good description actually contain? Compare two versions of the same tool. Minimal: "Retrieves customer information." Production-grade: "Retrieves a customer's account details by customer ID or email. Use for profile, contact, and account-status questions. Do NOT use for order-specific queries — use lookup_order instead. Input: a customer_id (format: CUST-12345) or an email address." The second one tells the model not just WHAT the tool does but exactly WHEN to reach for it and when not to.

A production-grade description carries five things, and you can treat them as a checklist. Miss any of them and you've left the model room to guess.

• 1.Primary purpose — what the tool does, in one clear sentence.
• 2.Input expectations — types, formats, constraints, and which inputs are required vs optional (e.g. 'customer_id in the form CUST-12345').
• 3.Example queries — the kinds of requests that should route here, in the words a user would actually use.
• 4.Edge cases and limitations — what it can't do, so the model doesn't over-reach.
• 5.Explicit boundaries vs similar tools — 'use this NOT that' — the single highest-leverage line when you have look-alike tools.

Here's the failure the exam tests most in 2.1. You have two tools — get_customer ("Retrieves customer information") and lookup_order ("Retrieves order details") — both with minimal descriptions and both accepting similar-looking identifiers. In production, the agent keeps calling get_customer when users ask about orders ("check my order #12345"). It's misrouting: the descriptions are too similar for the model to tell them apart, so it picks wrong.

Now the trap. Four fixes look plausible: (A) add 5–8 few-shot examples of correct routing; (B) EXPAND each description with formats, example queries, edge cases, and explicit boundaries; (C) build a routing layer that parses the user's words and pre-selects the tool; (D) consolidate the two tools into one lookup_entity. The exam wants the most effective FIRST step — and that's B. The root cause is inadequate descriptions, so fixing the descriptions addresses the cause directly, with the least effort.

Why the others lose: few-shot examples (A) add token overhead on every call without fixing the underlying ambiguity; a routing layer (C) is over-engineering that bypasses the model's own language understanding; consolidating tools (D) is a legitimate architectural option but is MORE effort than a 'first step' warrants when the immediate problem is just thin descriptions. The principle generalises: when tools misroute, reach for better descriptions before reaching for machinery.

Beyond expanding descriptions, two reshaping techniques help when a tool is doing too much or is poorly named. SPLITTING: a vague catch-all like analyze_document is hard to route to because it does many things; split it into purpose-specific tools — extract_data_points, summarize_content, verify_claim_against_source — each with a crisp input/output contract the model can match precisely. RENAMING: a tool called analyze_content that only handles web results is misleadingly broad; rename it extract_web_results and give it a web-specific description, eliminating overlap with other analyzers.

There's one more catch the exam likes, and it's easy to miss: the SYSTEM PROMPT can quietly override your careful tool descriptions. Keyword-sensitive instructions in the system prompt can create unintended associations — for instance, a system prompt that says 'always summarize content for the user' might nudge the model toward a summarize tool even when extraction is what's needed. So when you're debugging tool selection, don't stop at the descriptions; review the system prompt for wording that competes with them.

The 2.1 traps all reward the same instinct: when tool selection goes wrong, fix the DESCRIPTION first, before reaching for heavier machinery. The wrong answers consistently offer more infrastructure where a clearer description would do.

You now understand that descriptions drive selection, what a production-grade description contains, how to fix misrouting at its root, and the reshaping and system-prompt nuances. The exercise makes the cause-and-effect concrete: you'll watch routing accuracy jump just by rewriting descriptions, no new infrastructure required.

Descriptions get the model to call the RIGHT tool. The next lesson, 2.2, is about what happens when that tool FAILS — and how to report the failure so the agent can recover intelligently instead of flailing.