Lesson 8 — Tool schemas

Describing tools to the model

The model cannot read your Python code. It only sees a short description of each tool, called a schema:

• name — what the model writes to ask for it.
• description — one sentence on when to use it. The model chooses tools by reading this.
• parameters — the inputs: their names, types ("string", "number"...) and which are required.

{"name": "add", "description": "Add two numbers.",
 "parameters": {"type": "object",
                "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
                "required": ["a", "b"]}}

The parameters part follows JSON Schema, a standard way to describe JSON data. Real providers accept almost exactly this (OpenAI calls the field parameters, Anthropic calls it input_schema).

Why it matters: a vague description is the most common reason an agent picks the wrong tool. Writing good schemas is a real skill.