Versioning Tool Schemas in Long-Running Agent Deployments

Long-running agents fail in a way that is easy to miss and hard to debug. They keep running, their output looks right, and they quietly make the wrong decisions. The cause is tool schema versioning, and treating it as an application-level concern is exactly what makes it dangerous.

Why tool schema versioning is harder for agents than for conventional services

Restate's 2026 post gives this failure mode a name: silent corruption. The agent doesn't crash or warn. It reasons from a mismatched context and keeps going. The mechanism is concrete. Before an agent sends a result back to the model, the service is redeployed. On resumption, the agent calls the model with the updated tool descriptions but the old execution history. The model then interprets prior tool calls against the new schema. Schema description changes, prompt changes, guardrail changes, and tool removals each cause the model to reinterpret its own history differently. And the branching happens inside the model's probabilistic reasoning, not at a detectable code branch. There is no safe place in an agent loop to insert a version gate the way you would in a state machine.

This is structurally different from stateful-service versioning, where you embed version markers in state and add branching logic. That technique breaks down for agents. Agents are not fixed graphs with known branch points. Every iteration writes its own next step, so version branches compound on top of version branches. Keeping tasks short so they don't overlap with redeployments doesn't resolve it either. The execution history is still part of the state and must remain interpretable across versions regardless of task duration. The code is the manual the model uses to interpret its own prior actions. Tool descriptions, prompts, schemas, and model config get compiled into JSON and sent to the model as context on every resumption.

What "the tool schema" actually encompasses and why its scope keeps expanding

A tool schema is not just a function signature. It is the full contract the model uses to decide whether to call a tool, how to call it, and how to interpret the result. That contract spans multiple independently versioned systems. Four co-versioned layers together define an agent's behavior: code, prompts, model version, and tool contract version, which covers schemas, API endpoints, and response formats. The tool contract layer changes independently of agent code. When an upstream API like Stripe updates or an internal search index changes its response structure, that is a schema version change for the agent even if the agent codebase is untouched. A deployment manifest must lock all four layers into a single reproducible artifact. If you cannot recreate exact behavior from the manifest, you have a label, not real versioning. Metis (arXiv:2608.25322) makes the point structurally: built-ins, plugin tools, and MCP tools must all resolve through one registry before dispatch. That is a single authority path, not parallel resolution routes that can diverge.

The surface keeps growing. An evaluation of 177,436 agent tools created from November 2024 to February 2026 found that the share of action tools, those that modify external environments, rose from 27% to 65% of total usage over the sampled period. Schema accuracy is now a safety property, not just a correctness one. Three failure classes recur: tool-description poisoning, where a tool describes itself to encourage misuse. Schema under-specification, where recipient constraints, side-effect declarations, or retention behaviors are missing. And implementation drift, where the declared schema no longer matches what the implementation does. Schemas are the trusted computing base. They tell the model what a tool does and tell the runtime how to parse and dispatch the call. An inaccurate schema corrupts both the agent's decisions and the audit trail that records them.

Why treating schema versioning as application logic always breaks under operational pressure

Application-level versioning of tool schemas fails at the points of highest operational pressure: long waits, human-in-the-loop pauses, and cascading multi-agent pipelines. Agents waiting on human approval or extended research can run for days or weeks. Redeployments during that window are not edge cases but operational certainties. In a multi-agent pipeline that moves from planning to execution to review, if a new version deploys mid-run, downstream agents may get response formats from a version they were never built to consume. A schema field added in a new version corrupts rollback for in-flight sessions. The state written by the new version is not readable by the old one.

ATR (arXiv:2609.08015) sharpens why application-level checks are insufficient. A version conflict means state changed. A decision conflict means the change invalidates the action's justification. Detecting that the schema changed does not tell the application if the in-flight agent's pending action is still valid. Those are different questions, and application code that detects one still has no answer to the other.

Governance compounds the problem. PwC's Audrey Quessada-Vial (arXiv:2608.11166) diagnoses that existing LLMOps and AgentOps platforms do not offer a framework-independent configuration and governance model capable of describing, validating, and governing the system as a coherent whole. Configuration management remains fragmented across frameworks, making reproducibility, impact analysis, and long-term maintenance increasingly difficult. That is a practitioner diagnosis from a production context, not a vendor position. The problem exists independent of which orchestration framework a team chooses. Without a unified model, a guardrail approval granted under one policy gets treated as an approval under a different policy after a schema update. That is a concrete trust failure, not just a configuration inconvenience.

The two infrastructure rules that make schema versioning a runtime property

Making versioning an infrastructure property rather than an application concern requires exactly two enforced rules: immutable deployments and pinned execution contexts. Immutable deployments means every deployment is a complete, versioned snapshot. Code, prompts, tool definitions, schemas, guardrails, and model configuration are locked together. Once deployed, it never changes in place. New versions are deployed alongside old ones, not on top of them. Pinned execution contexts means every agent execution continues on the version it started with. Long-running tasks inherit their schema contract at spawn time, not at the moment a new version ships. Restate's 2026 post states the goal directly: "versioning becomes an infrastructure property, instead of something you need to worry about at the application level."

This pattern requires that the infrastructure layer, not the application, be responsible for routing in-flight executions to their originating version and for preventing schema changes from reaching them mid-run. The alternative, keeping tasks short to avoid overlap, fails in practice. The execution history must remain interpretable across versions regardless of task duration, and most agent SDKs are not designed for the reimplemented agent loop this would require. The two rules are simple to state. Implementing them at the infrastructure layer is where the real architectural work begins.

How the MCP protocol layer can serve as the schema distribution and deprecation bus

MCP's tool discovery mechanism makes the schema contract explicit and dynamic at the protocol level. The deprecation policy baked into the protocol directly governs how schemas can evolve without breaking pinned executions. An MCP client calls tools/list to receive the full schema of every available tool: names, descriptions, and input schemas. The agent uses this to decide which tools to call and how to call them. The schema is not embedded in agent code but fetched from the server at runtime.

The July 2026 MCP spec revision removes transport-level session management entirely, so the protocol core is stateless and scales on ordinary HTTP load-balanced infrastructure. Requests carry Mcp-Method and Mcp-Name headers so load balancers route without opening the body. Tools support full JSON Schema 2020-12. And a formal deprecation policy with a minimum 12-month removal window is now in force. That removal window is structurally aligned with the pinned-execution rule. An in-flight agent running for weeks or months is guaranteed that a tool it discovered at spawn time cannot be removed from under it within that window.

OpenPort Protocol (arXiv:2602.20196) formalizes explicit versioning in the URL path, such as agent/v1, for long-lived clients. Within a major version, servers evolve the protocol in a backward-compatible manner: additive fields, additive tools, stricter governance defaults. Clients treat tool discovery as dynamic because permitted tools and schemas may change with scopes, policy constraints, and incident-response revocations. Auditing the inputSchema of each tool and the underlying API permissions the server holds must happen not just at setup time but whenever the server is updated. That is a scheduled, recurring check rather than a one-time onboarding step.

The hidden cost of versioning: how schema size compounds across model upgrades

Every version bump that adds fields compounds a structural cost. Tool schemas consume significant token budget on every invocation, and schema accumulation across versions can disable smaller models entirely. Tool schemas are transmitted as JSON, a format designed for machine parsing, not for interpretation by language models. This protocol mismatch is the primary source of tool-use failure at production catalog sizes for smaller models.

The compression is not uniform across models. Per-operator isolation reveals three distinct profiles: operator-hungry, operator-sensitive, and operator-robust. A schema optimized for one model version may need recompilation when the underlying model is upgraded. That adds a model-version dependency to the schema-version dependency. The result is a versioning matrix: schema version multiplied by model version multiplied by compilation profile. It is a combinatorial problem that application-level management cannot track reliably, but a schema registry can.

Where schema registries belong in the agent runtime stack

A schema registry that lives at the runtime layer, not in the application and not in a shared document store, is the mechanism that makes immutable deployments and pinned execution contexts operationally tractable at scale. Metis (arXiv:2608.25322) demonstrates the principle. Built-ins, plugin tools, and MCP tools resolve through one registry before dispatch. Textual skills change instructions and tool visibility but do not create a second authority path. A child agent loop receives a cloned gate and filtered registry. The version boundary is enforced structurally, not by convention.

TSCG's compiler-based approach enables a community-curated registry of pre-compiled tool schemas spanning API services, including compiled schemas for Stripe, Slack, Notion, and GitHub. Pre-compiled standard MCP servers such as filesystem, Postgres, and GitHub MCP. And database, cloud, developer, and productivity tool schemas. Each entry includes compiled versions for multiple archetype profiles: conservative, balanced, and aggressive. Entries also carry tested-against-models metadata, benchmark results, and version pinning relative to the source API. An agent runtime that manages the schema registry can enforce the pinning rule automatically. When a new schema version is published, the registry routes new agent spawns to the new version while keeping in-flight executions bound to their originating version. No application-level branching logic required.

Microsoft Agent Framework reached 1.0 GA on April 3, 2026, unifying Semantic Kernel and AutoGen into a single production-ready SDK and runtime for.NET and Python. Both predecessors remain in maintenance mode. Azure AI Foundry Agent Service is one managed runtime backend. It is a signal that purpose-built agent runtimes with unified registries are moving from research patterns to production infrastructure. The gap between "the runtime enforces version isolation" and "the application is supposed to handle version isolation" is exactly the gap between infrastructure reliability and fragile convention. A developer-first agent OS that installs with a single command and exposes schema registry, version pinning, and execution routing as primitives removes the entire class of versioning bugs that application-level approaches must laboriously work around.

What a safe schema evolution workflow looks like in practice

Safe schema evolution in long-running agent deployments is a defined workflow, not a set of ad hoc checks. It operates at three distinct points: before a schema change ships, at deployment time, and during the deprecation window. Before a change ships, audit the inputSchema of every affected tool and the underlying API permissions the server holds. This means checking not just the schema diff but whether the implementation still matches the declaration. Classify the change. Additive fields are backward-compatible and can be deployed to new versions without breaking pinned executions. Field removals or semantic changes to existing fields require a new major schema version and a parallel deployment. And use ATR's distinction between version conflicts and decision conflicts: determine not just that a field changed but whether the change invalidates any pending agent action that observed the prior value.

At deployment time, deploy the new schema version as an immutable snapshot alongside the existing one. Never overwrite. Update the registry to route new spawns to the new version. The deployment manifest locks the new schema version, the model version, the prompt version, and the code SHA into a single artifact. Any execution that cannot be reproduced from its manifest is not versioned. Verify that in-flight executions remain bound to their originating schema version. That is an infrastructure check, not an application check.

During the deprecation window, respect the MCP formal deprecation policy. A minimum 12-month removal window applies to any tool schema exposed over MCP. Communicate deprecation through the protocol's deprecation fields, not out-of-band documentation. Monitor which in-flight executions are still running on deprecated schema versions. When the last execution on a version completes, the old snapshot can be retired from the registry. If the underlying model is upgraded, recompile and re-profile tool schemas against the new model. The operator-profile mapping, across operator-hungry, operator-sensitive, and operator-robust, may shift, changing which compilation archetype applies.