Describe tools so selection becomes explicit

Learning objective

Write tool descriptions that define purpose, expected inputs and outputs, examples, edge cases, and when to use alternative tools.

Core idea

As an architect exposing tools to Claude, you design the information from which the model chooses an operation. A description must answer a practical question: does this tool produce the evidence or effect this request needs, from the inputs available? A name such as analyze_document leaves that decision underspecified.

Claude determines when to call a tool from the user’s request and the tool’s description, and Anthropic calls detailed descriptions by far the most important factor in tool performance. The description explains intent and boundaries; the input schema describes the accepted argument structure. Neither can replace the other. A perfectly shaped call to the wrong operation still fails the user’s task.

Write the contract around a specific outcome. Explain what the tool does, what each parameter means, what it returns, and which nearby requests belong elsewhere. See 0.3 for required fields and nullability. Here the focus is making the choice and the meaning of those fields clear before execution.

How it works

Put the contract in the tool definition

For user-defined Messages API client tools, the request’s tools array carries name, description, and input_schema. The API constructs tool-use instructions from tool definitions, configuration, and the supplied system prompt. Descriptions therefore enter the model’s decision context; they are not merely documentation for your developers.

Use name for a recognizable operation and resource. Use description for its purpose, selection conditions, result meaning, and limitations. Use input_schema.properties and each property’s description to explain arguments. For example, document_id should mean the identifier of an ingested document, rather than an arbitrary filename, URL, or pasted body. That distinction belongs beside the parameter, not in an implementation comment Claude never receives.

A description needs enough detail to resolve likely confusion. Anthropic’s engineering guidance suggests describing the tool as you would to a new hire on your team, and spelling out what you might bring implicitly: specialized query formats, definitions of niche terminology, and relationships between underlying resources. The API documentation asks for at least three or four sentences, more for complex tools. That is guidance about coverage, not a guarantee attached to a sentence count; repeating “analyzes documents” four times adds nothing.

Define inputs and outputs together

Consider an illustrative application tool named extract_data_points. The following entry in tools defines its inputs and describes the application-owned result contract:

{
  "name": "extract_data_points",
  "description": "Extract requested fields from an ingested document. Accept only an ingested document identifier in document_id and field names in field_names, not a filename, URL, or pasted text. Return one record per field with its value, supporting passage, and page location. For example, use this tool for: Return the renewal date from the uploaded contract. If a field is absent, return a record marked missing rather than an inferred value. Use summarize_content for a narrative overview or verify_claim_against_source to compare a claim with source evidence.",
  "input_schema": {
    "type": "object",
    "properties": {
      "document_id": {
        "type": "string",
        "description": "Identifier returned by the application after ingestion"
      },
      "field_names": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Names of the fields to extract"
      }
    },
    "required": ["document_id", "field_names"]
  }
}

Explain the output in description as well as implementing it in the tool. An input schema describes accepted arguments; it does not tell the model what evidence the result contains. If an absent field produces an explicit missing-value record, say so. If the tool returns only extracted values and never verifies a claim, say that too. These choices must match the application contract shown in the description.

Prefer parameter names that identify the resource precisely. Anthropic’s engineering guidance contrasts an ambiguous user parameter with user_id. The same principle distinguishes document_id from document, and claim_text from query.

Add examples that resolve ambiguity

Include a short request example in the description: use extract_data_points for “Return the renewal date from the uploaded contract.” Pair it with a contrasting request: use summarize_content for “Explain the contract’s main obligations.” The contrast teaches the decision the model must make, rather than only demonstrating valid syntax.

For complex input objects, the API also supports input_examples. These are argument objects, not complete conversations or natural-language requests. Each example must satisfy input_schema; an invalid example returns HTTP 400. Show a representative nested structure or format-sensitive value when the schema alone leaves realistic usage unclear.

The distinction matters when reviewing examples. A sentence in description explains when to select the tool. An object in input_examples explains how to supply its arguments. Keep both aligned with the operation implemented by your application. A schema-valid example that uses an unsupported identifier convention can still teach the wrong behavior.

input_examples is supported for user-defined client tools and Anthropic-schema client tools except the computer-use and browser-use client toolsets. It is not supported for server tools such as web search or code execution. Do not transfer that field to every tool integration because it appears in a custom-tool example.

Explain the edges and the alternative

An edge case should change the caller’s decision or interpretation. For the illustrative extraction tool, explain how it handles a missing field, conflicting values, or an unsupported document identifier. Avoid promising that the model can repair these conditions by guessing a value.

Name the alternative operation explicitly. “Does not summarize” is less helpful than “Use summarize_content for a narrative overview; this tool returns requested fields with source passages.” Likewise, explain that verify_claim_against_source compares a supplied claim with evidence rather than extracting every value in a document.

Keep tool responses focused on information needed for the next decision. Anthropic recommends high-signal fields and stable, meaningful identifiers rather than bloated results. If source attribution is necessary, include it in the actual response contract; a description that promises page locations cannot compensate for an implementation that omits them.

Key distinctions and trade-offs

Each element of the contract closes a specific gap in the selection decision:

Purpose versus format: description helps determine whether an operation is appropriate. input_schema defines the argument structure. Clear format constraints do not establish semantic suitability.

Limit versus failure contract: “Only ingested document identifiers are accepted” describes a boundary. “Unknown identifiers produce this result” describes what happens at that boundary. State both when they affect subsequent work.

Architecture / decision scenario

A structured-data extraction assistant receives uploaded contracts. It has the illustrative tools extract_data_points, summarize_content, and verify_claim_against_source. A user asks for the renewal date, a summary of obligations, and whether the contract permits cancellation without notice.

The architect gives extract_data_points an input contract using document_id and field_names. Its description promises field values with source locations, explains the application’s missing-field result, and includes the renewal-date example. The summary tool promises a narrative overview. The verification tool accepts claim_text and returns a comparison supported by passages. Each description names the other operations where their responsibilities divide.

The assistant can select all three operations for the compound request without treating a summary as proof of a claim. If the renewal date is absent, the defined missing-field result preserves that absence. If the user supplies a filename instead of an ingested identifier, the assistant must resolve the identifier according to the contract rather than invent one.

For a nested extraction request, the architect adds valid input_examples to the custom client tool definition. They inspect representative tool_use blocks and returned evidence to confirm that examples improve argument formation without blurring the three purposes. See 1.1.2 for the call-and-result history mechanics.

Common exam traps

• Using a one-line description that repeats the name without specifying the outcome.
• Treating the input schema as documentation of returned evidence.
• Supplying natural-language requests where input_examples expects argument objects.
• Explaining the happy path but leaving missing values and unsupported inputs ambiguous.
• Saying “use another tool” without naming the relevant alternative and selection condition.
• Assuming a descriptive promise validates or enforces the application’s output contract.

What to remember

A useful description defines purpose, inputs, outputs, examples, edge cases, and alternatives. Put argument structure in input_schema, meaning in descriptions, and representative valid objects in input_examples where supported. Make the documented contract match the implemented result.

Knowledge check

References

• Anthropic, Define tools
• Anthropic, Tool use with Claude
• Anthropic, Writing effective tools for agents
• JSON Schema, Array