The agent's tool schema is a contract. It tells the model what functions exist, what parameters they accept, what types those parameters have, and what the function does. The model uses this contract to construct every tool call it makes.
When the contract changes and the agent doesn't know, the agent constructs calls against the old contract. The calls are wrong. The errors are confusing. And unlike a typed API client that fails at compile time, the agent fails at runtime — in production, on real user requests.
What changes break agents
New required fields. The API adds a required field to a function. The agent was never told about it. The agent calls the function without the new field. The call fails with a validation error the agent wasn't expecting.
Renamed parameters. A parameter named user_id becomes userId (camelCase migration). The agent keeps sending user_id. The API either rejects it or silently ignores it, depending on whether validation is strict.
Changed enum values. A status field that accepted "active" and "inactive" now accepts "enabled" and "disabled". The agent keeps sending "active". The API rejects it.
Changed response shape. The API changes where a field lives in the response object. The agent's post-processing logic extracts from the old path. It gets undefined. It either errors, or worse, treats undefined as a valid value and passes it forward.
Deprecated functions. A function is removed or its behavior changes. The agent calls it as before. The response is unexpected. The agent tries to interpret it.
Why this is harder for agents than for services
Traditional services are updated when their dependencies change. Someone updates the client library, tests fail, the team fixes the call, deploys. The feedback loop is explicit and the failure is caught before production.
Agents are different. The tool schema lives in the system prompt or is injected at runtime. It's text, not code. There's no compile-time check. The model is the "caller," and it won't refuse to call a function whose schema is stale — it will call it with whatever arguments make sense given the schema it was given. The error is discovered when the call fails in production.
And because the agent might call a tool infrequently — only for certain user requests that trigger the relevant path — a schema mismatch can sit undetected for a long time before the first failing request reveals it.
The architecture for managing tool schema over time
Treat tool schemas as versioned artifacts. Every tool schema should have an explicit version. The agent's system prompt should reference the version it was built against. When the schema changes, the version increments.
tools:
- name: create_account
schema_version: "2.1.0"
...
Use a schema registry. Don't store tool schemas inline in prompts. Store them in a registry — a database, a configuration system, or a schema repository. The agent loads schemas at runtime from the registry. When schemas change, the registry version increments and the change is tracked.
This makes the question "what schema was the agent using when this failure occurred?" answerable. Without a registry, it's guesswork.
Enforce backward compatibility on schema changes. Before deploying a schema change, test it against the agents that use it. The test is: can an agent trained on schema version N-1 make valid calls against schema version N?
- Adding optional fields: backward compatible. The agent won't send the field; the API should handle its absence.
- Adding required fields: breaking change. The agent won't know to send the field. Either provide a default, make the field optional, or version the API.
- Renaming fields: breaking change. Accept both old and new name during a transition period.
- Removing functions: breaking change. Deprecate first (keep the function, return a deprecation warning), remove after agent is updated.
Validate calls before they hit the API. Build a schema validation layer between the agent and the API. When the agent constructs a tool call, validate the arguments against the current schema before forwarding the call. Return a structured validation error that the agent can understand: "required field account_type is missing." The agent can then correct the call or surface the issue.
Test schema drift as part of CI. When a tool's underlying API changes, your CI pipeline should include a test that runs the agent against the updated schema and checks whether it can still construct valid calls. This is a prompt-level regression test, not a unit test. Run a set of representative user requests through the agent and verify that all tool calls pass schema validation.
Monitor tool call validation rates. Track the percentage of tool calls that fail schema validation in production. A spike in validation failures on a specific tool is a signal that the schema changed and the agent wasn't updated. Catch this within hours, not after users have been filing support tickets for a week.
The team process
Schema changes to tools that agents use should require an explicit agent compatibility review — the same way database schema changes require a migration plan. The question is always: "will existing agents still produce valid calls after this change?"
If the answer is no, the deployment sequence is: update the agent's tool schema in the registry → redeploy the agent → verify in staging → deploy the API change. Not the other way around.
This is extra process. But it's less expensive than debugging why an agent started failing on Tuesday afternoon and working backward to discover that the payments API team shipped a required field change on Tuesday morning without telling anyone.
Tool schemas are contracts with the model. Treat them with the same discipline you give any other versioned contract.