Tool Schema

What is a tool schema?

A tool schema is the structured contract that describes valid input for an AI agent tool. It defines fields, data types, required values, allowed options, formats, and sometimes nested structures or constraints.

The schema gives both the model and application a shared representation of what a well-formed tool request should contain.

What a schema can define

A flight-search schema might specify:

• origin and destination as required text values;
• departure_date in a defined date format;
• passengers as an integer within an allowed range;
• cabin as one of several supported values;
• optional filters such as maximum stops.

The model uses this structure when preparing a tool call. Application code validates the generated arguments before execution.

Schema versus definition

A tool definition explains what a tool does and when it is useful. A tool schema focuses on the shape of its input. Both are necessary: a clear description helps the model choose the right tool, while a precise schema helps it call that tool correctly.

A schema also differs from the underlying API contract. A tool may expose only a safe subset of a complex API. The application can translate the tool’s simple fields into the provider-specific request.

What schemas can and cannot validate

Schemas can catch structural errors such as a missing field, wrong data type, invalid enumeration value, or malformed date. They cannot always determine whether a request makes business sense or is authorized.

For example, a schema can confirm that account_id is text, but not that the current user owns the account. Business rules, permissions, and current-state checks belong in the execution layer.

Common design problems

Ambiguous field names lead to incorrect arguments. Huge schemas consume tokens and make tool calls harder to generate. Weak constraints accept values the implementation cannot process. On the other hand, a schema that is too rigid may reject legitimate requests.

Builders should use clear field descriptions, explicit units and formats, narrow enumerations where appropriate, and meaningful validation errors. Schema changes should be coordinated with the tool implementation and tested against representative calls.

Why it matters

A well-designed schema turns free-form model output into a predictable request that software can inspect. It reduces malformed calls, supports safer execution, and makes failures easier to diagnose. It does not replace authorization or judgment, but it provides a reliable first boundary between language generation and external actions. See [Tool Use in AI Agents](/tool-use-in-ai-agents/) for the complete tool-use lifecycle.