Tool Definition Schema: Contracts for LLM Actions
A tool schema is JSON that tells an LLM what actions it can take. Use it when you want the model to call APIs instead of just chatting. The model only emits arguments; it never runs the tool, and vague descriptions cause silent failures.
WHY IT EXISTS: LLMs generate text, but real applications need them to act. Early prompt engineering tried to coax models into emitting structured commands, but it was brittle and prone to hallucination. A formal contract was needed so the model could declare its intent in a machine-readable format that downstream code could trust and execute safely.
THE MENTAL MODEL: Think of a tool definition schema as a menu in a drive-through. The menu lists every item, what ingredients go into it, and what questions the cashier might ask. The LLM is the customer reading the menu. It does not cook the food; it places an order. Your application is the kitchen that receives the order, validates it, and actually prepares the meal. If the menu is vague, the customer orders something that does not exist.
HOW IT WORKS: You write a schema, almost always in JSON Schema format, for each capability you want the model to access. Each definition contains a name, a natural language description that the model uses to select the right tool, and a parameters object with types, required fields, and constraints. When you send a user prompt to the model, you attach this schema in a dedicated tools or functions field. The model then decides whether to respond in plain text or to emit a structured JSON object matching one of your schemas. Your code intercepts that JSON, validates it against the schema, performs the actual API call or computation, and optionally feeds the result back to the model in a subsequent turn.
WHEN TO USE IT: Use tool schemas whenever the LLM needs fresh data or side effects that its training data cannot provide. Classic cases include retrieving live weather, searching a vector database, performing a calculation with a calculator, updating a ticket status, or fetching user-specific account details. They are also essential for agentic workflows where a model must plan multi-step tasks and delegate steps to specialized utilities.
WHEN NOT TO USE IT: Do not use tool schemas for tasks the model can handle entirely with its internal knowledge, because the round-trip adds latency and cost. Avoid them when the operation is unsafe and cannot be validated, such as arbitrary code execution without sandboxing. Also skip them if the output structure is simple and static; a basic JSON output instruction in the prompt is often lighter than a full tool contract.
ONE CANONICAL EXAMPLE: Imagine a travel assistant. You define a tool named get_flight_price with a description that says it retrieves current airfare between two airports on a given date. The parameters schema requires origin as a three-letter airport code, destination as a three-letter code, and departure_date in ISO 8601 format. When the user asks what it costs to fly JFK to LAX tomorrow, the model does not guess. It emits a JSON object with those exact keys. Your backend validates the codes, calls the airline API, and returns the price. The model then composes a friendly sentence with the real number.
Get five bites like this every day.
Tezvyn delivers a daily feed of 60-second tech bites with quizzes to lock in what you learn.