Tool schema
Overview
A tool schema is a formal description that defines how a large language model or AI agent can invoke an external function, API, or service. It specifies the tool's name, purpose, required and optional parameters, parameter types, constraints, and expected outputs. This schema acts as an interface contract between the model's reasoning process and the executable environment.
Tool schemas enable agentic workflows by making external capabilities discoverable and invocable by models through structured calls. Rather than training a model to generate arbitrary text that describes an action, a schema constrains the model's output to a machine-parseable format with named parameters and type information. This reduces ambiguity, improves execution reliability, and facilitates error handling when a tool call fails or requires self-reflection.
Tool schemas are central to frameworks like Model Context Protocol (MCP), which standardizes how tools are exposed to models. They are also fundamental to ReAct-style agents and other planning-based agents that alternate between reasoning and tool use. The schema format itself is typically JSON, YAML, or similar structured notation that a model can reliably parse and generate.
How it works
A tool schema typically contains the following components:
- Name: A unique identifier for the tool (e.g., `search_web`, `calculate`, `retrieve_document`).
- Description: A natural-language summary of what the tool does, used by the model to decide when to invoke it.
- Parameters: A structured definition of inputs, including:
- Parameter name
- Type (string, integer, boolean, array, object, etc.)
- Required or optional designation
- Description and usage guidance
- Constraints (e.g., maximum length, allowed values, numeric ranges)
- Return type: Specification of the output format and structure the tool will return.
- Error handling: Optional specification of expected error conditions and how failures are reported.
When a model receives a tool schema, it can reason about which tools are relevant to a task, determine the appropriate parameters, and generate a structured invocation. For example, given a schema for `web_search(query: string, num_results: integer)`, a model might generate:
```json {"tool": "web_search", "parameters": {"query": "recent advances in LLMs", "num_results": 5}} ```
The execution environment parses this structured output, calls the underlying function with the specified parameters, and returns the result to the model in a format the schema defined. This feedback loop enables iterative multi-agent orchestration and context-aware tool selection.
Tool schemas may also include metadata such as rate limits, authentication requirements, or guardrails that restrict certain parameter combinations. Some frameworks generate schemas dynamically from function signatures or docstrings, while others require manual schema definition.
| Term | Distinction |
|---|---|
| Model card | A model card documents a model's capabilities, limitations, and training data. A tool schema documents the interface to an external function or service that a model can call. They serve different purposes: model cards inform users about the model itself; tool schemas enable the model to interact with external systems. |
| Prompt engineering | Prompt engineering shapes model behavior through natural-language instructions. Tool schemas define machine-parseable interfaces that constrain and structure the model's outputs to match expected function signatures. Tool schemas are more rigid and deterministic than prompts. |
| Instructions-as-Code | Instructions-as-Code embeds formal logic or constraints directly into prompts or system messages. Tool schemas are declarative specifications of available tools, not instructions on how to reason or behave. They complement rather than replace instruction engineering. |
| Context window | A context window is the maximum token length a model can process in a single input. Tool schemas are typically concise JSON descriptions that fit within the context window; they define what tools are available, not how much context the model can handle. |
| Embedding models | Embedding models map text to vector representations for retrieval. Tool schemas are structured metadata for function signatures. Embedding models may help retrieve relevant tools from a large schema repository, but the schema itself is not an embedding. |
Examples
OpenAI Function Calling: OpenAI's GPT models accept tool schemas in JSON format. A schema for a calculator might specify:
```json {
"name": "calculate",
"description": "Performs arithmetic operations",
"parameters": {
"type": "object",
"properties": {
"expression": {"type": "string", "description": "Mathematical expression to evaluate"}
},
"required": ["expression"]
}
} ```
The model receives this schema, reasons about when to use it, and generates a structured call. The environment executes the calculation and returns the result, enabling multi-step reasoning.
Anthropic's Tool Use: Anthropic's Claude models use XML-based tool schemas within system prompts. A retrieval tool might be specified with name, description, and parameter definitions. When Claude determines a tool is needed, it generates structured XML matching the schema, which the application parses and executes.
Model Context Protocol (MCP): The MCP specification formalizes tool schemas across multiple hosts and models. An MCP server exposes tools with JSON schemas describing parameters, return types, and descriptions. Clients (models) discover these schemas and can invoke tools through a standardized protocol, enabling multi-agent systems to share tool catalogs.
See also
- Agentic AI vs AI agent — Overview of agent-based model behavior.
- Planning (AI agent) — How agents use tool schemas to plan sequences of actions.
- Multi-agent orchestration — Coordination of multiple agents that share or discover tool schemas.
- Model Context Protocol — Standardized framework for exposing tool schemas to models.
- ReAct — Agent reasoning pattern that alternates between tool use and reflection.
- Self-reflection (AI) — How agents evaluate tool calls and recover from errors.
