Tool Descriptions: How Claude Chooses Which Tool to Call

1.What Claude actually sees when it picks a tool

Anthropic calls tool use a contract. You declare which operations exist and what their inputs and outputs look like. Claude decides when and how to call them. What makes this different from an ordinary API is who is calling: a language model choosing a function based on the conversation, not a developer who has read your code. Claude never sees how the tool is implemented, only the schema you wrote and the results you send back.

So what decides the choice? The overview docs answer directly: Claude decides when to call a tool from the user's request and the tool's description. With the default tool_choice of auto, Claude calls a tool when the request matches that tool's described capability and the answer isn't already in context. Everything Claude knows about a tool's capability comes from the text you wrote.

That text also has a physical location. When you send the tools parameter, the API builds a special system prompt from your tool definitions, your tool configuration and your own system prompt. Your descriptions sit in the same prompt as your instructions, which is why the two can interfere with each other, as the rest of this section shows.

Because descriptions and instructions share one prompt, system prompt wording affects tool selection as well. The overview docs say the boundary between calling a tool and answering directly is steerable through your system prompt, and small changes of phrasing move it. "Use the tools to investigate before responding." increases tool use. "Always call a tool first before responding." pushes further. "Use your judgment about whether to call a tool or respond directly." keeps triggering behaviour conservative. The tool choice cookbook adds that with tool_choice set to auto, Claude can be over-eager to call tools, and that a detailed prompt helps Claude determine when to call a tool and when not to. Its example ran with a deliberately weak prompt and two tools, a sentiment tool and a calculator. When a tweet said "I had four and just adopted 2 more! Guess how many I have now?", Claude reached for the calculator instead of analysing sentiment. The words in the input pulled it toward the wrong tool.

The same risk applies to keyword-sensitive instructions in your own system prompt. The docs don't name this failure, but it follows from what they do say. If a line ties a word or phrase to a tool ("whenever the user mentions X, use tool Y"), that instruction sits in the same prompt as the descriptions and steers the choice, so it can create unintended tool associations that override a well-written description. When a tool keeps being called for the wrong requests and its description is already sharp, review the system prompt. Look for instructions that bind keywords to tools, and rephrase them in terms of when each tool should and shouldn't be used.

Sources1234

2.What a strong description contains

The Define tools guide says to provide extremely detailed descriptions and calls this 'by far the most important factor in tool performance.' It lists what to cover: what the tool does, when it should be used and when it shouldn't, what each parameter means and how it changes the tool's behaviour, and any caveats or limits, including what information the tool does not return. It also gives a minimum length: at least 3–4 sentences per description, more if the tool is complex.

Anthropic's agent-building guidance says much the same from the designer's side. A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools. A useful test is to put yourself in the model's place. If you would have to think hard about how to use the tool from its description alone, so will the model. Write it the way you would write a great docstring for a junior developer on your team.

The docs show the difference with two versions of the same stock-price tool. Here is the good one:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

The poor version keeps the same name and schema but has the description "Gets the stock price for a ticker." and no description on the ticker parameter. The docs' verdict is that it is too brief and leaves Claude with many open questions about how the tool behaves and when to use it. The table below sets out what was lost.

Sources35

3.Examples and arguments that are hard to get wrong

Some tools have inputs that are hard to describe in words alone: nested objects, optional parameters, or values that must follow a set format. For these, the definition can carry an optional input_examples field. This is an array of example input objects that appear in the prompt next to the schema. They show Claude when to include optional parameters, which formats to use, and how to structure complex inputs. Three rules apply. Every example must be valid against the tool's input_schema, and invalid examples return a 400 error. The field works on user-defined and Anthropic-schema client tools, but not on server tools. And examples cost prompt tokens: roughly 20–50 for a simple example and 100–200 for a complex nested one. The guidance still puts descriptions first and treats examples as an extra for complex tools.

" ? ": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],

Sometimes the fix belongs in the arguments rather than the wording. Anthropic's term for this is 'poka-yoke': change the arguments so mistakes are harder to make. While building its SWE-bench agent, Anthropic saw the model mishandle relative file paths after it had moved out of the root directory. The team changed the tool to always require absolute paths, and the model then used it flawlessly.

To find out which fix is needed, measure. Many tool errors for invalid parameters suggest the tool needs a clearer description or better examples. When Anthropic launched Claude's web search tool, it found Claude needlessly adding 2025 to search queries, which biased the results. The fix was a better tool description.

Sources356

4.Telling similar tools apart

The tool description is the primary mechanism Claude uses for tool selection. The overview says Claude decides when to call a tool from the user's request and the tool's description, and the Define tools guide calls detailed descriptions 'by far the most important factor in tool performance.' This matters most when tools resemble each other. Anthropic's advanced tool use post reports that the most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names like notification-send-user vs. notification-send-channel. The writing-tools post adds that when tools overlap in function or have a vague purpose, agents can get confused about which ones to use. Minimal descriptions give Claude nothing to separate two near-identical tools, so selection among similar tools becomes unreliable.

The troubleshooting guide names both the symptom and the fix. If Claude calls tool A when you wanted tool B, the likely cause is description ambiguity. The fix is to sharpen descriptions and differentiate tools by WHEN to use them, not only WHAT they do.

In practice, each tool in a group of similar tools needs a description that answers four things for that tool alone:

- its purpose: what it does - its expected inputs: what each parameter means and what format it takes - its outputs: what it returns, and what it does not return - when to use it versus similar alternatives, and when not to

This is the Define tools checklist applied with the neighbouring tool in view. Anthropic's agent-building guidance calls the last part 'clear boundaries from other tools' and says clear parameter names and descriptions are especially important when using many similar tools. Names help as well. Namespacing by service and by resource (for example asana_search, jira_search, asana_projects_search) helps agents pick the right tool at the right time.

Sources73865

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.If the tool name is self-explanatory, a one-line description is enough.Why is that wrong?

   The guidance sets a minimum of 3–4 sentences per description and wants usage boundaries, parameter meanings and limits spelled out. A clear name does not replace any of that.

   Covered in What a strong description contains

2. 2.When Claude picks the wrong one of two similar tools, the fix is to describe more precisely what each tool does.Why is that wrong?

   The troubleshooting guide says to differentiate similar tools by when to use them, not only by what they do. Two precise descriptions of what each tool does can still leave the choice between them ambiguous.

   Covered in Telling similar tools apart