The API your agent calls was updated last Tuesday. A field was renamed. created_at is now createdAt. The team that owns the API shipped a changelog. Nobody told your agent.
Your agent doesn't read changelogs. It reads outputs. And when it reads { "createdAt": "2026-06-20" } and looks for created_at, it gets undefined. It doesn't crash. It keeps going, using undefined wherever the date used to be.
This is schema drift. It's one of the quietest failure modes in production agents. No exception. No alert. Just a growing gap between what the agent thinks it knows and what's actually true.
Why agents don't catch this
Most agents don't validate tool outputs against a schema. They parse whatever they receive, try to extract the values they need, and continue. If a key is missing, many LLMs will either hallucinate a plausible substitute or proceed with null values that corrupt downstream reasoning.
The model was trained to be helpful. Being helpful means not stopping to complain about a missing field. So it fills in the gap.
This isn't a model bug. It's a design assumption that didn't hold: that the tools the agent relies on are stable. In production, tools are never stable indefinitely.
What schema drift looks like in practice
Case 1: Field rename. The API ships a breaking change. Your agent extracts undefined for every date field. Downstream logic that compares dates now always evaluates false. Your agent starts telling users that no appointments exist.
Case 2: New required argument. The API now requires a version parameter. Requests without it return an error object rather than the expected data. Your agent doesn't check for errors — it tries to parse the error object as if it were a real result.
Case 3: Enum expansion. A status field that used to contain ["active", "inactive"] now includes "suspended". Your agent's internal logic maps two states. When it encounters "suspended" it falls through to a default branch and misclassifies the record.
Case 4: Nested restructure. The API moved pagination metadata from the top level into a meta object. Your agent used to stop when it hit the last page. Now it never finds the end-of-page signal and loops indefinitely.
Why this takes weeks to find
Schema drift rarely causes immediate explosions. The agent keeps running. It produces outputs. Those outputs look mostly correct.
The failures are subtle: a report with incorrect dates, a list that's missing records, a process that loops longer than expected. These look like data issues or user error. Someone files a ticket. It gets triaged as low priority. By the time a developer traces it back to the tool output, three weeks of incorrect outputs have shipped.
What Faultmap checks
Before you build against a tool, Faultmap maps the full output schema at the field level. Every field, every type, every possible enum value. Then it monitors for drift.
When a field disappears, a type changes, or a new enum value appears, Faultmap surfaces it before it ships. You see the delta. You decide whether to update the agent or pin the tool version.
You don't find out three weeks later from a bug report.
The fix before you build
Pin your schemas. Treat tool output schemas the same way you treat library versions. Explicit. Versioned. Breaking changes require a deliberate update.
Validate at the boundary. Every tool call should run through a schema validator before the LLM processes the output. If validation fails, fail loud — don't let the agent improvise with malformed data.
Test against real tool outputs. Mock responses don't drift. Real APIs do. Your test suite should include integration tests that call the actual tools and validate the output schema on every build.
Monitor in production. Log the raw tool outputs, not just the agent's final answer. When schema drift happens (and it will), you want the first alert to come from your monitoring stack, not from a user.
The tool didn't break. The contract between the tool and your agent did. That contract has to be explicit, versioned, and validated — or you'll keep finding out about drift the hard way.