Defining Tools: Name, Description, and Input Schema

A tool definition tells the model what a tool does, when to use it, and what parameters it accepts. Three fields make up the definition, and one of them matters far more than the others for tool selection.

The three elements

• name — The technical identifier. This is what appears in tool_use blocks when the model calls the tool. Keep it short, descriptive, and unique.
• description — The natural language explanation of what the tool does, when to use it, and how it differs from similar tools. This is the model’s primary decision signal for choosing between tools.
• input_schema — A JSON Schema object defining the parameters: their types, which are required, and descriptions of each.

Description is the selection mechanism

The model reads the description to decide which tool to use. A minimal description like “Gets customer data” leaves the model guessing when multiple tools could apply. A good description specifies:

• What the tool does
• What input it expects (with examples)
• What it returns
• When to use it versus similar tools

{
  "name": "get_stock_price",
  "description": "Get the current stock price for a given ticker symbol. Input: ticker string (e.g., 'AAPL'). Returns: current price, daily change, volume. Use for real-time price queries. For historical data, use get_price_history instead.",
  "input_schema": { ... }
}

That last sentence — “For historical data, use get_price_history instead” — is surprisingly important. It draws a boundary that prevents misrouting.

input_schema defines input only

The schema uses JSON Schema format to define parameters. Properties listed in the required array are mandatory; everything else is optional by default. You can add description fields to individual properties to help the model understand what each parameter expects.

One thing the schema does not define: the tool’s output format. There is no output schema validation in the Claude API. The schema constrains what goes in, not what comes out.

One-liner: The description field is how the model chooses which tool to call — invest in clear, boundary-drawing descriptions, not just clever names.