Agents fail loudly when tool schemas are vague. A missing required field, an open string where an enum belongs, or a nested object with no max depth invites invent-as-you-go calls. Bound the schema before the first live call.
A bound schema is small, typed, and hostile to surprise inputs. It tells the model what is legal. It tells your runner what to reject. Without that pair, retries become guesswork.
List only the fields the tool truly needs
Start from the production call, not from a wishlist. Keep required fields minimal. Mark everything else optional with defaults in your code, not in the model prompt. Extra optional fields become places for the model to hallucinate values.
Pair this with hard tool call limits so a confused schema cannot spin unbounded retries.
Prefer enums and ranges over free text
Where a field has five legal values, use an enum. Where a number has a safe range, set min and max. Free-text IDs should carry format patterns. Soft prose fields belong in user content, not in tool arguments that hit APIs.
Tight types catch bad calls before network I/O. That is cheaper than parsing error bodies after the fact.
Reject unknown keys at the gate
Configure your validator to forbid additional properties. Models love inventing helpful fields. Your API does not. A hard reject with a short error message teaches the next turn better than silently dropping keys.
Log the rejected payload shape next to the tool name. You will see schema drift early, the same way you watch for bad ids with object ID checks.
Version schemas the way you version APIs
Name tools with a version suffix when fields change meaning. Keep old versions available until evals pass on the new one. Silent field renames break transcripts and caches. Treat a schema change as a release, not a prompt tweak.
When you measure prompt cache behavior, unstable tool definitions also shatter prefixes. See prompt caching cost traps for that failure mode.
Test schemas with hostile fixtures
Before wiring the tool to production credentials, feed the validator empty strings, huge strings, wrong types, and extra keys. Confirm rejections are clear. Then run a small agent suite that must call the tool correctly, using ideas from eval harnesses for tool-calling agents.
A schema that only works on happy demos is not bound. It is decorative.
Document one example call beside the schema
Store a single golden JSON example next to the schema file. Keep it valid. Point the model at the schema, not at a paragraph of prose rules. Prose drifts. Examples and validators do not.
Bound schemas will not make agents brilliant. They make illegal calls boring and rare, which is how tools stay shippable.
FAQ
What does it mean to bound a tool schema?
It means required fields stay minimal, types are tight, unknown keys are rejected, and changes are versioned like an API.
Why are free-text tool fields risky?
They invite invented values that fail at the API and burn retries. Enums and ranges shrink that space.
Should I allow additional properties?
No for production tools. Reject unknown keys and return a short error the next turn can use.
When should I version a tool name?
When field meanings change. Keep the old version until evals pass on the new schema.
How do I test a schema before launch?
Run hostile fixtures through the validator, then a small agent eval that must produce legal calls.
Where should examples live?
Keep one golden JSON example beside the schema file instead of long prose rules in the prompt.