Tool Calling· Lesson 2 of 7
Defining a Tool Schema
In one line · A schema is the description that tells the model a tool's name, what it does, and what inputs it takes and of what type.
The model decides whether to use a tool and fills its inputs from this description alone. A precise description means correct use; a vague one makes the model flounder.
Think of it as a job posting for the tool: its name, its job, and the things it needs you to bring. The clearer you write it, the better the model uses it.
Like the labels on a vending machine's buttons: the model reads only the written description to decide which button to press — if the label is wrong, it requests the wrong thing.
A send_email tool has: description 'sends an email to a customer', and parameters: to (string, email), subject (string), body (string) — all required. The model fills them from the user's message.
A schema is written as JSON Schema: a name, a description, and parameters with each input's type, allowed values (enum where relevant), and which fields are required. These definitions are sent with every request inside the context, so the model 'reads' them each time like any prompt — they cost tokens, and a good description is the most important prompt engineering in the whole tool. The model then generates inputs shaped like the schema — but that's no guarantee: your code must validate before executing.
A weather-tool schema — note the specific description and the enum:
{
"name": "get_weather",
"description": "Gets the current weather for a city. Use only when the user asks about weather right now, not forecasts.",
"input_schema": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "City name in English, e.g. Cairo" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["city"]
}
}🧪 Try it yourself: write a full JSON schema for a calculate tool — think: should the operation (add/subtract/multiply/divide) be an enum or free text? Are the numbers required? What should the description say so the model uses it for arithmetic instead of guessing? Then stress-test it: could anyone misread your schema?
Top mistakes: (1) a vague description like 'gets data' — the model won't know when to use it. (2) All fields optional, so the model leaves them empty. (3) No enum for constrained values, so the model invents them. (4) Two tools with near-identical names — the model mixes them up. (5) Relying on the schema alone as validation — the schema guides the model; real validation lives in your code.
Write a detailed schema for any tool the model will see: a description saying when to use it (and when not), strict types, and enums for any constrained value.
Don't put internal implementation details (table names, endpoints) in the schema — they don't help the model, they burn tokens, and they expose your internals for no reason.