2026-06-10

What is a tool schema / tool definition?

A tool schema or tool definition is a machine-readable description of a function, API, or action an LLM can call, including its name, what it does, and the inputs it accepts.

Why it matters

Tool schemas let you connect a model to real capabilities without letting it invent the interface.

In practice, they solve three common problems:

Structured calling: the model can ask for a function call instead of writing brittle free-form text.
Validation: the runtime can check that the model supplied the right arguments before executing anything.
Interoperability: apps can expose search, database queries, calculators, workflow steps, or external APIs in a consistent format.

If you are building an agent, tool schemas are usually the contract between the model and the rest of your system.

How it works

A tool definition usually includes:

a name for the tool,
a description of when to use it,
a parameter schema that lists required and optional inputs,
sometimes the expected output shape.

That schema is often expressed in JSON Schema or a similar structured format, because the model and the application both need a precise contract.

The model uses the descriptions and parameter definitions to decide whether a tool is relevant and, if so, to produce a structured call like “use search_flights with origin=SF and destination=NYC.” The application then validates the call, executes the real tool, and returns the result back to the model if needed.

A useful way to think about it: the schema is not the tool itself. It is the metadata and contract that tells an LLM how to use the tool safely and correctly.

Tiny concrete example

{
  "name": "get_weather",
  "description": "Get the current weather for a city.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "units": { "type": "string", "enum": ["metric", "imperial"] }
    },
    "required": ["city"]
  }
}

A user asks: “What’s the weather in Paris?”

The model might respond with a structured call equivalent to:

{ "name": "get_weather", "arguments": { "city": "Paris", "units": "metric" } }

Your app validates those arguments, runs the weather API, and feeds the result back to the model.

Common pitfalls / when NOT to use it

Using vague descriptions. If the tool description is unclear, the model will choose the wrong tool or pass bad arguments.
Leaving parameters underspecified. Missing required fields, types, or enums makes validation weak and behavior inconsistent.
Treating the schema as security. A tool schema helps structure calls, but it does not replace authorization, rate limits, allowlists, or sandboxing.
Overloading one tool. Very broad tools are harder for models to use reliably than a smaller set of focused tools.
Using tools when plain text is enough. If the task is simple generation or summarization, adding tool machinery can increase complexity without benefit.

For most teams, the practical rule is: start with a small number of tightly scoped tools and a strict schema, then expand only when you see a real need.