What is Tool Schema?
Also called tool definition, function schema.
A tool schema is the machine readable description of a single capability offered to a language model, giving the tool a name, a natural language description of when to use it, and a formal definition of its parameters. Models rely on this description alone when deciding whether and how to call the tool, so its wording directly shapes behavior.
Parameters are almost always expressed with JSON Schema: types, required fields, enumerated values, and per field descriptions. The model reads the whole structure as text inside its context window. Constraints such as enums and required fields do double duty, steering the model toward valid arguments and letting the application reject invalid ones before anything executes.
The description field is the highest leverage text in most agent systems. It is effectively a prompt, read every time the model considers acting. Stating what the tool does, when to prefer it over similar tools, what it returns, and what it must never be used for removes most of the ambiguity that causes wrong tool selection in the first place.
Common errors include copying internal API documentation verbatim, leaving parameter descriptions empty, exposing cryptic internal field names, and accepting free text where a fixed set of allowed values would do. Another is forgetting that every schema consumes context on every request, so a hundred verbose tools can crowd out the conversation they were meant to support.
A schema constrains shape and never meaning. A perfectly valid call can still be the wrong call, with a well formed date that is the wrong date or an identifier pointing at the wrong account. Schemas therefore sit alongside server side validation and permission checks rather than replacing them.
Key points
- Name, description, and parameter definition for one capability.
- Parameters are usually expressed using JSON Schema.
- The description is read by the model and behaves like a prompt.
- Enums and required fields reduce invalid arguments.
- Valid shape does not mean correct intent, so validate server side.
In practice
A tool named create_calendar_event is described as: create an event on the user's primary calendar, only after the user has confirmed the exact time. Its schema requires a title string, a start time in ISO 8601 format, and a duration in minutes between fifteen and four hundred eighty, with an optional list of attendee emails. That narrow duration range alone prevents a whole class of accidental week long bookings.