A tool schema describes a tool to the model — its name, what it does, and what arguments it expects — using the same structured, precise approach as JSON Schema. A poorly written schema is one of the most common causes of unreliable tool calling.
Anatomy of a Good Tool Schema
{
"name": "search_products",
"description": "Search the product catalog by keyword. Use this
when the user asks about finding or browsing
products, NOT for checking a specific known
order's status.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search keywords, e.g. 'wireless headphones'"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return",
"default": 5
}
},
"required": ["query"]
}
}Why the Description Matters So Much
The model decides which tool to use largely based on the description field — a vague or ambiguous description directly causes the model to pick the wrong tool, or fail to use the right one when it should. Treat writing tool descriptions with the same care as writing a good prompt (see Prompt Engineering) — because that's effectively what it is.
Before/After Example
Weak description: "Gets order info"
→ ambiguous — does this search orders, check status, cancel an
order? The model has to guess.
Better description: "Retrieves the current shipping status and
estimated delivery date for a SPECIFIC order, given its order ID.
Does not search or list orders — use search_orders for that."
→ specific about what it does, what it needs, and explicitly
distinguishes it from a similar, easily-confused toolDistinguishing Similar Tools
When multiple tools have overlapping purposes, explicitly clarifying the distinction in each tool's description (as in the example above) meaningfully reduces the model selecting the wrong one — an easy, high-leverage fix for a very common tool-calling reliability problem.
Practical Use Case
A system with 10+ available tools needs deliberately well-differentiated schemas — as tool count grows, ambiguous descriptions increasingly cause wrong-tool selection, making schema quality a real, ongoing engineering concern, not a one-time setup task.
Common Mistakes
- Writing terse, vague tool descriptions ("gets data," "does the thing") instead of specific, unambiguous explanations of purpose and when to use it
- Not distinguishing between similar tools explicitly, leading to frequent wrong-tool selection
- Missing required parameter descriptions, leaving the model to guess expected formats (e.g. date format, ID format)
Interview Relevance
"A model keeps calling the wrong tool out of two similar options. What would you fix first?" — reviewing and clarifying both tools' descriptions to explicitly distinguish their purposes is the highest-leverage, most direct fix.
Practice Question
Write a tool schema for a cancel_order function that clearly distinguishes it from a hypothetical get_order_status tool, minimizing confusion between the two.
