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.
Interview question
When an LLM invokes a tool through a tool definition schema, which step does the model itself perform?
- a.It selects the appropriate tool and produces a JSON payload matching the schemaCorrect
- b.It executes the external API call and receives the raw response
- c.It dynamically rewrites the JSON Schema to better fit the user's request
- d.It validates the emitted JSON against the schema before sending it
Why? this is the answer
The model acts like a customer placing an order: it selects the tool and emits a structured JSON payload, but the application code validates the payload and executes the actual API call. Option D is tempting because validation occurs right after generation, yet it is strictly the application's responsibility, not the model's.
Just read this? Test yourself on what you have been reading.
- #llm
- #function calling
- #json schema
- #tools
- #agents
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on llm — each one lists the topics its interview covers.
See open roles