Tool descriptions and boundaries

What you’ll be able to do

Write tool descriptions that state purpose, input formats, outputs, example queries, edge cases, and when to use each tool instead of a similar one
Diagnose misrouting between tools with overlapping names or descriptions, and fix it by renaming and rewriting descriptions
Split a generic tool into purpose-specific tools, each with a defined input/output contract
Review system prompts for keyword-sensitive instructions that override well-written tool descriptions

What you need to know

The description is how the model chooses

When Claude has several tools available, it doesn't see your code or your intentions. It sees each tool's name, description, and input schema, and it chooses based on those. So the description is the main way the model decides between tools. A one-line description such as "Analyzes content" is enough when there's only one tool. Once a similar tool sits next to it, the model has nothing to tell them apart, and its choices become inconsistent across requests that look almost the same.

A description that works at selection time answers the questions the model has right then:

Purpose: what the tool does, in terms of its effect ("returns the current order status and shipping events for one order"), not its internals ("queries the v2 orders service over gRPC").
Input formats: which identifiers or values it accepts, and in what shape (order numbers like #12345, ISO dates, full URLs).
Example queries: one or two requests it is meant for.
Edge cases: what happens with partial input, no match, or several matches.
Boundaries: when to use a neighboring tool instead, stated by name.
Output: what comes back, so the model can plan its next step.

Overlap causes misrouting

Two tools can each be fine on their own and still break the system together. The guide's example is analyze_content and analyze_document with near-identical descriptions: the model sends web search results to one and uploaded PDFs to the other more or less at random, because nothing in what it reads separates them.

The fix starts with the names and descriptions. Rename the tool whose name hides its scope, for example analyze_content becomes extract_web_results with a description that says it handles web search results, and give both tools boundary statements that point at each other. If you only rewrite one side, the vague tool still looks like it could handle the request.

before — two tools the model can't tell apart

analyze_content: "Analyzes the provided content and returns findings." analyze_document: "Analyzes a document and returns findings."

after — renamed, with inputs, outputs, and boundaries on both sides

extract_web_results: "Extracts titles, snippets, URLs, and publication dates from web search results. Input: the raw result list from web_search. Use for anything that came from a web search. For uploaded files (PDF, DOCX), use analyze_document instead." analyze_document: "Extracts key findings from one uploaded document. Input: a document ID from the upload store. Returns findings with page references. Do not use for web search results; use extract_web_results."

Other fixes are heavier and come later, if at all. Few-shot examples of correct tool choice add tokens and don't fix the descriptions. A keyword-based router in front of the model ignores the model's understanding of the request. Merging tools changes the interface for every caller. All three can be valid in some designs, but none of them is the best first step when the descriptions are the root cause.

Split generic tools into clear contracts

Sometimes the overlap is inside one tool. A generic analyze_document that might extract figures, summarize, or fact-check, depending on how it is called, has no single input/output contract, and its description can't say clearly when to use it. Splitting it into purpose-specific tools gives each one a description that is easy to write and easy to choose:

extract_data_points: document in, list of named values with locations out.
summarize_content: document in, summary of a stated length out.
verify_claim_against_source: a claim and a source in, verdict with the supporting passage out.

Each new tool has defined inputs and outputs, so both the model and downstream code know what they will get.

The system prompt can override good descriptions

Tool selection depends on everything in context, not only the tool list. A system prompt instruction tied to a keyword, such as "When the user mentions a document, analyze it thoroughly", can link the word "document" to analyze_document strongly enough that the model uses it for a web article the user calls "this document". The tool descriptions can be perfect and the misrouting will continue, because the prompt is pushing the other way.

When misrouting persists after the descriptions are fixed, read the system prompt for instructions keyed to words that also appear in other tools' territory. Reword them in terms of the task ("when the user provides an uploaded file…") or remove them, and let the tool descriptions do the routing.

Key concept

Tool descriptions are the main input the model uses to choose a tool. Make each one state purpose, inputs, outputs, examples, edge cases, and its boundary against similar tools. Fix overlap by renaming, rewriting both sides, or splitting, and check that the system prompt isn’t pulling the other way.

When a scenario says the model "picks the wrong tool" between similar tools, the answer the exam wants is usually better names and descriptions, not more prompt examples, a router, or a merged tool.

Practice scenario

ScenarioA research system's analysis subagent has analyze_content and analyze_document, both described as "Analyzes input and returns findings." The team expanded both descriptions last week, but logs still show web articles going to analyze_document whenever the user writes "summarize this document." The subagent's system prompt includes: "Whenever a document is mentioned, use the document analysis tool."

Work it through, then open this

The descriptions were the right first fix, and they may now be fine. What’s left is the system prompt’s keyword-sensitive instruction: the word “document” is tied to analyze_document, so a user calling a web article a “document” overrides the descriptions. Reword that instruction in terms of the input source (uploaded files versus web search results), or remove it. Also consider renaming analyze_content to extract_web_results so the name says what it handles. Adding few-shot examples or a keyword router would be working around a prompt that is actively steering the model wrong.

Build exercise — Audit a tool set for misrouting

Intermediate · 30 min

What you’ll learn

Reading tool descriptions the way the selecting model reads them
Fixing overlap with renames, boundary statements, and splits
Finding system prompt wording that competes with tool descriptions

Take a tool set with at least three tools and write five realistic requests. For each request, list every tool whose name and description could plausibly handle it.
- Why: Overlap is invisible when you look at one tool at a time. It only shows up when you compare descriptions against real requests.
- You should see: Either one obvious tool per request, or pairs that both look reasonable for the same request.
For each overlapping pair, rename where the name hides the scope and rewrite both descriptions with purpose, input format, an example query, an edge case, and a “use X instead when…” boundary. If one tool does several unrelated jobs, split it.
- Why: The boundary has to be stated on both sides, and a generic tool can’t be described precisely until it’s split into clear contracts.
- You should see: Every request from step 1 now matching exactly one tool when you reread the descriptions.
Search the system prompt for instructions keyed to words like “document”, “search”, “account”, or “file”, and check whether each one points to the same tool the descriptions do.
- Why: A keyword-sensitive instruction can override even well-written descriptions.
- You should see: A short list of instructions to reword in terms of the task or input source, or confirmation that none conflict.

Exam traps

Leaving tool descriptions minimal and expecting the model to infer the difference between similar tools

Descriptions are the main signal for selection. Minimal ones make selection unreliable as soon as a similar tool exists.

Describing a tool’s implementation instead of its purpose, inputs, outputs, and boundaries

Service names and protocols don’t help the model decide whether the tool fits the current request.

Rewriting one of two overlapping descriptions while the other stays vague

The vague tool still looks like a match. Both sides need a boundary that names the other.

Reaching for few-shot examples, a keyword router, or a merged tool before fixing the descriptions

These are heavier changes that don’t address the root cause. Better descriptions, and renames where needed, are the effective first step.

Keeping one generic tool for jobs that need different input/output contracts

A tool that extracts, summarizes, and verifies can’t be described precisely. Split it into purpose-specific tools.

Ignoring keyword-sensitive system prompt instructions that pull the model toward the wrong tool

If misrouting continues after the descriptions are fixed, check the system prompt for instructions tied to particular words.

Sources

Claude Developer Platform Docs
Anthropic, Claude Certified Architect – Foundations Exam Guide v1.0 (July 2026)