Agent Versioning Documentation Specification

TL;DR

Long-running agents break silently when a tool changes shape without telling them. This specification fixes that by requiring three things in every agent tool or skill manifest: a parseable version field, machine-readable deprecation metadata (deprecated_at, sunset_at, replacement_uri, severity), and a runtime version negotiation channel such as a X-Tool-Version request header. SemVer 2.0.0 is the default; date-based schemes are allowed when documented. The classification of what counts as a breaking change is non-negotiable: any field rename, removed parameter, type narrowing, or output shape change is MAJOR.

Definition

Agent versioning documentation is the contract between a tool publisher and the agent runtimes that consume it. It declares which version of the tool the manifest describes, how clients should request a specific version, what changes between versions mean, and how end-of-life is communicated. It applies uniformly to four surfaces:

• Tool manifests exposed by Model Context Protocol (MCP) servers (modelcontextprotocol.io/registry/versioning).
• Skill bundles such as Anthropic Agent Skills with SKILL.md and OpenAI Skills (anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills, developers.openai.com/api/docs/guides/tools-skills).
• Plugin and connector manifests that agents read at registration time.
• HTTP API endpoints invoked by agent tools, including third-party APIs the agent calls through a tool wrapper.

The specification is independent of any single registry. A tool can be published to multiple registries simultaneously and its versioning documentation MUST remain consistent across them.

Why It Matters

Versioning silence is the highest-impact preventable failure mode for production agents. Three failure patterns recur:

1. Manifest drift. A tool publisher updates the runtime behavior but not the manifest description. The agent still believes the old shape applies. The agent issues calls that succeed at the wire layer but produce semantically wrong outputs. There is no error to catch.
2. Silent breakage on latest tags. When a tool is referenced by a moving tag, a re-deploy can change the tool description mid-session. The MCP community has documented this as the “silent breakage” problem and recommends pinning to specific versions instead of latest (Reddit r/googlecloud discussion on MCP versioning).
3. Unsignaled deprecation. The publisher shuts down an endpoint or removes a parameter on a calendar deadline that the agent’s authors never saw. The agent fails on the cutover date. Studies of API governance attribute roughly 60% of operational disruptions in surveyed organizations to outdated software where deprecation timelines were not communicated cleanly (InstaTunnel review of API versioning vulnerabilities).

Agent platforms compound the impact. Claude, OpenAI, MCP clients, and orchestration frameworks like LangGraph all reuse tool descriptions across many sessions. A single ambiguous version field can break thousands of agent runs at once.

How It Works

Versioning documentation has three layers.

Layer 1: identity. Every published artifact has a unique, immutable version string. Once published, a version string MUST NOT be re-used. The MCP Registry enforces this rule: “The version string MUST be unique for each publication of the server. Once published, the version string (and other metadata) cannot be changed.” (modelcontextprotocol.io/registry/versioning).

Layer 2: meaning. The version string communicates what changed. SemVer 2.0.0 is the default scheme: MAJOR.MINOR.PATCH where MAJOR is incremented on backwards-incompatible changes, MINOR on backwards-compatible additions, and PATCH on backwards-compatible fixes (semver.org). Date-based schemes such as Stripe’s 2026-04-22.dahlia (Stripe API versioning) and the protocol-level YYYY-MM-DD MCP scheme (modelcontextprotocol.io/docs/learn/versioning) are also allowed when explicitly documented. Mixed schemes within the same artifact are forbidden.

Layer 3: negotiation. The agent runtime must be able to request a specific version. Stripe pins the requested version with a Stripe-Version header. The same pattern is generalized in this specification as a X-Tool-Version request header, supplemented by a version selector in the manifest URL where appropriate. When negotiation is unsupported, the publisher MUST document that fact and the implicit version selection rule.

flowchart LR
    A["Agent reads manifest"] --> B["Pin to version X"]
    B --> C["Issue tool call
+ X-Tool-Version: X"]
    C --> D{"Server supports X?"}
    D -->|Yes| E["Execute
+ deprecation headers if relevant"]
    D -->|No| F["Return version-mismatch error
+ supported versions list"]
    E --> G["Agent parses Sunset header"]
    G --> H["Schedule upgrade before sunset_at"]

Required Fields

The following fields MUST appear in every agent tool or skill manifest that claims compliance with this specification.

At runtime the same metadata MUST be echoed in HTTP responses for HTTP-based tools using the standard Deprecation and Sunset headers (RFC 8594, http.dev/deprecation). The body of the response MAY include a _meta.deprecated block mirroring the manifest fields (oneuptime.com guide on deprecation headers).

Breaking-Change Classification

A single ambiguous rule causes most versioning disasters. This specification adopts the SemVer 2.0.0 definition of “backwards incompatible” and lists the following changes as MAJOR by default. Reclassifying any of them as MINOR or PATCH is non-compliant.

Class conventions match the consensus across SemVer, Stripe SDKs, and Kubernetes API deprecation policy (docs.stripe.com/sdks/versioning, kubernetes.io/docs/reference/using-api/deprecation-policy).

Lifecycle States

Four states are defined. Transitions MUST be one-way except where explicitly noted.

• preview. The artifact is published but not stable. Breaking changes MAY occur on MINOR bumps. Agents SHOULD NOT depend on preview versions in production.
• ga. Generally available. Breaking changes only on MAJOR bumps. This is the default state for production agents to consume.
• deprecated. Still functional but scheduled for removal. The manifest MUST include deprecated_at, sunset_at, replacement_uri, and severity. Runtime responses MUST include Deprecation and Sunset headers.
• sunset. No longer responding. Calls return a stable error code with the replacement_uri in the body. The manifest entry remains discoverable for at least 90 days after sunset for audit purposes.

Reverting a deprecation (deprecated → ga) is permitted but MUST update changelog_uri with an explicit reversion entry.

Worked SKILL.md Upgrade Scenario

Anthropic Agent Skills do not specify a required version field in the core frontmatter, but the recommended pattern places version metadata under the optional metadata map (Deep Dive SKILL.md, abvijaykumar.medium.com). A spec-compliant skill upgrade looks like:

---
name: deploy-pipeline
description: "CI/CD deployment workflows for Kubernetes clusters."
metadata:
  version: "3.0.0"
  version_scheme: "semver"
  lifecycle_state: "ga"
  changelog_uri: "https://example.com/skills/deploy-pipeline/CHANGELOG.md"
  supported_versions: ["2.5.0", "2.6.0", "3.0.0"]
  breaking_changes:
    - field: "target_cluster"
      change: "renamed from cluster"
      migration: "Replace cluster: with target_cluster: in invocations"
  deprecated_at: null
  sunset_at: null
  replacement_uri: null
  severity: null
  last_updated: "2026-05-02"
  author: "platform-team"
---

When the same skill enters deprecation 18 months later, only the lifecycle fields change:

metadata:
  version: "3.0.0"
  lifecycle_state: "deprecated"
  deprecated_at: "2027-11-01"
  sunset_at: "2028-05-01"
  replacement_uri: "https://example.com/skills/deploy-pipeline-v4"
  severity: "high"

Changelog Format

changelog_uri MUST resolve to a document parseable by an agent. The minimum acceptable format is the Keep a Changelog convention: each version block contains an H2 with the version and date, plus subsections for Added, Changed, Deprecated, Removed, Fixed, and Security. JSON or YAML changelog formats are equally acceptable provided each entry includes version, date, and an array of typed change records.

Human-only release-note prose without structure is not compliant. Agents need to read the changelog programmatically when deciding whether to bump the pinned version.

Common Mistakes

• Treating SKILL.md version as optional. The frontmatter spec lets you omit it, but the skill is then untrackable. Always include metadata.version.
• Reusing version strings across re-publishes. The MCP Registry rejects this and other registries should follow. Bump the version even on small fixes.
• Mixing schemes. Do not combine SemVer and date-based versions in the same artifact. Pick one and document it in version_scheme.
• Documentation-only signals. A blog post announcing deprecation does not satisfy this specification. The signal must be in the manifest and in runtime headers.
• Skipping the breaking-change list. Even when MAJOR bumps are obviously breaking, list each break individually with a migration note. Agents synthesize migration plans from this list.
• Pinning agents to latest. Always pin to a specific version in the agent registration. Update the pin deliberately.

FAQ

Q: Should I use SemVer or date-based versioning for agent tools?

Default to SemVer 2.0.0 unless you have a strong reason to use date-based versioning. Date-based versioning shines when the API has many independent endpoints and you want each customer pinned to a date snapshot, as Stripe does. SemVer is simpler to communicate to agents and to changelog tooling. Whichever you pick, document it in version_scheme and never mix.

Q: How do I handle MCP’s YYYY-MM-DD protocol version when my server uses SemVer?

They are at different layers. The MCP protocol version describes the wire protocol between client and server. Your server’s tool versions are independent and may use SemVer. The MCP Registry recommends SemVer for published servers even though the protocol itself uses date-based versioning (modelcontextprotocol.io/registry/versioning). A draft proposal (SEP-1400) has explored adopting SemVer at the protocol level as well.

Q: What deprecation timeline is reasonable?

Minimum 90 days for high-severity deprecations and minimum 180 days for any deprecation that requires non-trivial agent migration work. Stripe’s policy is to almost never deprecate; Kubernetes guarantees at least one minor release of overlap. Pick a timeline that lets agent authors update before sunset and publish it the day deprecation begins.

Q: Do I need both manifest fields and HTTP response headers for deprecation?

Yes for HTTP-based tools. Manifest fields let registration-time tooling plan migrations; runtime headers let active calls notice deprecation that was published after the agent registered. The two channels target different consumers and are not redundant.

Q: How should agents react to a Deprecation header?

Log the event, surface it in the agent’s observability output, and either schedule an upgrade or refuse to reuse the deprecated version on the next session start. Agents that ignore deprecation headers will fail at sunset.

Q: Can a replacement_uri point to a different tool name?

Yes. The replacement is allowed to be a renamed or restructured tool, not just a newer version of the same tool. The migration note in breaking_changes should explain how to translate calls. Splitting one tool into several or merging several into one are both valid replacement patterns.

Q: What about preview features inside an otherwise GA tool?

Mark the tool itself as ga and mark the specific preview parameters in the manifest with a preview: true flag and an inline note. When the preview parameter is removed or stabilized, treat that as a MINOR bump if it stays additive, MAJOR if shape changes.

Q: Does this spec require a registry?

No. It applies whether the manifest lives in a registry, in a Git repo, or in a single distributed file. Registries enforce uniqueness centrally; out-of-registry deployments must enforce uniqueness through deployment process and Git tags.