Defining Claude Tools: Schemas, Descriptions, and Tool Set Design

1.Where a tool runs decides what you build

Tool use (also called function calling) lets Claude call functions that you define or that Anthropic provides. Before writing any schema, decide where the tool's code will run. The docs treat this as the main way tools differ, and it fixes what your application is responsible for. There are three buckets. User-defined client tools carry most tool-use traffic: you write the schema, run the code, and return the result. Anthropic-schema client tools (memory, bash, text_editor, computer, browser) work the same way, except Anthropic publishes the schema. Server-executed tools (web_search, web_fetch, code_execution, tool_search) run on Anthropic's infrastructure, so you never build a tool_result for them.

Why use Anthropic's bash schema when you could write your own shell tool? Claude has been optimized on many successful trajectories that use those exact signatures. As a result it calls them more reliably and recovers from errors better than it would with a custom equivalent.

The three buckets collapse into a two-way split: client-side vs. server-side tools. Client-side tools (user-defined and Anthropic-schema) run in your application. Claude answers with stop_reason: "tool_use" and one or more tool_use blocks, your code runs each call, and you send back a tool_result block. Because the model can't run your code, every call is a round trip, and your application drives a while loop that continues as long as stop_reason is tool_use. If a client tool fails, you report it with is_error: true. Server-side tools run on Anthropic's infrastructure inside their own loop. The response contains server_tool_use blocks showing what ran and what came back, you never construct a tool_result, and you don't handle is_error for them. Two cases need your attention. If the server loop hits its iteration limit, the response has stop_reason: "pause_turn", and you re-send the conversation, including the paused response and the same tools, to let Claude continue. If Claude calls a server tool and a client tool in the same group of parallel calls, the API does not run the server tool yet: the response has stop_reason: "tool_use" and a server_tool_use block with no result block. You return the client tool_result blocks, keep the same tools array, and the API then runs the deferred server tool.

Sources12

2.Anatomy of a tool definition

You declare client tools in the top-level tools parameter of the request. A user-defined tool has a name, which must match ^[a-zA-Z0-9_-]{1,128}$. It also has a plaintext description and an input_schema, which is a JSON Schema object for the parameters. Behind the scenes, the API turns these definitions into a special system prompt, so everything you write in them becomes context for Claude.

{
  "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"]
  }
}

Two optional fields make tool calls more dependable. input_examples is an array of sample inputs, which helps most with nested objects and format-sensitive parameters. Every example has to validate against input_schema, otherwise the request returns a 400. Examples also cost prompt tokens, and they don't work on server tools or on the computer use and browser use toolsets. strict: true turns on grammar-constrained sampling. That guarantees the inputs match your schema, so you get passengers: 2 and never the string "two".

Sources34

3.Writing descriptions that drive tool selection

Claude decides whether to call a tool based on the user's request and the tool's description. A good description says four things: what the tool does, when to use it and when not to, what each parameter means, and its limits, such as what it doesn't return. Anthropic recommends at least 3–4 sentences per tool, and more for complex ones. Compare this description with the weak alternative, "Gets the stock price for a ticker."

{
  "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"]
  }
}

Sources35

4.Building a tool set that scales

Good individual tools can still add up to a confusing set. Anthropic gives three construction rules. Consolidate: one tool with an action parameter beats separate create_pr, review_pr, and merge_pr tools, because fewer tools leave less room for picking the wrong one. Namespace: when tools span services, prefix names with the service, as in github_list_prs and slack_send_message. This matters most when you use tool search. Return high-signal results: send back stable, meaningful identifiers such as slugs or UUIDs, and only the fields Claude needs for its next step. Bloated responses waste context.

Also check that a task needs a tool in the first place. Tools fit side effects, fresh or external data, outputs that must have a fixed shape, and calls into existing systems. They don't fit summarization, one-shot Q&A, or trivial work where the extra round trip would dominate. Anthropic's rule of thumb: if you're writing a regex to extract a decision from model output, that decision should have been a tool call.

Sources31

5.Configuring requests for external systems: tool_choice and server tools

The request also controls *whether* Claude calls tools. With the default tool_choice of auto, Claude decides on each turn. You can push it with the system prompt: "Use the tools to investigate before responding." increases tool use. To require a call rather than rely on prompting, set tool_choice. Adding disable_parallel_tool_use: true limits Claude to at most one tool call per turn.

Forcing a tool has costs. With any or tool, the API prefills the assistant turn, so Claude writes no explanation before its tool_use blocks. Forced tool use also isn't supported everywhere. Manual extended thinking rejects any and tool. On Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1, any and tool return a 400 error. On those models, use auto with strict tool use, or use structured outputs. Server tools need very little setup: you enable them with a date-versioned type. For remote MCP servers, the MCP connector connects from the Messages API without a separate MCP client.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Sources35

Exam traps

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

1. 1.Server-side tools need the same handling as client-side tools: build a tool_result and set is_error on failures.Why is that wrong?

   Only client tools need your tool_result and is_error handling. Server tools run in Anthropic's own loop and show up as server_tool_use blocks. The exceptions to watch for are pause_turn and a turn that mixes server and client tools.

   Covered in Where a tool runs decides what you build

2. 2.If Claude picks the wrong tool or calls it out of scope, turn on strict mode or add parameters.Why is that wrong?

   Strict mode only guarantees the shape of the input. Which tool Claude picks, and when, depends on the description, so rewrite it to state scope, when not to use the tool, and what it returns.

   Covered in Writing descriptions that drive tool selection

3. 3.tool_choice: tool is always the way to force a specific tool call.Why is that wrong?

   Some models reject it with a 400, including Opus 5.5, Sonnet 5.5, Fable 5.1, and Mythos 5.1, and so does manual extended thinking. On those, use auto with strict tool use or structured outputs.

   Covered in Configuring requests for external systems: tool_choice and server tools