Tool Schema
A tool schema describes a tool's name, purpose, and expected input format so a model knows how to call it correctly.
Prerequisites
What Is a Tool Schema?
A model can't call a tool it doesn't know exists, and it can't call it correctly without knowing exactly what input the tool expects. A tool schema is that description: a structured definition of a tool's name, what it does, and the shape of the arguments it accepts — given to the model alongside the request, so it has everything it needs to generate a valid call.
Tool Schema (name, description, parameters)
Structured DefinitionGiven to the model alongside the request.
Model Reads Schema
Knows the ShapeLearns exactly what input the tool expects.
Generates Matching Tool Call
Valid CallMatches the expected arguments exactly.
Code Example
Illustrative — the exact schema format varies by provider, but the shape is consistent:
{
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "City name, e.g. 'Austin'" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["city"]
}
}Why Schema Quality Matters
- A clear, specific description helps the model decide when this tool actually applies — vague descriptions lead to the model picking the wrong tool, or the right tool at the wrong time.
- A well-defined parameter schema constrains what the model can generate as input, reducing malformed or nonsensical tool calls.
- Required vs. optional parameters should reflect what the tool actually needs — marking too much as required can block valid calls; marking too little can produce incomplete ones.
- This is the same schema mechanism structured output relies on — both need the model to produce validated, well-formed data rather than free text.
Common Mistakes
Writing vague or overlapping tool descriptions
If two tools sound similar in their descriptions, the model has a harder time reliably choosing the correct one.
Trusting a tool call's arguments without validating them
A schema constrains what the model is likely to generate, but the receiving code should still validate arguments before acting on them.
Defining an overly complex parameter schema
Deeply nested or ambiguous parameter structures are harder for a model to fill in correctly and harder for a human to review.
Not keeping the schema in sync with what the tool actually does
If the tool's real behavior changes but the schema and description don't, the model keeps making decisions based on stale information.
Interview Question
What is a tool schema, and why does its quality directly affect how reliably a model uses tools?
A tool schema is a structured description of a tool's name, purpose, and expected input, given to the model so it can generate a valid call — the model can't use a tool it doesn't know about or doesn't understand the shape of. Schema quality matters because a clear, specific description is what lets the model correctly decide when a tool applies, especially when several tools exist; a vague or overlapping description leads to the wrong tool being picked, or the right tool being called incorrectly. The parameter definition itself constrains what the model is likely to generate, but the receiving code still needs to validate arguments independently — a schema shapes the model's output, it doesn't guarantee its correctness.
What an interviewer may ask next
- Why might a model call the wrong tool if two tool descriptions are too similar?
- Does a well-defined schema mean you don't need to validate the tool call's arguments?
- How does a tool schema relate to structured output?
Explain It in 30 Seconds
A tool schema is a structured description of a tool's name, purpose, and expected arguments, given to the model so it can generate a valid call. Its quality directly affects reliability: a clear, specific description helps the model choose the right tool among several, and a well-defined parameter structure constrains what it's likely to generate — though the receiving code still needs to validate arguments independently, since a schema shapes output, it doesn't guarantee correctness.