Breaking Change Impact Analysis Prompt for Tool Providers

Use this prompt when your platform team is preparing to roll out a breaking change to a tool's API, schema, or behavior and you need to understand the blast radius across all registered agent consumers. The core job-to-be-done is producing a structured, per-consumer impact assessment that answers three questions: which agent-tool bindings will break immediately, which will adapt automatically (e.g., via version negotiation or fallback logic), and which require immediate migration work from the consuming team. This is a pre-release planning exercise, not a post-mortem. Run this assessment before cutting a release candidate so you can communicate impact, schedule migrations, and avoid production incidents where agents start failing silently against the new version.

The prompt requires two concrete inputs: a breaking change specification that describes exactly what is changing (deprecated endpoints, removed fields, type changes, behavioral differences) and a consumer registry that lists every registered agent, its bound tool versions, its declared adaptation capabilities, and its owner contact. Without both inputs, the assessment will be incomplete. The prompt is designed to produce a structured JSON output with per-consumer severity scores, adaptation classifications (e.g., BREAKING, ADAPTABLE, UNAFFECTED), and a completeness verification that confirms every consumer in the registry was assessed. This output feeds directly into your release communication workflow, migration tracking system, or automated notification pipeline.

Do not use this prompt for runtime version resolution during live agent execution—that requires a different prompt focused on real-time version negotiation and fallback selection. Do not use it when you lack a complete consumer registry, as the completeness check will flag missing entries but cannot fabricate them. This prompt also assumes the breaking change is already well-specified; if you are still discovering what changed between versions, use a schema evolution diff analysis prompt first. Finally, this prompt is not a substitute for human judgment on migration timelines or business priority—it provides the technical impact classification, but the decision to delay a release, grant an extension, or force an immediate migration belongs to the platform team's governance process.

The following prompt template is designed to be wired into your orchestration layer. It accepts a change specification and a consumer registry, then produces a structured impact assessment. The template uses square-bracket placeholders for all dynamic inputs, making it safe to paste directly into your prompt management system, CI/CD pipeline, or agent gateway. Before using it, ensure your consumer registry is complete and your change spec includes the old and new tool schemas, the deprecation window, and any migration guidance you intend to publish.

textCopy
You are a platform reliability engineer analyzing a breaking change to a tool used by multiple registered agent consumers. Your task is to produce a structured impact assessment that identifies which agent-tool bindings will break, which will adapt automatically, and what the migration urgency is for each consumer.

## INPUTS

### Change Specification
[CHANGE_SPEC]

### Consumer Registry
[CONSUMER_REGISTRY]

### Output Schema
[OUTPUT_SCHEMA]

### Risk Tolerance
[RISK_LEVEL]

## INSTRUCTIONS

1. Parse the change specification to identify all breaking, behavioral, and cosmetic changes between the old and new tool versions.
2. For each consumer in the registry, analyze its declared tool bindings, version constraints, and usage patterns against the change specification.
3. Classify each consumer's impact as one of: `BREAKING` (hard incompatibility requiring immediate migration), `ADAPTIVE` (automatic adaptation possible with field mapping or version negotiation), `BEHAVIORAL` (output changes that may affect downstream logic), or `NONE` (no impact detected).
4. For each BREAKING classification, identify the specific fields, endpoints, or behaviors that cause the break.
5. For each ADAPTIVE classification, describe the adaptation path and any residual risk.
6. Assign a migration urgency score (1-5) for each affected consumer based on the deprecation window, usage criticality, and break severity.
7. Flag any consumers that appear to use deprecated features indirectly through transitive dependencies or shared schemas.
8. If the risk tolerance is HIGH, include a human-review flag for any consumer where the impact classification confidence is below 90%.

## CONSTRAINTS

- Do not assume consumers have updated their bindings unless the registry explicitly indicates it.
- Treat silent contract changes (same field name, different semantics) as BREAKING unless proven otherwise.
- If a consumer's usage pattern is ambiguous, classify conservatively and flag for human review.
- Do not fabricate consumer data. Only analyze consumers present in the registry.
- If the change specification is incomplete, list the missing information needed to complete the analysis rather than guessing.

## OUTPUT

Return a valid JSON object conforming to the provided output schema. Include a `warnings` array for any analysis limitations, missing data, or low-confidence classifications.

To adapt this template, replace each square-bracket placeholder with the corresponding value from your system. [CHANGE_SPEC] should contain the full diff between tool versions, including schema changes, deprecated endpoints, and sunset dates. [CONSUMER_REGISTRY] should be a structured list of all registered agents with their tool bindings, version pins, and usage metadata. [OUTPUT_SCHEMA] defines the exact JSON shape you expect—use a strict schema with required fields for consumer_id, impact_classification, breaking_details, migration_urgency, and human_review_required. [RISK_LEVEL] should be set to HIGH for production-critical tools or regulated environments. After pasting, validate that the model's output conforms to your schema before allowing it to drive automated migration tickets or consumer notifications. For high-risk deployments, route all BREAKING classifications with urgency 4 or 5 to a human reviewer before actioning.

This prompt is designed to operate as a batch analysis step inside a tool platform's release pipeline, not as a real-time agent call. The primary integration point is a CI/CD or release management workflow that triggers when a tool schema version bump is proposed. The harness must supply the prompt with a complete consumer registry—a structured list of every agent, workflow, or service registered as a consumer of the tool being changed—along with the old and new tool schemas. Without a complete registry, the analysis will silently miss affected consumers, which is the most dangerous failure mode for this workflow.

Input assembly requires three data sources: (1) the current tool schema (OpenAPI, JSON Schema, or MCP tool definition), (2) the proposed new schema, and (3) a consumer registry export containing per-consumer records with at minimum consumer_id, tool_binding (which endpoints or functions are called), call_patterns (argument usage, frequency), and last_validated_version. The harness should validate that every consumer record includes a non-null tool_binding before passing it to the prompt—empty bindings produce false negatives. For large registries exceeding context windows, partition consumers by endpoint affinity and run parallel analyses, then merge results with a deduplication step.

Output validation is critical because the prompt produces structured impact classifications. The harness must parse the JSON output and run three checks before accepting results: (1) every consumer in the input registry must appear in the output with a non-null impact_level—missing consumers indicate a model truncation or attention failure and require a retry with that consumer isolated, (2) any consumer classified as NO_IMPACT must have zero breaking changes listed in its breaking_details array—mismatches indicate hallucinated or contradictory classifications, and (3) consumers flagged as BREAKING must include at least one specific schema change reference (field name, type change, or removed endpoint) in their breaking_details. Failures on any check should trigger a retry with the failing consumer subset and a stricter output schema constraint.

Human review gates are mandatory before the analysis drives any migration timeline or consumer notification. The harness should route all BREAKING and ADAPTATION_REQUIRED classifications to a review queue where platform engineers confirm the impact assessment against their own knowledge of consumer behavior. The prompt's confidence field per consumer is a routing signal: low-confidence breaking classifications should be reviewed first. The harness should also compare results against the previous version's impact analysis to detect regressions—a consumer that was previously NO_IMPACT but is now BREAKING without a corresponding schema change in its bound endpoints indicates either a registry staleness problem or a model error. Log every analysis run with the full input registry, output JSON, validation results, and reviewer decisions for audit trails and future prompt regression testing.