Describing a tool

Claude never sees your function's code. It only sees a description of it, and that description has three parts.

name is what Claude calls it by, like get_weather. Letters, digits, underscores and dashes, up to 128 characters. description is plain English: what the tool does and when to use it. input_schema says what arguments it takes, written in JSON Schema, a standard way to describe the shape of a JSON object.

Read the schema from the top. The input is an object. It has two properties: city, a string, and unit, which can only be "celsius" or "fahrenheit" because it has an enum. Only city is required, so Claude can leave unit out.

Each property gets its own description too. “City name, with country if it's ambiguous” is what stops Claude sending "Paris" when the user meant Paris, Texas.

You send the list of tools with every request, in a tools field next to your messages. That has a cost: the definitions are input tokens, and turning tools on adds a small hidden system prompt that teaches Claude how to call them (286 tokens on Claude Haiku 5.5, as of October 2026). A handful of tools is cheap. Hundreds of them crowd the context, which is one reason to keep your list short.

Your turn. Ask Claude to write the input schema for a tool that looks up a flight's status: a required flight number, and an optional date. Ask for JSON only, so the answer stays short.