Defining Tools with JSON Schema

20 min read Lesson 13 / 28

Tools are the bridge between Claude's language reasoning and the real world. You describe what a tool does and what parameters it accepts; Claude decides when and how to call it.

Tool Definition Structure

Each tool needs three things: a name, a description, and an input schema.

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city. Returns temperature in Celsius and conditions.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "The city name, e.g. 'London' or 'New York'",
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature units. Default: celsius",
                },
            },
            "required": ["city"],
        },
    },
    {
        "name": "search_web",
        "description": "Search the web for current information. Use when you need facts not in your training data.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query",
                },
                "num_results": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "description": "Number of results to return. Default: 3",
                },
            },
            "required": ["query"],
        },
    },
]

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Tokyo right now?"}],
)

print(response.stop_reason)  # tool_use
print(response.content)

JavaScript Tool Definition

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools = [
  {
    name: "query_database",
    description:
      "Run a read-only SQL query against the analytics database. Only SELECT statements allowed.",
    input_schema: {
      type: "object",
      properties: {
        sql: {
          type: "string",
          description:
            "The SQL SELECT query to execute. Must not contain INSERT, UPDATE, DELETE, or DROP.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 1000,
          description: "Maximum rows to return. Default: 100",
        },
      },
      required: ["sql"],
    },
  },
];

Writing Good Tool Descriptions

The description is what Claude reads to decide whether to use the tool. Be specific:

# Weak description — Claude may not call this at the right time
{"name": "get_data", "description": "Gets data"}

# Strong description — Claude knows exactly when to use it
{
    "name": "get_stock_price",
    "description": (
        "Get the real-time stock price for a publicly traded company. "
        "Use this when the user asks about current stock prices, market cap, "
        "or 'how is [company] doing today'. Do NOT use for historical prices."
    ),
}

Clear tool descriptions reduce unnecessary tool calls and improve agent reliability.