CertSafari
    Anthropic Claude Certified Architect – Foundations (CCAR-F)· Lessons

    Domain 2 · Lesson 8/30

    Tool descriptions: how Claude picks a tool, and how to stop it picking the wrong one

    Design effective tool interfaces with clear descriptions and boundaries

    20 min read
    3.6% of exam
    9 sources
    Published 20 Oct 2026
    Docs as of 14 Oct 2026

    What you will be able to do

    • Explain why the tool description, more than any other signal, decides which tool Claude calls
    • Write a tool description that covers purpose, inputs, examples, edge cases and boundaries against similar tools
    • Diagnose misrouting between overlapping tools and fix it by renaming and rescoping descriptions
    • Split a generic tool into purpose-specific tools with clear input and output contracts
    • Audit a system prompt for keyword-triggered instructions that pull calls away from a tool's described scope

    Key concept

    Description-driven tool selection — Claude picks a tool by matching the request against each tool's name and description, and the API puts nothing else about the tool in front of the model. When two descriptions say the same thing, Claude has nothing to tell the tools apart, and calls land on the wrong one.

    1.The description is what Claude chooses from

    A tool definition is the whole interface between your code and the model's decision to call it. Each user-defined tool in the tools parameter has a name, a description, an input_schema and, optionally, input_examples. With the default tool_choice of auto, Claude decides on every turn whether to call a tool. It calls one when the request maps to that tool's described capability and the answer isn't already in context.

    What Claude sees for each user-defined tool
    FieldWhat it carries
    nameThe tool's identifier; must match ^[a-zA-Z0-9_-]{1,128}$
    descriptionWhat the tool does, when it should be used, and how it behaves
    input_schemaA JSON Schema object defining the expected parameters
    input_examplesOptional example input objects, each valid against the schema

    Several things that look like they might help are never shown to the model at all. Your backend routing weights, the internal function a tool maps to, and an ID a user might type have no effect on which tool Claude calls. When two tools share a description, the only remaining difference is two near-synonymous names, and process_data against process_information says nothing about which job belongs where. The fix goes in the tool definitions, not in the user's phrasing or the order of the array.

    A description that is too short fails in the same way, just less visibly. The documentation's poor example, "Gets the stock price for a ticker.", is too brief and leaves Claude with many open questions about the tool's behavior and usage. Which exchanges? What currency? Should it also answer a question about the company's earnings? Claude fills each of those gaps with a guess.

    Because the description is the primary selection signal, a minimal one makes selection unreliable exactly when it matters most: among similar tools. A lone stock-price tool with a one-line description has no rival to be confused with. Add a second tool that also touches prices, and that one line is all Claude has to decide between them. Anthropic's own example of a pair where extra context is needed is create_ticket against create_incident. The same holds for tool search, which matches against names and descriptions, so a vague pair is harder to discover as well as harder to choose between. The remedy is more context in the description itself: what the tool does, when it applies, and what it leaves alone.

    Checkpoint 1 of 8· Check yourself

    Your agent has two user-defined tools, and Claude keeps calling the wrong one. You can make only one change. Which change can actually affect which tool Claude chooses?

    Checkpoint 2 of 8· Exam question

    A team names two tools process_data and process_information, and both share the description "Processes data provided by the user." The model routes roughly half of matching tasks to the wrong tool. What is the most likely root cause?

    Sources123

    2.What a selection-ready description contains

    Anthropic ranks detailed descriptions as by far the most important factor in tool performance, ahead of every other lever. A description should explain what the tool does, when it should be used and when it should not, what each parameter means, and any caveats, including what information the tool does not return. Aim for at least 3–4 sentences, and more for a complex tool.

    A description that states scope, input format, output, when to use it, and what it will not dojson
    {
      "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"]
      }
    }
    Each part of the get_stock_price description closes a specific gap
    ElementIn the exampleMistake it prevents
    Input format and constraintsValid symbol on NYSE or NASDAQ; e.g. AAPL for Apple Inc.Passing a company name or an unsupported market
    OutputLatest trade price in USDClaude guessing the currency or what kind of price comes back
    When to use itCurrent or most recent price of a specific stockCalling it for questions it was never built for
    BoundaryWill not provide any other information about the stock or companyExpecting it to answer earnings or company questions

    Edge cases and examples belong in the description as well. Anthropic's agent-building guidance puts it this way: a good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools. It suggests writing the description the way you would write a docstring for a junior developer, which matters most when many tools look alike. The input format is often what decides whether a call works. A location parameter described as "The city and state, e.g. San Francisco, CA" shows Claude how to pass a multi-word place name. A bare string type does not.

    For complex, nested or format-sensitive inputs, input_examples can add concrete calls that are validated against the schema, and an invalid example returns a 400 error. Examples supplement the description and do not replace it. They also help when two tools are similar, because an example can show which one fits a given request. A small wording change can still have a big effect. Anthropic found Claude needlessly appending the current year to web search queries, and fixed it by improving the tool description.

    Differentiation between sibling tools comes from four statements made side by side: purpose, inputs, outputs, and when to pick this tool over its neighbour. Take two tools that both touch web pages. One description reads: "Extracts the title, price and availability from a product page. Takes a single URL and returns those three fields as JSON. Use it when the user supplies a link to a product page; for summarizing an article, use summarize_article instead." The other mirrors it: it takes pasted article text, returns a short summary, and says it should not be used for product pages. Neither description needs to be long, but each names its input, its output and the case it hands to the other tool. The decisive part is the last one, because the troubleshooting guidance for Claude calling tool A when you wanted tool B is to differentiate tools by WHEN to use them, not only WHAT they do. Documenting the return format in the description, such as the fields and their types, makes the contrast between siblings concrete.

    Checkpoint 3 of 8· Fill the gap

    The poor version of this tool declared ticker as just {"type": "string"}, with no other keys. In the complete definition below, which key in the parameter gives Claude the input format it needs?

    {
      "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",
            " ? ": "The stock ticker symbol, e.g. AAPL for Apple Inc."
          }
        },
        "required": ["ticker"]
      }
    }

    Checkpoint 4 of 8· Check yourself

    A teammate wants to cut a nested-input tool's description down to one line and add three schema-valid input_examples instead, since "examples show Claude more than prose does." What is wrong with this plan?

    Sources24356

    3.Overlapping tools: rename and rescope

    Overlap is the most common source of misrouting. Anthropic names wrong tool selection as one of the two most common failures, especially when tools have similar names such as notification-send-user and notification-send-channel. The troubleshooting guidance for "Claude calls tool A when you wanted tool B" is to sharpen descriptions and to tell tools apart by when to use them, not only by what they do.

    Overlap often creeps in when a tool gains a successor. Say analyze_content was built to summarize any pasted content, including emails and internal notes. Later a web-specific tool arrives, but nobody edits the old description, so it still claims every kind of content. Claude reads two descriptions that both cover web material, and some web tasks go to the general tool. Fixing this takes two edits to the old tool. Give it a name that matches the scope it has left. Then rewrite its description so it explicitly excludes the case the new tool now owns.

    Copied descriptions are the other common way overlap starts, and there the older tool is narrowed the other way round. Suppose a different pipeline has analyze_content and analyze_document, written with near-verbatim descriptions, although in practice analyze_content is the tool that receives web search results and analyze_document receives uploaded files. Rename analyze_content to extract_web_results and give it a web-specific description: it takes web search results, returns the extracted fields, and is not for uploaded files. Let analyze_document describe uploaded documents. The overlap disappears at the source because each name and description now states a scope the other does not, so a request about an uploaded PDF no longer matches the web tool. Deleting one tool, or making users paste documents as plain text, removes a capability without fixing the description problem. Giving the tools different internal function names changes nothing Claude can see.

    Names and descriptions that make the boundary visible
    Weak definitionStronger definition
    query_db_orders: "Execute order query"search_customer_orders: "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
    Unprefixed names across servicesService-prefixed names such as github_list_prs, slack_send_message

    Names do some of this work. When tools span several services, prefixing each name with the service keeps selection unambiguous as the library grows. A prefix complements the description and cannot replace it. Two tools with clear names and identical descriptions still overlap.

    Checkpoint 5 of 8· Check yourself

    After a web-extraction tool was added, analyze_content kept its old description: "Summarizes any content: emails, notes, web pages." Both tools now have detailed descriptions of what they do, but some web tasks still go to analyze_content. Which fix targets the actual cause?

    Checkpoint 6 of 8· Exam question

    A tool named analyze_content, originally built for summarizing pasted text, has its description copied almost verbatim onto a newer tool, analyze_document, meant for uploaded PDFs. Following the pattern of renaming a tool to eliminate overlap, what should the team do?

    Sources632

    4.Splitting a generic tool into purpose-specific contracts

    A generic tool overlaps with itself. A single analyze_document that extracts, summarizes or fact-checks, depending on how Claude reads the request, has one description trying to cover three jobs. Each of those jobs takes different inputs and returns different outputs. The fix is to split it into extract_data_points, summarize_content and verify_claim_against_source. Each one gets a defined input/output contract. The verifier takes a claim and a source, for example, while the summarizer takes only content. Each description can then say what the tool returns and when to choose it over its two siblings.

    The two rules apply to different shapes of tool, so they do not conflict. Consolidation is for one resource with several actions. Rather than defining create_pr, review_pr and merge_pr separately, you group them into one tool with an action parameter, because fewer, more capable tools reduce selection ambiguity. Splitting is for one name that hides several distinct purposes. Ask whether the operations share a contract. Actions on the same pull request do, so they belong behind one tool with an action parameter. Extraction, summarization and claim verification produce different outputs that Claude uses differently, so each gets its own tool and description.

    The contract should be written down, outputs included. Anthropic's example get_orders description lists what comes back: an id, a total in USD, a status of 'pending', 'shipped' or 'delivered', the items, and an ISO 8601 created_at. Spelling out the output makes the boundary between sibling tools concrete. The agent-building guidance gives one more test. Ask how you could change parameter names or descriptions to make the tool's use obvious, and change the arguments so mistakes are harder to make.

    Checkpoint 7 of 8· Check yourself

    You propose splitting a generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source. A reviewer objects: "Anthropic says to consolidate related operations into fewer tools, so splitting makes selection worse." What is the best response?

    Sources274

    5.System prompt wording can override a good description

    Tool descriptions and your system prompt are not separate channels. When you call the API with tools, it builds one prompt that contains the tool definitions, the tool configuration and your own system prompt, and Claude reads them together.

    The prompt the API constructs: your system prompt sits directly beside the tool definitionstext
    In this environment you have access to a set of tools you can use to answer the user's question.
    {{ FORMATTING INSTRUCTIONS }}
    String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
    Here are the functions available in JSONSchema format:
    {{ TOOL DEFINITIONS IN JSON SCHEMA }}
    {{ USER SYSTEM PROMPT }}
    {{ TOOL CONFIGURATION }}

    System prompt wording measurably steers tool use. "Use the tools to investigate before responding." increases tool calls, "Always call a tool first before responding." pushes further, and "Use your judgment about whether to call a tool or respond directly." keeps triggering conservative. Since one sentence in the system prompt can shift how often Claude calls tools, one sentence can just as easily shift which tool it calls.

    Instructions keyed to particular words are where this goes wrong. Suppose a system prompt says "Whenever the user mentions a document, analyze it." That ties the word "document" to whichever tool has "analyze" or "document" in its name. A request to verify one claim in a PDF might then go to a general analysis tool, even though verify_claim_against_source describes that exact job. The careful description is still there. A trigger word elsewhere in the same prompt is drawing the call away from it. When routing stays wrong after the descriptions have been fixed, read the system prompt for phrases like this. Then either remove the keyword link or rewrite it to point at the tool whose description actually fits.

    Emphatic wording creates unintended associations too. Claude's recent models respond more strongly to the system prompt than earlier ones, so a line written to stop a tool undertriggering, such as "CRITICAL: You MUST use this tool when...", can now make it fire on requests that belong to a neighbouring tool. Anthropic's fix is to dial back aggressive language: a plain "Use this tool when..." is enough. Blanket defaults like "If in doubt, use [tool]" cause overtriggering for the same reason, and the better instruction is targeted, naming the situation in which the tool helps. Audit a prompt for three patterns: a trigger word that matches a tool's name, an emphatic MUST aimed at one tool, and a default-to-this-tool rule. Each one competes with the descriptions.

    Checkpoint 8 of 8· Fill the gap

    Debugging a misroute that remains after the tool descriptions were rewritten, you look at the prompt the API builds around your tools. Which placeholder sits right after the tool definitions and explains why instructions outside the tool definitions can still affect which tool Claude calls?

    In this environment you have access to a set of tools you can use to answer the user's question.
    {{ FORMATTING INSTRUCTIONS }}
    String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
    Here are the functions available in JSONSchema format:
    {{ TOOL DEFINITIONS IN JSON SCHEMA }}
     ? 
    {{ TOOL CONFIGURATION }}

    Sources2189

    Sources

    (9)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “It calls a tool when the request maps to that tool's described capability and the answer isn't already in context.”
      ↩︎ The description is what Claude chooses from
      “This boundary is steerable through your system prompt.”
      ↩︎ System prompt wording can override a good description
      “Claude determines when to call a tool based on the user's request and the tool's description.”
      ↩︎ Key concept
      “Claude determines when to call a tool based on the user's request and the tool's description.”
      ↩︎ Exam trap 1
      “Claude determines when to call a tool based on the user's request and the tool's description.”
      ↩︎ Prediction
    2. 2.
      “The poor description is too brief and leaves Claude with many open questions about the tool's behavior and usage.”
      ↩︎ The description is what Claude chooses from
      “The more context you can give Claude about your tools, the better it will be at determining when and how to use them.”
      ↩︎ The description is what Claude chooses from
      “Provide extremely detailed descriptions. This is by far the most important factor in tool performance.”
      ↩︎ What a selection-ready description contains
      “Aim for at least 3–4 sentences for each tool description, more if the tool is complex.”
      ↩︎ What a selection-ready description contains
      “This makes tool selection unambiguous as your library grows, and is especially important when using tool search.”
      ↩︎ Overlapping tools: rename and rescope
      “Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”
      ↩︎ Splitting a generic tool into purpose-specific contracts
      “the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt.”
      ↩︎ System prompt wording can override a good description
      “Prioritize descriptions, but consider using input_examples for complex tools.”
      ↩︎ Exam trap 2
      “the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt.”
      ↩︎ Exam trap 4
      “Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the input_examples field”
      ↩︎ Checkpoint
    3. 3.
      “Tool search matches against names and descriptions, so clear, descriptive definitions improve discovery accuracy.”
      ↩︎ The description is what Claude chooses from
      “Similar tools where examples clarify which one to use (e.g., create_ticket vs create_incident)”
      ↩︎ What a selection-ready description contains
      “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.”
      ↩︎ Overlapping tools: rename and rescope
    4. 4.
      “A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools.”
      ↩︎ What a selection-ready description contains
      “How can you change parameter names or descriptions to make things more obvious?”
      ↩︎ Splitting a generic tool into purpose-specific contracts
    5. 5.
      “we steered Claude in the right direction by improving the tool description”
      ↩︎ What a selection-ready description contains
    6. 6.
      “Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
      ↩︎ What a selection-ready description contains
      “Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
      ↩︎ Overlapping tools: rename and rescope
      “Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
      ↩︎ Exam trap 3
    7. 7.
      “Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.”
      ↩︎ Splitting a generic tool into purpose-specific contracts
    8. 8.
      “Writing a detailed prompt helps Claude determine when to call a tool and when not to.”
      ↩︎ System prompt wording can override a good description

    Spotted a mistake, or was something unclear? Tell us.