Design effective tool interfaces with clear descriptions and boundaries

Every tool you give Claude, whether through the API tools array or an MCP server, is defined by three things: a name, a description, and an input_schema. When Claude chooses which tool to call, it reasons almost entirely from the description and the parameter docs. It never sees your source code or your intentions, so the description is the single highest-leverage field you control.

Anthropic's guidance is direct: write detailed descriptions, ideally more than three or four sentences per tool. Cover what the tool does, when to use it, when NOT to use it, and what each parameter means. A one-line description like 'Retrieves order details' gives the model almost nothing, and that thin signal collapses the moment two tools look alike.

name: lookup_order
description: Look up ONE order by its order ID (format ORD- followed by 8 digits). Returns line items, status, and totals. Use only when the user names a specific order or order number. Do NOT use to identify a customer, call get_customer first.
input: { order_id: string }  # e.g. ORD-10482913

A strong description answers four questions: what the tool does, what inputs it expects (formats, units, valid ranges, example values), what it returns, and when to use it versus similar tools. Add example queries and describe edge-case behavior, such as what happens on no match or on an ambiguous identifier.

Explicit boundary statements are what let Claude separate near neighbors. A line like 'Use this only for web search result lists, never for local document text' is worth more than any amount of generic prose. Boundaries turn an ambiguous menu into a decision the model can actually make.

This is exactly the fix in the customer-support scenario: get_customer and lookup_order both said only 'Retrieves ... information' and accepted similar identifier formats, so the agent routed 'check my order #12345' to get_customer. Expanding both descriptions with input formats, example queries, edge cases, and explicit boundaries is the first, highest-leverage change, higher leverage than few-shot examples or an external router.

Misrouting is usually a symptom of overlap, two tools whose descriptions are so similar the model has no basis to choose. The canonical example: analyze_content and analyze_document both described as 'Analyzes content'. Whichever one the model picks is essentially a coin flip, and web results end up in the document analyzer or vice versa.

You have two levers. First, rename and rescope: change analyze_content to extract_web_results and rewrite its description so it is unambiguously about web search hits (URLs, titles, snippets), not documents. A precise name is a compressed hint the model reads before it even reaches the description. Second, split the generic tool (covered next). Either way, the goal is that any given request maps to exactly one obvious tool.

When one tool tries to do several jobs, its description cannot be precise about any of them, and its input/output contract stays vague. The fix is single responsibility: split the generic tool into purpose-specific tools, each with a defined input and output.

For a research system, a catch-all analyze_document becomes three sharp tools:

analyze_document  ->  split into:
  extract_data_points          in: doc text + fields[]     out: { field: value }
  summarize_content            in: doc text + max_length   out: summary string
  verify_claim_against_source  in: claim + source          out: { supported: bool, evidence }

Each tool now has an obvious purpose, a tighter schema, and clearer errors. The trade-off is more tools, so do not split without reason: giving one agent too many tools hurts selection on its own (see task 2.3). The principle here is purpose-specific, not tool-maximizing. Split when jobs are genuinely distinct, and keep each agent's set scoped to its role.

Even a well-written tool interface can be overridden by the system prompt. Tool selection is keyword sensitive: if your system prompt says 'analyze the document' and you have a tool literally named analyze_document, that lexical match can pull the model toward it even when a better tool exists. The prompt created an unintended tool association.

So when tools misfire and the descriptions already look good, audit the system prompt for wording that echoes a tool name. Neutralize the phrasing (say 'review the file' or 'process the input' instead of a phrase that mirrors a tool name), or align the wording with the tool you actually want. The lesson: the tool interface is the name, the description, the input_schema, AND the surrounding prompt, all working together.

The same rules apply to MCP tools. An MCP server advertises each tool with a name, a description, and an inputSchema, and Claude Code discovers all of them at connection time. If those descriptions are thin, the agent may prefer a built-in tool (for example Grep) over a more capable MCP tool, so write MCP tool descriptions that spell out capabilities and outputs in detail.

Do not stop at the description. Parameter names and their per-field descriptions in the input_schema also guide both selection and argument filling. Prefer descriptive field names (order_id, not id), add a short description to each field, and mark required versus optional accurately. A clean, self-documenting schema reduces malformed calls and reduces the model's need to guess.