Claude Tool Definitions: Schemas, Descriptions and Tool Set Design

1.Tool use as a contract with external systems

A tool is a typed interface between Claude and your application. You say which operations exist and what their inputs look like, and Claude chooses when to call them. The model never runs anything itself. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result comes back into the conversation. Claude never sees your implementation. It sees only the schema you wrote and the result you returned. So the definition is the entire interface Claude has to your system.

You configure tools to let Claude reach systems outside the model. The documentation lists four cases where tools fit:

- Actions with side effects, such as sending an email, writing a file or updating a record. - Fresh or external data, such as current prices, today's weather or the contents of a database. - Structured, guaranteed-shape outputs, where a schema has to enforce the fields. - Calls into existing systems, such as databases, internal APIs and filesystems.

One practical sign: if you are writing a regex to pull a decision out of model output, that decision should have been a tool call.

Tools are the wrong choice in three cases:

- The model can answer from training alone (summarization, translation, general knowledge). - A one-shot Q&A has no side effects and nothing to execute. - The extra round trip a tool call costs would take longer than the trivial task itself.

Sources1

2.Anatomy of a tool definition

You declare client tools in the tools top-level parameter of the API request. A user-defined tool has three required fields and one optional field:

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

location is required. unit is optional, but the enum limits it to "celsius" or "fahrenheit", so the schema itself restricts what Claude can send. Further optional properties, including cache_control, strict, defer_loading and allowed_callers, are documented in the Tool reference. Anthropic-schema client tools such as bash and the text editor are declared differently: you give a date-versioned type instead of writing your own schema.

Claude does not receive these definitions raw. The API builds a special system prompt from your tool definitions, the tool configuration and your own system prompt. The description you write is therefore prompt text that Claude reads when it decides what to do.

Sources2

3.Writing descriptions that steer tool selection

The documentation is direct about this: detailed descriptions matter more to tool performance than anything else. A good description covers four things:

- what the tool does - when to use it, and when not to - what each parameter means and how it changes the tool's behaviour - caveats and limits, such as information the tool does not return

The guideline is at least 3–4 sentences per tool, and more for complex tools. The documentation gives this example of a poor one:

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

The documented good version keeps the same schema and only rewrites the text:

- The ticker must be a valid symbol for a company on a major US exchange such as NYSE or NASDAQ. - The tool returns the latest trade price in USD. - It should be used when the user asks for the current or most recent price of a stock. - It provides no other information about the stock or company.

The ticker parameter also gets its own description ("e.g. AAPL for Apple Inc."). Scope, output and exclusions are all spelled out, so Claude can tell when a request falls outside the tool.

input_examples is a secondary option. Descriptions come first. Examples help with complex inputs, nested objects, optional parameters and format-sensitive values. Each example must validate against the tool's input_schema. The examples go into the prompt next to the schema and show Claude when to include optional parameters and how to format them.

Sources2

4.Constructing the tool set

Good individual descriptions are only part of the job. The design of the whole tool set also affects how well Claude uses it. The same guidance gives three rules for building the set.

Consolidate related operations. Don't make create_pr, review_pr and merge_pr separate tools. Expose one tool with an action parameter. Fewer, more capable tools reduce selection ambiguity.

Namespace by service. When tools span several services or resources, prefix each name with the service, for example github_list_prs or slack_send_message. This keeps selection unambiguous as the library grows, and it matters most when you use tool search.

Return only high-signal information. Tool results also use context. Return semantic, stable identifiers such as slugs or UUIDs, not opaque internal references. Include only the fields Claude needs for its next step. Bloated responses waste context and make the important parts harder to find.

Sources2

Exam traps

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

1. 1.When Claude picks the wrong tool, the first fix is to add input_examples.Why is that wrong?

   Wrong tool selection is a description problem. Descriptions are the most important factor. input_examples help mainly with complex, nested or format-sensitive inputs.

   Covered in Writing descriptions that steer tool selection

2. 2.Giving each action its own narrowly named tool makes selection clearer for Claude.Why is that wrong?

   The guidance says the opposite. Group related operations into one tool with an action parameter, because fewer tools reduce selection ambiguity.

   Covered in Constructing the tool set