Tool Schema Design: The Prompt You Forgot You Were Writing

Tool definitions get written once, early, usually by transcribing an existing API. Then they sit in the prompt on every turn of every session, quietly determining how reliably the agent behaves.

They are prompt engineering, and treating them as configuration rather than as writing is one of the most common reasons agents underperform.

Fewer tools, less confusion

The most reliable improvement is reducing the number of tools.

Every tool competes for the model's attention. Twenty tools with overlapping purposes produce wrong-tool errors that six clear ones do not. If two tools could plausibly serve the same request, the model will sometimes pick the wrong one, and it will do so unpredictably.

Audit for overlap specifically. A codebase with search_files, grep, find_symbol and lookup_definition has four ways to do one thing, and the model must guess which you meant. Merging them into one tool with a mode parameter usually improves reliability more than any prompt tweak.

Descriptions should say when not to use it

Most tool descriptions state what the tool does. The more useful half is when it should not be used.

"Reads a file. Use for specific files you already know the path of. Do not use to explore — use search first, then read the specific results" prevents a whole class of behaviour where the agent burns turns opening files at random.

Negative guidance is disproportionately effective because it addresses the failure the model is actually prone to, rather than restating what the name already implies.

Parameter design

Required means required. A required parameter the model cannot determine from context forces invention. If a value might genuinely be unknown, make it optional and handle the absence.

Enums over free strings. A closed set eliminates an entire failure class and makes validation meaningful. Anywhere the valid values are known, enumerate them.

Flat over nested. Every level of nesting adds a way to get the shape wrong. Deeply nested parameter objects are noticeably less reliable than flat ones with more fields.

Describe every parameter. Descriptions are read by the model. A field named limit with no description invites a guess about units, range and meaning.

Give examples in the description. One concrete example of a well-formed value does more than a paragraph of specification, particularly for string formats like paths, globs or query syntax.

Return the smallest useful thing

Tool results become prompt content, competing for attention with everything else and consuming context permanently for the rest of the session.

A search returning full file contents for twenty matches has just consumed an enormous share of the working context. The same search returning path, line number and a two-line excerpt gives the model what it needs to decide what to read next, at a fraction of the cost.

Design tool output for the model's next decision, not for completeness. If the model needs more, it can ask — that is what the loop is for. Tool result formatting covers the patterns.

Errors are instructions

An error message is the highest-leverage text in the whole system, because the model reads it at exactly the moment it needs to change behaviour.

"Invalid input" teaches nothing and produces an identical retry. "Parameter limit must be an integer between 1 and 100; received the string 'ten'" gets corrected on the next turn nearly always.

Write errors as if instructing someone who will act on them immediately, because that is exactly the situation. Name the parameter, state the constraint, quote what was received, and where possible suggest the fix. Agent error recovery patterns covers the loop-level handling.

Make retries safe

Agents retry. Design tools so a repeated call is harmless.

Idempotent operations — where calling twice has the same effect as calling once — remove a whole category of damage from a model that loses track of what it already did. Where true idempotency is impossible, an operation identifier that lets the tool recognise and ignore a duplicate achieves the same thing.

This matters most for anything that writes, sends or charges. A model repeating a read is wasteful; a model repeating a write can be destructive. Idempotency in agent actions covers the design.

Test the schema, not just the model

Run a few hundred calls against your real tools and measure schema-valid rate, correct-tool rate and parameter accuracy per tool.

The per-tool breakdown is the useful part. Aggregate reliability hides the fact that one badly described tool is producing most of the failures, and that is usually what is happening. Fixing that one description costs an afternoon and beats a model upgrade.