Tool Contract Breaking Change Detection Prompt

This prompt is designed for platform engineers and integration developers who own the contract between AI agents and external tools. The core job-to-be-done is comparing two versions of a tool schema—whether OpenAPI, MCP, JSON Schema, or a custom contract—and producing a structured change impact report. The report must classify every difference by severity, assign a migration urgency score, and provide explicit guidance on what agent code, prompts, or tool configurations must be updated to prevent silent failures. Use this prompt before deploying a new tool version, as a gate in your CI/CD pipeline during contract verification, or when auditing a tool registry for compatibility risks across multiple agents.

Do not use this prompt for runtime tool selection or for generating new schemas from scratch. It assumes two complete, valid schemas as input and focuses exclusively on detecting breaking changes between them. The prompt is not a substitute for schema validation, and it will not catch semantic drift where a tool's behavior changes without a corresponding schema change. For runtime scenarios, pair this with a tool output contract validation prompt. For schema creation, use the Tool Contract Schema Definition Prompt Template instead. The ideal user has access to both schema versions, understands the agent's dependency on the tool, and needs a structured report that can feed directly into a migration checklist or automated compatibility gate.

Before running this prompt, ensure both schemas are normalized to the same format. If you are comparing an OpenAPI spec to an MCP tool definition, run the OpenAPI-to-MCP Schema Translation Prompt first. The prompt expects square-bracket placeholders for [OLD_SCHEMA] and [NEW_SCHEMA], and optionally [AGENT_CONTEXT] describing how the agent uses the tool. The output is a structured JSON report with fields for change type, severity, affected agent paths, and migration urgency. In high-risk environments—such as financial transactions, healthcare data, or security-sensitive operations—always route the report through human review before deploying. The prompt identifies what broke; a human must decide whether the break is acceptable and what the migration window should be.

Common failure modes include false positives when a field is renamed but semantically equivalent, and false negatives when a new required field is added inside a nested object that the prompt's diff logic does not fully traverse. To mitigate this, include [AGENT_CONTEXT] that specifies which fields the agent actually uses, so the prompt can prioritize changes that impact real agent paths rather than flagging every schema delta. After receiving the report, validate the top three highest-severity findings against your agent's actual tool-call logs before initiating any migration work. The next step is to feed the report into your change management process: update agent prompts that reference deprecated fields, adjust argument coercion rules, and schedule a canary deployment that monitors tool-call error rates against the new schema version.

This prompt template is designed to compare two versions of a tool contract schema—typically a JSON Schema, OpenAPI fragment, or MCP tool definition—and produce a structured change impact report. The report identifies field removals, type changes, new required fields, enum value deprecations, and other breaking modifications. It also assigns a severity classification and a migration urgency score to each finding. Replace every square-bracket placeholder with your actual schemas, risk tolerance, and output format requirements before sending the prompt to the model.

textCopy
You are a tool contract auditor. Your task is to compare two versions of a tool schema and identify every breaking change that could cause an agent or integration to fail.

## INPUTS

### Previous Schema (Version A)
[PREVIOUS_SCHEMA]

### Current Schema (Version B)
[CURRENT_SCHEMA]

### Tool Name
[TOOL_NAME]

### Additional Context
[CONTEXT]  // e.g., "This tool is used in a financial audit pipeline. Downtime requires Sev-2 escalation."

## DEFINITION OF BREAKING CHANGE
A change is breaking if an agent or client built against Version A could fail, produce incorrect results, or silently drop data when interacting with Version B. Include:
- Field removal (required or optional)
- Type change (e.g., string to integer, object to array)
- New required field added without a default
- Enum value removal or renaming
- Output shape change (removed response fields, changed response types)
- Constraint tightening (e.g., maxLength reduced, new pattern enforced)
- Semantic change (same field name, different meaning or unit)
- Endpoint or operation removal
- Authentication or authorization requirement change

## OUTPUT SCHEMA
Return a single JSON object with this exact structure:
[OUTPUT_SCHEMA]

## CONSTRAINTS
[CONSTRAINTS]  // e.g., "Do not flag cosmetic changes like description text updates. Only flag changes that affect runtime behavior."

## SEVERITY CLASSIFICATION
- **CRITICAL**: Agent will crash, hang, or produce incorrect results with no workaround.
- **HIGH**: Agent will fail on specific inputs or edge cases; workaround possible but fragile.
- **MEDIUM**: Agent behavior changes but does not break; may require code updates.
- **LOW**: Backward-compatible but warrants attention (e.g., new optional field that agents should adopt).

## MIGRATION URGENCY SCORING (1-10)
- 9-10: Deploy immediately; production is or will break.
- 7-8: Deploy within current sprint; risk is imminent.
- 4-6: Plan migration; breaking under specific conditions.
- 1-3: Nice-to-have; no immediate risk.

## INSTRUCTIONS
1. Parse both schemas completely.
2. Identify every difference between Version A and Version B.
3. Classify each difference as breaking or non-breaking per the definition above.
4. For each breaking change, assign a severity and migration urgency score with a one-sentence rationale.
5. Group findings by affected component (arguments, outputs, error responses, operations).
6. Include a summary section with total breaking changes, highest severity, and recommended migration window.
7. If no breaking changes are found, explicitly state that and explain why.
8. Return ONLY the JSON object. No markdown fences, no commentary outside the JSON.

Adaptation guidance: Replace [PREVIOUS_SCHEMA] and [CURRENT_SCHEMA] with the actual JSON Schema, OpenAPI fragment, or MCP tool definition for each version. The [OUTPUT_SCHEMA] placeholder should contain your desired JSON structure—define it precisely so the model returns parseable output every time. Use [CONSTRAINTS] to exclude known false positives, such as internal-only fields or documentation changes that your team has already reviewed. The [CONTEXT] field is optional but valuable for calibrating urgency scores to your operational reality. If your tool ecosystem uses a different severity taxonomy, replace the four-level classification with your own. For high-risk domains such as payments, healthcare, or auth, add a [RISK_LEVEL] field and instruct the model to escalate urgency scores accordingly.

What to do next: After copying this template, wire it into a CI pipeline that runs on every schema change PR. Pair it with the Tool Contract Validation Prompt to verify that the model's output JSON conforms to your [OUTPUT_SCHEMA] before surfacing findings. For production-critical tools, route CRITICAL and HIGH findings to a human review queue before merging. Avoid running this prompt on schemas larger than your model's context window without chunking; split large contracts by operation or component and merge results in application code.

This prompt is designed to operate as a gating step in a schema evolution pipeline, not as a one-off analysis tool. The implementation harness should invoke the prompt whenever a tool's OpenAPI spec, MCP server manifest, or gRPC protobuf definition changes in version control. The prompt compares two schema versions—[OLD_SCHEMA] and [NEW_SCHEMA]—and produces a structured change impact report. The harness must supply both schemas in a normalized format (preferably JSON Schema or OpenAPI 3.x) to avoid the model hallucinating field names or types from inconsistent serializations. If your tool registry stores schemas in multiple formats, add a normalization step before prompt invocation to convert everything to a canonical representation.

The harness should enforce a strict output contract. After the model returns the change impact report, validate that the JSON output contains all required fields: breaking_changes (array of objects with field_path, change_type, severity, migration_note), non_breaking_changes, new_required_fields, deprecated_enum_values, and migration_urgency_score. Use a JSON Schema validator in your application code—do not rely on the model to self-correct without verification. If validation fails, retry once with the validation errors injected into [CONSTRAINTS] as explicit repair instructions. If the second attempt also fails, log the failure, flag the schema change for manual review, and block the merge or deployment. For high-risk tools (those handling payments, PII, or irreversible operations), always require human approval on any detected breaking change with severity high or critical, regardless of validation success.

Model choice matters here. Use a model with strong structured output capabilities and a large context window, as some enterprise API specs exceed 20K tokens. GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are suitable defaults. Enable structured output mode (JSON mode or function calling with a strict schema) rather than relying on prompt-level formatting instructions alone. For cost control, cache the [OLD_SCHEMA] across multiple comparisons by storing it in a prompt cache or using a model that supports prefix caching. Wire the harness into your CI system (GitHub Actions, GitLab CI, Jenkins) so that every PR touching a tool schema file triggers the check. Post the change impact report as a PR comment and attach the full JSON payload as a CI artifact for audit trails. Do not auto-merge PRs that introduce breaking changes unless the migration urgency score is below a configurable threshold and the changes are explicitly allowlisted by the platform team.