Designing a tool schema
“How do you design a good tool schema for an LLM, and what makes a schema bad?”
What this tests
- Understanding that the schema is the model's interface and needs to be unambiguous
- Knowledge of JSON schema features: enums, required fields, descriptions
- Awareness of tool granularity and tool-count effects on selection accuracy
- Thinking about the return shape, not just the arguments
Answers by level
Read the beginner answer first and notice what is missing.
A tool schema is an API contract for a caller that only reads the docs. The name should be a verb phrase that describes one action (get_order_status, not orders). The description says when to use it and when not to, with an example. Parameters are typed narrowly: enum for fixed choices, format: date for dates, required set explicitly, and each parameter has a description with units and valid ranges. See Tool Schemas.
Bad schemas are vague or overloaded: a single query: string that the model must format itself, optional parameters with hidden defaults, boolean flags that change semantics, or one tool that does five things depending on a mode field. Each of these pushes ambiguity onto the model and shows up as Argument Validation errors and wrong selections.
The return shape matters as much: return structured, compact results with stable field names and explicit error objects ({ error: "not_found", id }) so the model can act on failure instead of guessing. And keep the tool count small; selection accuracy degrades as similar tools multiply.
Green flags · Red flags
- Verb-phrase names, single responsibility per tool
- Uses enums, required fields, descriptions with units and examples
- Designs the return shape and error objects
- Mentions tool count and selection accuracy
- Validates server-side regardless of schema
- Measures selection accuracy and argument validity
- Praises "flexible" tools with free-form string arguments
- Ignores return shape or errors
- No mention of validation
- No awareness that descriptions need iteration
Follow-up questions
mode enum or three tools?Practical scenario
search_customers(query), find_customer(q), and lookup_customer(name_or_email). Selection accuracy is 71%. Propose a redesign of the customer tools, explain how you would measure the improvement, and estimate what else you would change about the tool set.