Every Tool Call Is a Contract Designing AI Agent Schemas That Dont Lie

Why Tool Descriptions Break AI Agents (And How to Fix Schema Drift)

A client called me in a panic last spring. Their customer support AI began duplicating orders.

The problem started right after a small code update. A developer updated the backend fulfillment service. They merged the order lookup tool with a reorder fallback routine. The code passed internal unit tests. But no one updated the tool description given to the AI.

To the AI, the tool description was clear. It said the tool only checks order status. But behind the scenes, the function had a new rule. If an order had an issue, it created a replacement order right away.

The AI did not know that. It ran the tool as asked. In response, the server placed brand new orders.

I learned a big lesson that day. In an AI agent setup, your tool description is not just casual notes. It is your live interface.

When software engineers write code for other people, bad docs cause a quick chat or a failed build. But when you give an AI a tool description that drifts from reality, the system does not fail loudly. It guesses user intent. It loops over and over. It invents bad inputs. Or it triggers unwanted side effects by mistake.

Here is what happens when schemas drift, why tool descriptions matter so much, and how to build schemas that keep your tools reliable.

The Real Interface Why Language Is Runtime Logic

In standard software design, code types and databases enforce rules. If a tool needs a number and gets text, the server stops it with a clear error.

With AI agents, the runtime router is plain language.

When an AI chooses a tool, it reads the tool names and descriptions in your schema. It looks at the text to decide what to do.

If the description is vague, incomplete, or out of date, the model has no way of knowing. It cannot read your server code or inspect your database. It treats your text description as pure fact.

If your schema says a tool only reads data, but the code edits records, you have put a lie into the model prompt. Every tool call is an agreement: if you pass these inputs under these terms, this exact result will happen. Break that rule, and the agent breaks too.

4 Ways Schema Drift Breaks Production Agents

In my consulting work, I see schema drift fall into four common traps.

1. The Undocumented Parameter Problem

When developers add new features, they often add optional arguments to backend tools. If you leave these out of the schema, the model will either:

• Guess their names and pass bad values.
• Miss key filters, flooding the prompt with too much data.

I once worked on an audit where a search tool had a hidden limit set to one hundred items. The model thought it was getting the top five results because the description said: "Finds the best matching notes." That huge data load filled the context window and drove up API bills fast.

2. Behavioral Shifts in Returned Data

Sometimes the input stays the same, but the output shape changes.

If a tool used to return simple order IDs, and an update changes it to return nested carrier objects, the agent will stumble. The AI gets confused by new keys and passes bad data to the next step.

3. Boundary Collisions Between Overlapping Tools

As your tool list grows from three to thirty, tool descriptions start to step on each other.

• Trigger (User Prompt): "Where is our remote work travel policy?"
• Evaluation (Model Step): The model examines available schema descriptions.
• Collision Point:
• Tool A (search\_files): Description reads "Searches through company documents."
• Tool B (query\_knowledge\_base): Description reads "Searches internal documentation."
• Failure Mode: Ambiguous boundary lines force the AI into a random guess between cloud drive storage and the team wiki.

When a user asks where to find the travel policy, which tool should the AI pick? Without clear boundaries, the model has to guess. If one tool checks cloud storage and the other checks a wiki, the choice is just a coin flip.

4. Unhelpful Error Payloads Breaking the Recovery Loop

A good contract covers failures too.

When a server sends back a blank error, the AI has no way to fix its mistake. It will often try the exact same call three times until it hits a limit.

When the tool returns a clear error note—like stating that a date was formatted wrong and showing the right format—the model fixes the input on its next try.

How to Design Schemas That Tell the Truth

Fixing schema drift takes simple, daily habits. Here are the steps that work best in live setups.

Define Negative Boundaries

Most teams only write what a tool can do. Just as vital is telling the model what it should not do.

If you have a tool that stops a plan, do not just write: "Stops a user plan."

Instead, write: "Stops an active user plan. Use only when the user asks to cancel. Do not use to pause an account or give a refund. For refunds, use the refund tool instead."

This simple rule stops wrong tool calls before they happen.

Provide Concrete Format Examples

Never rely only on broad types like text or number. A text type tells the model almost nothing about what you expect.

Explicitly State Side Effects

If a tool writes, edits, or deletes data, say so in plain words. Models handle risky actions much better when the schema warns that the action makes permanent edits in the live database.

Preventing Drift Across Your Team

To keep your schemas in sync as your team ships updates, set up a simple check flow:

1. Maintain Tool Definitions Alongside Application Logic

Do not hide tool descriptions in far-off files. Keep the description and input rules right next to the code that runs the tool. When a developer changes a function, they update the schema text in the exact same pull request.

2. Build Tool Evaluation Suites into Deployment Checks

Whenever you change a tool description, run a small test set of sample queries before you deploy:

• Prompts that should pick the tool.
• Prompts that should pick other tools.
• Prompts that should pick no tools.

If an edit fixes one edge case but breaks basic routing, your tests catch it right away.

Actionable Schema Design Checklist

• Single Job: Does the tool do one clear, well-defined task?
• Clear Exclusions: Does the note explain what the tool should avoid?
• Exact Formats: Are dates, IDs, and allowed values clearly shown with examples?
• Open Side Effects: Does the note state if the tool reads or edits data?
• Helpful Errors: Do error messages tell the model how to fix bad inputs?
• Shared Location: Is the schema kept right beside the handler code?
• Test Coverage: Has the schema passed a check against positive and negative test prompts?

Practical Reflections from Implementation

When teams build AI tools, they often spend all their time tweaking system prompts or testing new models.

Yet in my experience, when an AI tool fails in production, the issue is rarely model smarts. It is almost always an outdated or misleading tool schema.

Treat your tool definitions as real contracts. Write clear notes that match your code, set firm boundaries, and test them often. When your schemas tell the truth, your AI workflows stay calm, steady, and reliable.

Frequently Asked Questions

Why not let the AI infer parameter details from context?

While models can guess missing details, guessing is risky. Without exact format rules and defaults, the model will invent values. In live apps, guessing leads to random errors, slow retries, and corrupted data.

How detailed should a tool description be?

Keep descriptions between two and four short sentences. State what the tool does, when to call it, what tools to use instead, and any needed setup. Avoid long walls of text that crowd the prompt.

What is the difference between system prompt guidance and tool descriptions?

The system prompt sets the general persona, safety rules, and top-level policies. Tool descriptions give exact, local rules for running single actions. Keeping action details in the schema keeps your main prompt clean.

How should tools handle large volumes of returned data?

Never send huge, raw lists back to the model. Filter, summarize, or paginate records on the server first. Always explain page settings in your schema so the model can browse data step by step.

Suggested External References

• JSON Schema Standards Documentation (json-schema.org): The standard reference for structural schema validation.
• Provider Guidelines on Function Calling & Tool Use: Industry documentation covering tool definitions, constraints, and structured error responses.
• Model Context Protocol Guidelines: Open community frameworks for managing tools, schemas, and resource access in automated workflows.