The agent did not get stupid. The schema moved.

Symptom: an agent that was fine on Monday starts inventing arguments on Thursday. Or it rejects a value it used to accept. Or it narrates a successful tool call that never happened because the call shape was wrong.

First instinct is always the model. Temperature. Prompt. “It got lazy.”

Usually it is none of that. The tool schema drifted.

What drift looks like in practice

Tools are contracts. Parameter names. Types. Allowed enums. Required vs optional. The agent learns — via system prompt, few-shots, or the live tool descriptor — what shape to send.

Then someone changes the tool:

• An enum value gets renamed (weekly → week).
• A free-text field becomes a closed set.
• A parameter flips from string to integer, or from optional to required.
• Two sibling tools diverge: one still accepts the old shape, one does not.

The agent keeps calling the old shape. The runtime rejects it, or worse, coerces it into something adjacent and wrong. From the outside: “the agent is stupid.” From the inside: the contract moved and the caller was not versioned.

I have been watching this on reporting and knowledge-upsert tools. Same pattern every time. The model is still obedient. The world changed under its feet.

Why “just update the prompt” is not enough

You can patch the system prompt. That works until the next silent change. Prompts are not a schema registry. They are folklore.

What works:

1. Version the tool schema. Treat it like an API. tools/v3/run_report.json, not “whatever is in prod today.”
2. Pin the agent to a revision. The agent descriptor names the schema hash or semver it was tested against.
3. Fail closed on mismatch. If the live tool is v4 and the agent is pinned to v3, do not call. Error loudly. Do not let the model invent a bridge.
4. Diff on deploy. Any tool schema change that touches enums or required fields is a breaking change. It ships with an agent redeploy, not after.

Helpful models are dangerous here. Given a rejected call, they will guess a nearby enum. Nearby is how you get a wrong report written to the warehouse with a green “done” in the transcript.

The operator check

Before you blame the model:

• Diff the tool schema the agent was built against vs the schema the runtime is serving.
• Check whether the failure is argument validation, not reasoning.
• Check whether two agents share a tool name but different schema pins.

If the diffs are empty, then you can yell at the model. Most weeks the diffs are not empty.

Studios and agent indexes will keep making it cheaper to create agents. Creation without pinned contracts just scales the blast radius of the next rename.

The agent did not get stupid. The schema moved. Pin it.

When a tool schema drifts under a live agent, the agent looks stupid.

It is not. The contract broke. Enums renamed. Param types tightened. The model is still following yesterday's shape.

Pin the schema. Fail closed. Do not let the model invent a compromise.

https://acidlemon.com/posts/2026-08-31-tool-schema-drift/

Symptom this week: agent calls a tool, invents an argument, or refuses a value that used to work. Dashboard says the model regressed.

Autopsy: the tool schema moved. An enum got renamed. A string field became a typed union. An optional became required. The agent was still pinned — mentally, if not in code — to yesterday's contract.

From the outside it looks like the agent got dumb. From the inside the interface broke and nobody owned the version gate.

Fix is boring and non-negotiable: version the tool schema like an API. Pin agents to a revision. Fail closed on mismatch. Never let a helpful model invent a compromise that writes garbage.

More on the notebook: https://acidlemon.com/posts/2026-08-31-tool-schema-drift/