Versioning guide

Detect breaking changes in agent tool contracts

Classify required fields, enums, unions, side effects, and output changes before an agent tool deployment breaks callers.

Structural breaking changesBehavioral description diffSide-effect annotationsProvider compile matrix

Reviewed 29 August 2026Source: MCP 2026 release candidate

Traditional API diffs miss model-facing behavior. Renaming a description cue, widening an enum, or changing side-effect expectations can alter tool selection even when validation still passes.

Read the schema and its provider wrapper as one contract. APITC distinguishes target requirements from portable JSON Schema, applies mechanical repairs only when intent is recoverable, and identifies transformations that can change meaning.

Diagnostic procedure

Repair the schema, then recompile.

01
Diff canonical intent
Compare names, descriptions, optionality, enum meaning, input shapes, output shapes, and annotations.
02
Compile every supported target
A source-compatible edit can exceed one provider’s schema subset or complexity budget.
03
Classify deployment risk
Separate validation breaks, caller-adapter breaks, and model-routing behavior changes.

Before

status enum: ["open", "closed"]

Target-safe shape

Adding "all" may be schema-compatible but changes routing and result size; review as behavioral risk.

Interactive check

Run the schema against a real target.

Paste JSON, choose a target, and inspect the compiled shape and every portability warning before copying the result.

01 / Base specification

02 / Candidate specification

03 / Compatibility ledgerJSON · OpenAPI 3.x

4: breaking
0: risky
2: additive

breakingGET /orders/{id}

Operation removed

additiveGET /orders/search

Operation added

breakingGET /orders › query.region

Required parameter added

breakingcomponents.schemas.Order.currency

Property became required

breakingcomponents.schemas.Order.status.enum

Allowed enum values narrowed

additivecomponents.schemas.Order.currency

Property added

No account · no upload · no endpoint calledOpen the full openapi impact diff and operating notes →

FAQ

Before you ship

Does APITC upload my schema?

No. Parsing, diagnostics, and compilation run in your browser tab.

Is the compiled result guaranteed to preserve meaning?

Safe repairs are deterministic. When the target provider cannot express a source constraint, APITC labels the transform as lossy instead of hiding it.

Protocol behavior checked against the MCP 2026 release candidate. Recheck your pinned provider/API version before production deployment.

Repair the schema, then recompile.

Diff canonical intent

Compile every supported target

Classify deployment risk

Run the schema against a real target.

Before you ship