What is a tool?
Read · 1 of 3
The model can't run code. You can.
A model only writes text. A tool lets it ask your program to do something: search, calculate, read a file, call an API.
You describe each tool with three things: a name, a description and an input_schema (JSON Schema for its arguments). The model reads these and, when a tool would help, replies with a tool_use block naming the tool and its arguments.
The description is the model's only documentation. Say what the tool does, when to use it, and what it returns. Vague descriptions mean wrong calls.
Read this lesson as text
A name, a description and an input schema. The description is the model's only manual.
The model can't run code. You can.
A model only writes text. A tool lets it ask your program to do something: search, calculate, read a file, call an API.
You describe each tool with three things: a name, a description and an input_schema (JSON Schema for its arguments). The model reads these and, when a tool would help, replies with a tool_use block naming the tool and its arguments.
The description is the model's only documentation. Say what the tool does, when to use it, and what it returns. Vague descriptions mean wrong calls.
Which description?
A = {"name": "search", "description": "Searches."}
B = {"name": "search_orders",
"description": "Find a customer's orders by email. Use when the user asks about an order, delivery or refund. Returns up to 5 orders with id, date and status."}Which tool will the model use well?
- A: shorter is clearer
- B: it says what, when, and what comes back
- Neither: models ignore descriptions
Show the answer
B: it says what, when, and what comes back. With A the model has to guess what "search" searches and when to call it. B tells it exactly when the tool applies and what it will get back, so it calls it at the right moments with the right input.
Exercise: Write a tool definition
Input: the tool's name, its description, then k, then k lines param type required|optional description words.
Print the definition as one line of JSON with json.dumps: name, description, and input_schema = {"type": "object", "properties": {...}, "required": [...]}. Each property is {"type": ..., "description": ...}.