Phase 2: Tool Design & Function Calling · 50 min · Python · Pydantic · OpenAI SDK
Designing Tool Schemas
The description field is the API contract between your system and the model.
Hiring signal: Tool schema design is a concrete deliverable in AI engineer roles. At Stripe, Notion, and Linear, engineers own the tool library for their domain — schema review is part of code review. Candidates who treat schemas as a user interface (for the model) stand out.
What you will learn
- Write tool names, descriptions, and parameter schemas that maximize selection accuracy
- Design parameter types, enums, and required/optional flags that guide the model toward correct calls
- Audit an existing tool library for schema weaknesses
The Problem
Two agents have a search tool. Agent A's tool is called search, takes a query string, and has the description "search for information." Agent B's tool is called search_product_catalog, takes query, category, and max_price, and has the description "Search the product catalog by name or description. Use this for questions about available products, pricing, or inventory. For order history, use get_order_history instead."
Agent B's tool selection accuracy is 94%. Agent A's is 61%. The difference is entirely in the schema design — no model change, no prompt change, no architecture change.
The Anatomy of a Great Tool Schema
A tool schema has four components, each with a job to do:
Name: Use a specific verb+noun pattern that is unambiguous even when surrounded by other tools. get_order_status not search. search_product_catalog not lookup. The model uses the name as a primary signal for whether a tool is relevant — generic names create ambiguity.
Description: Answer three questions for the model: (1) When should I call this tool — including situations where it might seem relevant but isn't? (2) What does this tool return? (3) What are the alternatives when this tool isn't the right one? A description that only says "gets order data" gives the model nothing to work with. A description that says "Returns real-time order status including shipping updates. For order history and past purchases, use get_order_history instead." gives the model a complete usage policy.
Parameters: Use the most specific type available. When a parameter has a fixed set of valid values, use an enum — the model will only produce valid values and will never hallucinate "in_transit" or "processing" when your system only accepts "pending", "shipped", "delivered", "cancelled". Include a description on every parameter, even obvious ones. For free-form parameters, include examples.
Required vs. optional: Mark a parameter as required only if the tool cannot function without it. A tool with too many required parameters creates a catch-22: the agent needs the tool to get information, but needs information to call the tool. Review each required parameter — if there's a sensible default, make it optional.
You're designing a tool that queries orders. Which parameter design is better for an "order_status" filter?
Enum type is the strongest constraint — the API and model both know exactly what values are valid, eliminating hallucinated inputs like "in_transit". Including "Omit to return all" tells the model when NOT to pass the parameter. Option A is human-readable but doesn't constrain the model. Option D uses magic numbers, an anti-pattern that makes schemas unreadable.
Unlock the full lesson
You've read the first 2 sections. The rest of this lesson covers Parameter Design Patterns, Common Schema Anti-Patterns, Build It, What to Practice — plus a hands-on lab, quiz, and project artifact.
Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.
Browse all courses · View pricing · DeVenture Academy