Designing Tool Schemas

How to write tool schemas the model will actually call correctly, and why description quality outranks naming.

A tool schema is JSON Schema attached to a tool definition: name, description, and input_schema describing the parameters. The model reads this schema at inference time and decides two things from it: whether to call the tool at all, and what arguments to pass. Nothing else is available to the model — no source code, no comments in your codebase, no tribal knowledge. If the schema is ambiguous, the model's behavior will be ambiguous.

Description beats name

Exam-relevant point: the model selects tools primarily from the description field, not the name field. A tool named search with a three-word description will be selected incorrectly far more often than a tool named x1 with a precise, example-rich description. Treat the description as the primary interface contract, not the name. Good descriptions state: what the tool does, when to use it (and when not to), what each parameter means, units and formats for ambiguous fields (is a date a Unix timestamp or ISO 8601? is a price in cents or dollars?), and edge-case behavior (what happens on an empty result set, what happens if a required lookup fails).

Parameter design

Keep required parameters minimal and give optional parameters sane defaults described in the schema text itself, since the model cannot read your server-side default logic. Use enum constraints wherever the parameter space is closed — this reduces invalid calls far more effectively than prose alone. Prefer flat, explicit parameter names over deeply nested objects when the tool will be called frequently; nested structures increase the chance of malformed tool_use input, especially with smaller models. Where a parameter's format is easy to get wrong (a phone number, a currency code, a compound identifier), give one or two examples directly in the parameter's own description, not just in the top-level tool description.

Scoping tools

A single tool that does one well-defined thing is easier for the model to select correctly than one tool with a mode flag that switches between five behaviors. If you find yourself writing a description with branching logic ("if action is create, then...; if action is delete, then..."), that is usually a sign you should split it into separate tools with separate names and descriptions. This also makes error handling and permissioning per-action cleaner downstream.

Testing schemas like an interface, not an implementation detail

Because the schema is the only thing standing between a natural-language request and a correctly-formed function call, it deserves the same review rigor as a public API contract. Read the description as if you had never seen the underlying implementation and ask whether it alone would let you fill in every parameter correctly. A useful exercise is to hand the schema, with no other context, to a fresh model conversation along with a handful of realistic user requests and see whether the resulting tool_use input is what you would have written by hand. Mismatches point directly at where the description is underspecified. This kind of review also surfaces overloaded parameters — a single field silently expected to hold either an email or a username, for instance — that are easy to miss when you already know, from having written the backend, which one you meant.

It also pays to think about how the description reads next to the descriptions of every other tool available in the same conversation. Two tools with similar-sounding descriptions but different side effects (one that previews a change, one that commits it) are a common source of the model picking the wrong one under time pressure. Make the distinguishing detail — read-only versus mutating, reversible versus not — explicit and early in the description text rather than buried at the end, since that is the detail most likely to disambiguate a close call between two similar tools.

Scenario: a support-ticket tool takes a status string parameter with no further constraint. In production, the model sometimes sends "closed", sometimes "Closed", sometimes "resolved" — none of which match the backend's expected value of "CLOSED". The right fix is to add an enum listing the exact valid status strings in the schema, not to add a sentence to the description asking the model to "use the correct status format." Constraints the model can see in the schema are far more reliable than instructions it has to remember and infer correctly.

Try it

Write a tool schema for a "cancel_subscription" action against a fictional billing API. Give it a required subscription_id string and an optional reason enum with three or four values. Deliberately write a bad, one-line description first, call it with a vague natural-language request, and see what arguments the model produces. Then rewrite the description with an explicit statement of when to call it, an example subscription_id format, and a note about what happens if the subscription is already canceled. Compare the two runs.