A tool schema, also called a tool definition, is the structured, machine-readable description of a function that a language model may call: its name, a natural-language description and a typed specification of its input parameters, usually written in JSON Schema. In the field of AI agents, the tool schema is the contract between the model and the outside world, because the model never sees the tool’s code, only this description.
Every tool call an agent makes is shaped by the schema. The model reads the descriptions to decide whether a tool is relevant, and it uses the parameter specification to produce arguments in the expected format. A precise schema therefore improves both tool selection and argument accuracy, while a vague one causes wrong calls, missing fields and wasted agent loop iterations.
Components of a tool schema
A tool schema consists of three core elements: an identifier, a description and an input specification. Some platforms add optional elements such as an output schema, behavioral annotations or a strict-mode flag that forces the model to follow the schema exactly.
| Field | Purpose | Good practice |
|---|---|---|
| Name | Unique identifier the model emits in a call | Short verb phrase such as get_order_status |
| Description | Explains what the tool does and when to use it | State purpose, limits and expected inputs |
| Input schema | Typed definition of parameters | Use types, enums, required lists and formats |
| Output schema | Describes the structure of the result | Helps the model parse returned data |
| Annotations | Hints such as read-only or destructive | Mark side effects for permission checks |
| Strict flag | Enforces exact schema conformance | Enable for production integrations |
The input schema typically declares an object with named properties, each with a type, a description and, where relevant, an enum of allowed values, a pattern, or numeric minimum and maximum bounds. The required array tells the model which parameters it must always supply, and setting additionalProperties to false rejects invented fields.
How the model uses the schema during tool calling
During tool calling, the application sends the tool schemas together with the conversation, and the model treats them as part of its context. When the model decides that a tool is needed, it emits a structured call containing the tool name and a JSON arguments object; the application validates the arguments against the schema, executes the real function and returns the result to the model.
Schemas consume context window tokens on every request. A single tool definition typically costs from about 50 to several hundred tokens, so an agent with 100 tools can spend tens of thousands of tokens before the user says anything. Providers that support prompt caching reduce the cost of repeated schemas, but the attention cost of many similar tools remains and tends to lower selection accuracy.
The following table traces the role of the schema through one complete call cycle.
| Step | Actor | How the schema is used |
|---|---|---|
| Registration | Application | Declares available tools to the model |
| Tool selection | Model | Compares the task with tool descriptions |
| Argument generation | Model | Fills parameters to match types and constraints |
| Validation | Application | Checks arguments before any execution |
| Execution and result | Application | Runs code and returns output to the model |
Tool schemas across protocols and platforms
Most major model APIs and agent protocols describe tools with JSON Schema-based definitions, but the field names and supported keywords differ. Portable tool libraries therefore keep one canonical definition and translate it for each target platform.
| Context | Schema form | Notable characteristic |
|---|---|---|
| Model APIs | Name, description and parameter schema | Often support a strict or structured mode |
| MCP server | Tool list with an input schema per tool | Discovered dynamically by an MCP client |
| Agent frameworks | Generated from function signatures | Type hints and docstrings become the schema |
| OpenAPI | Operation definitions for REST endpoints | Convertible into tool definitions |
| Agent card | Capability and skill listing | Describes an agent, not a single function |
With the Model Context Protocol (MCP), schemas are discovered at runtime rather than hard-coded, which makes integration easy but also means the agent trusts descriptions written by a third party. That trust has security consequences discussed below.
Designing effective tool schemas
An effective tool schema is written for the model as its reader, much as good API documentation is written for a new developer. The description should state what the tool does, when it should and should not be used, what the parameters mean in business terms and what the tool returns.
- Prefer enums over free text for parameters with a fixed set of values, such as status or region.
- Specify formats explicitly, for example ISO 8601 dates, currency codes or units of measure.
- Keep tools focused: one clear action per tool rather than a single tool with a mode switch.
- Use distinct names and descriptions so that similar tools cannot be confused.
- Limit parameter nesting to two or three levels, because deep structures increase argument errors.
- Version the schema and test agents against it whenever it changes.
Teams that refine schemas should evaluate them like prompts, measuring tool selection accuracy, argument validity rate and task success on a fixed set of scenarios. Small wording changes in a description can shift selection behavior noticeably.
Failure modes and security risks
Tool schemas fail in predictable ways, and most failures trace back to ambiguity, overload or misplaced trust. Because the description is text inside the model context, it can also carry hidden instructions, a risk known as tool poisoning when a malicious server embeds directives in its descriptions.
| Symptom | Likely cause | Fix |
|---|---|---|
| Wrong tool chosen | Overlapping descriptions | Clarify scope and add usage boundaries |
| Invalid arguments | Loose types or missing constraints | Add enums, patterns and required fields |
| Invented parameters | Open object definition | Set additional properties to false |
| Tool ignored | Vague or generic description | Describe concrete triggers for use |
| Unsafe action executed | No side-effect annotation | Mark destructive tools and require approval |
Validation against the schema is necessary but not sufficient for safety. A syntactically valid call can still delete the wrong record, so destructive tools need agent permissions, human-in-the-loop approval or sandboxed execution in addition to a well-formed schema.
In simple terms
A tool schema is like the label and instruction card on a machine in a workshop. It tells a new worker what the machine is called, what it is for and exactly which settings it needs.
An AI agent cannot look inside its tools, so it relies entirely on these cards. Clear cards lead to correct use; vague cards lead to mistakes. That is why developers spend real effort writing the name, the description and the list of required inputs for every tool.
A practical example
An online retailer builds a customer service agent with tools for order lookup, returns and refunds. The first version of the refund tool has a free-text reason field and an amount field without units, and the agent sometimes submits amounts in cents, sometimes in dollars, and occasionally calls the refund tool when the customer only asked about return eligibility.
The developers rewrite the schema. The amount becomes a decimal in the order currency with a maximum equal to the order total, reason becomes an enum of six approved codes, and the description states that the tool must be used only after a return is confirmed. The tool is also annotated as destructive, so refunds above 100 dollars require staff approval. On a test set of 250 support conversations, invalid refund calls fall from about 9 percent to under 1 percent, and premature refund attempts disappear.