Function Schemas
In Lesson 1 you saw the tool-call cycle in action. But how does the model know what tools are available, what arguments they accept, and what they do? The answer is the function schema — a structured definition, written by the developer and passed to the model at the start of a conversation, that describes each tool in precise, machine-readable terms. The schema is the contract between the model and the executor: the model commits to calling tools exactly as the schema describes, and the executor commits to accepting calls in that format.
Anatomy of a Function Schema
Function schemas in modern AI APIs are written in JSON Schema, a widely used standard for describing the structure of JSON data. A complete tool definition has three required top-level fields: name: A short identifier the model uses when emitting a tool call. It must be unique within the tool set and should be a snake_case string that reads like a verb-noun pair: get_weather, send_email, search_database, calculate_mortgage. The name appears verbatim in the tool call the model emits, so it must match what the executor expects exactly. description: A natural-language explanation of what the tool does, when to use it, and — critically — when not to use it. This is the most important field for the model. The model reads descriptions and reasons about which tool fits the current situation. A vague description produces unpredictable tool selection. A precise description with examples produces reliable behavior. parameters: A JSON Schema object that defines every argument the tool accepts. This includes the data type of each argument (string, number, boolean, array, object), a description of what each argument means, which arguments are required versus optional, and any constraints on valid values (minimum, maximum, enum for fixed sets).
When you write a function schema, the description field is not documentation for humans — it is the primary signal the model uses to decide whether and how to use the tool. Poor descriptions are the single most common cause of incorrect tool selection. Write descriptions as if the model's only knowledge of the tool comes from that text — because it does.
Here is a complete, well-written function schema for a weather tool: { 'name': 'get_current_weather', 'description': 'Returns the current weather conditions for a given city. Use this tool when the user asks about current weather, temperature, or conditions in a specific location. Do not use for historical weather data or forecasts beyond today.', 'parameters': { 'type': 'object', 'properties': { 'city': { 'type': 'string', 'description': 'The city name, e.g. Chicago, London, Tokyo. Include the country if the city name is ambiguous.' }, 'unit': { 'type': 'string', 'enum': ['celsius', 'fahrenheit'], 'description': 'Temperature unit. Default to celsius unless the user specifies otherwise.' } }, 'required': ['city'] } } Notice several design choices: the description explicitly states when NOT to use the tool (not for historical or forecast data), preventing the model from reaching for this tool in the wrong situations. The city description gives concrete examples. The unit parameter uses an enum to constrain valid values to exactly two strings, preventing the model from inventing variations like 'Celsius' (capitalized) or 'F'. The required array tells the model that city is mandatory while unit is optional.
Match each schema field to its primary purpose in the tool-calling system.
Terms
Definitions
Drag terms onto their definitions, or click a term then click a definition to match.
Schema Quality Makes or Breaks Tool Use
The difference between a good schema and a poor one is the difference between a reliable agent and a broken one. Consider two versions of a schema for a database search tool: Poor version: name: 'search' description: 'Searches things.' parameters: { query: { type: 'string' } } Good version: name: 'search_customer_records' description: 'Searches the customer database by name, email, or customer ID. Returns up to 20 matching records with name, email, account status, and join date. Use when the user needs to look up a specific customer or find customers matching a criterion. Do not use for product or inventory searches.' parameters: query: { type: string, description: 'The search term. Can be a full name, partial name, email address, or numeric customer ID.' } limit: { type: integer, minimum: 1, maximum: 20, description: 'Maximum number of results to return. Default 10.' } status_filter: { type: string, enum: ['active', 'inactive', 'all'], description: 'Filter by account status. Default all.' } The poor version gives the model almost no signal — it might reach for this tool when it should not, fill in arbitrary argument values, or miss available filtering options. The good version tells the model exactly what the tool does, what data it returns, when to use it, and how every argument behaves. Schema authoring is a design discipline, not a clerical task.
A model that misuses a tool due to a poor schema will not raise an exception — it will call the tool with plausible-looking but wrong arguments, and you will get wrong results that look like correct ones. Vague descriptions and missing argument documentation are a source of hard-to-debug agent failures.
Fill in the key fields of a complete function schema.
A model has two tools: get_weather (description: 'Get current weather') and get_forecast (description: 'Get weather forecast for the next 7 days'). A user asks 'Will it rain in Seattle this weekend?' Which tool should the model call, and why?
A function schema defines a parameter with 'type': 'string', 'enum': ['low', 'medium', 'high']. What happens if the model tries to emit 'critical' as the value for this parameter?
Write a Function Schema From Scratch
- You are building a smart calendar assistant. It needs a tool to create a new calendar event.
- Step 1: Decide on a name for the tool (remember: verb-noun, snake_case).
- Step 2: Write a description (2-4 sentences). Be specific: what does it do, what does it return, when should it be used, and is there anything it should NOT be used for?
- Step 3: Define at least 4 parameters. For each: name, type, description, and whether it is required or optional. Consider: what makes an event — title, date, time, duration, location, attendees, recurrence?
- Step 4: If any parameters have a fixed set of valid values (e.g. a recurrence_type might be 'daily', 'weekly', 'monthly', 'none'), use an enum.
- Step 5: Exchange schemas with a partner. Try to find one case where their description would cause the model to misuse the tool, and one parameter that is under-described. Give specific improvement suggestions.
- Goal: practice the discipline of writing schemas that are precise enough for a model to use reliably.