Tool Schema Design for AI Agents: How Bad JSON Schemas Increase Token Spend

A Bad Tool Schema Is a Token Multiplier

Tool schemas look like plumbing, but they are one of the most important cost controls in an AI agent system. Every schema is included in the model's working context or tool inventory. Every ambiguous field increases the chance of a wrong call. Every validation error can trigger another model turn. In long coding sessions, a bad JSON schema does not just create bugs; it creates compounding token spend.

This is especially true for coding agents. Tools are how the agent reads files, edits code, searches the repo, runs tests, opens pull requests, and calls internal systems. If those tools are described poorly, the model spends extra tokens reasoning around the ambiguity, then spends more tokens recovering when the call fails.

The Four Cost Paths of Bad Schemas

Shorter Is Not Always Cheaper

A schema can be too long, but it can also be too terse. Removing descriptions may save a few input tokens while increasing invalid calls. The best schema is not the shortest schema; it is the schema with the lowest cost per successful tool action. Sometimes a precise 30-token field description saves a 3,000-token repair loop.

The right design target is compressed clarity. Use short field names when obvious, but write descriptions that remove real ambiguity. Include examples for fields that frequently fail. Avoid long policy essays inside every tool; put shared policy in the system prompt or tool-use rules so it can be cached and reused.

Design Rules for Lower-Cost JSON Schemas

1. One tool should do one job. Split read, edit, search, and execute operations when their parameters differ meaningfully.
2. Use required fields honestly. Do not mark fields optional if the tool almost always needs them.
3. Name fields by intent. Prefer targetFilePath over vague names like value or input.
4. Keep enums small and distinct. Avoid overlapping modes such as update, modify, and change.
5. Return exact validation errors. The model should know which field failed and what valid values look like.
6. Version schemas. Track retry rates before and after schema changes instead of guessing.

A Cost Example: Extra Fields and Repair Turns

Suppose an edit tool rejects extra JSON fields. The model includes an extra reason field because the schema description implies the agent should explain its edit. The validator rejects the call. The agent receives an error, re-reads the tool schema, and tries again. In a short session, that is annoying. In a long-context session with repository files, tool lists, and test logs, it can add tens of thousands of repeated input tokens.

The fix might be small: clarify that explanations belong in the assistant message, not the tool payload; or allow a harmless optional explanation field if it does not create downstream risk. The point is to design for the model's behavior and the validator's needs together. A schema is an interface for both software and a probabilistic caller.

What to Log in Production

Schema Reviews Should Be Part of Cost Reviews

Most teams review prompts and model choices before they review schemas. That order is backwards for agent systems. Tool schemas define what the model can do and how often it fails while doing it. A monthly AI cost review should include the top tools by token spend, validation retry rate, average repair turns, and schema version changes.

The fastest savings often come from boring changes: removing unused fields, splitting an overloaded tool, making enum names clearer, or improving validation errors. These changes lower cost without changing model providers or reducing developer access.

Bottom Line

Bad JSON schemas make AI agents expensive by increasing prompt size, ambiguity, validation failures, and repair loops. Good schemas reduce cost by making the correct tool call obvious and recovery cheap when mistakes happen. If your agent budget is rising, do not only compare model prices. Audit the tool contracts that turn model intelligence into work, then use the AI Cost Estimator to quantify the retry savings.