Tool Definition — Describing a Tool So It Gets Used Well
Tripmate has a tool called lookup with the description "Looks things up." It gets called for weather, for trains, for Asha's calendar — and fails at most of them. The code behind it is fine. The model simply cannot tell what the tool is for, because the definition is the only thing it sees.
The rule
The model sees only the definition — write it like documentation for a stranger.
A tool definition has three parts, and the model relies on each:
- Name — short, specific, verb-first:
search_trains, notlookuportool2. - Description — what it does, when to use it, when not to, and what comes back.
- Input schema — the arguments, their types, which are required, and allowed values. Most providers use JSON Schema for this.
{
"name": "search_trains",
"description": "Search scheduled trains between two stations on one date. Use this to find options before booking. Returns up to 10 trains with departure, arrival, class and fare. Does not book anything.",
"input_schema": {
"type": "object",
"properties": {
"from": { "type": "string", "description": "Origin station code, e.g. PUNE" },
"to": { "type": "string", "description": "Destination station code, e.g. JP" },
"date": { "type": "string", "description": "Travel date as YYYY-MM-DD" },
"class": { "type": "string", "enum": ["SL", "3A", "2A", "1A"] }
},
"required": ["from", "to", "date"]
}
}The enum limits class to four real values, the date format is spelled out, and "Does not book anything" tells the model this tool is safe to call freely.
The shortcut
Before shipping a tool, cover the code and read only the definition, then ask: "Could I call this correctly, and would I know when not to?" If you would have to guess a format, a unit or a side effect, the model will guess too.
Split by job
One tool doing three jobs becomes three:
search_trains,get_weather,read_calendar.
The definition covers what goes in; design what comes out with the same care. Return compact, labelled results ("fare_inr": 1180, not a raw web page), and make errors say how to recover: "date must be YYYY-MM-DD" lets the model fix its call on the next turn, while "bad request" leaves it guessing.
Keep the toolset small and non-overlapping. Two tools with similar descriptions force the model to guess between them, and every definition costs tokens on every call.
Drills
Answer fast — trust the rule.
What does the model use to decide which tool to call?
Which schema feature stops the model sending class: "sleeper-ish"?
Which is the better tool name?
Why add "Does not book anything" to the search_trains description?
Remember
- The model sees only the name, description and input schema — write them for a stranger.
- Shortcut: hide the code, read the definition — could you call it right and know when not to?
- Trap: vague, overlapping tools that force the model to guess.