Designing Tool Schemas AI Agents Actually Use Correctly

A tool schema isn't just a technical contract between your code and a model, it's the actual interface the model reasons against when deciding whether and how to call a tool. Two schemas exposing the same underlying functionality can produce meaningfully different call accuracy depending on how clearly they're described, and that difference compounds across a real agent workflow with many tool calls.

Names and descriptions carry more weight than they seem to

A tool named process with a vague one-line description forces the model to infer its actual purpose largely from context, increasing the odds it's selected incorrectly or given wrong arguments. A tool named send_refund_confirmation_email with a clear description of exactly when it should and shouldn't be used gives the model far less room for misinterpretation. Specific, unambiguous naming and description is doing real work, not just documentation for humans reading the code later.

Keep functionally similar tools clearly distinguished

If two tools have overlapping purposes with a subtle difference, a search tool for internal documents and a separate one for external web search, for example, the descriptions need to make that distinction explicit and hard to miss, since a model choosing between similar-sounding options under ambiguity is a common source of wrong-tool-selected errors.

Parameter design: fewer, clearer fields beat many optional ones

A tool with a dozen optional parameters, several of them rarely used and loosely described, gives a model more opportunities to omit something that mattered or fill in something incorrectly. Splitting an overly complex tool into a couple of more focused ones, each with a smaller, clearer parameter set, tends to produce more reliable calls than one tool trying to handle every possible variation through optional flags.

Constrain values wherever the real world allows it

Where a parameter genuinely has a fixed, known set of valid values, use an enum rather than free text, this removes an entire category of near-miss or hallucinated value errors that free-text fields are prone to. Reserve free text specifically for fields that genuinely need it, don't default to it for convenience where a constrained type would work.

Write descriptions for a model with no other context

A model deciding whether to call a tool generally doesn't have access to your codebase's internal documentation or the assumptions your team carries about how the system works, it has the schema and description text you provided, and whatever's in the current conversation. Writing the description as if explaining the tool to someone with zero prior context, rather than a terse internal-shorthand label, produces more reliable tool selection.

Test schema changes the same way you'd test a prompt change

A schema edit, renaming a parameter, changing a description, adding a new tool with an overlapping purpose, can shift call accuracy in ways that aren't obvious from reading the change alone. Running your eval set against a schema change before shipping it catches regressions the same way it does for prompt changes, since the schema is functionally part of the same interface the model is reasoning against.

The core principle

Design tool schemas the way you'd design a well-documented public API for a human developer with no inside knowledge, clear names, unambiguous scope, constrained types where possible, because that's functionally closer to what the model is actually working from than most teams initially assume.