Runtime Tool Schema Change Detection Prompt

Use this prompt when you operate agent systems in production where external tools, APIs, or MCP servers can change their response schemas independently of your deployment cycle. The primary job-to-be-done is detecting structural differences between the schema your agent expects and the schema a live tool actually returns, before those mismatches cause silent parsing failures, hallucinated field values, or cascading errors in multi-step workflows. The ideal user is an agent infrastructure developer, platform reliability engineer, or AI operations engineer responsible for tool contract stability across a fleet of agent instances. You need this prompt when your tool ecosystem includes third-party endpoints, internally maintained services with independent release cadences, or MCP servers that can be updated by other teams without coordinated agent redeployment.

The prompt requires a registered schema (the contract your agent code or validation layer expects) and a current schema (extracted from live tool responses or introspection). It compares them across breaking dimensions—removed required fields, changed types, narrowed enums, deleted endpoints—and non-breaking dimensions such as added optional fields or widened constraints. The output is a structured change report with impact assessments for each dependent agent workflow. You should wire this into a scheduled job or a webhook triggered by tool health checks, not run it as a one-off manual review. For high-risk production systems, pair the detection output with an automated alert that quarantines affected agent instances until a human operator acknowledges the change or a migration path is applied.

Do not use this prompt as a substitute for proper API versioning, contract testing in CI/CD, or server-side schema governance. It detects changes after they occur in the live environment; it does not prevent them. If your tool providers publish formal changelogs, deprecation schedules, or versioned endpoints, prefer consuming those signals directly. This prompt is also insufficient when the schema change is semantic rather than structural—for example, a field that keeps the same name and type but changes its business meaning. In regulated or safety-critical domains, always require human review of detected changes before allowing agent workflows to continue, and maintain an audit trail of every schema change detection event, operator decision, and remediation action.

This template is designed to be dropped into an agent infrastructure monitoring pipeline. It compares a freshly observed tool response schema against the registered, expected schema and produces a structured impact assessment. The prompt is schema-agnostic and works across JSON Schema, OpenAPI fragments, or custom type systems as long as both inputs are provided in a consistent format. Use it as the core of a scheduled diff job, a pre-commit hook for tool registry updates, or a runtime guard that fires before dependent agent workflows execute.

textCopy
You are a tool schema change detector for production agent infrastructure. Your job is to compare the current observed response schema of a tool against its registered expected schema and produce a structured impact assessment.

## INPUTS

**Registered Schema (expected):**
[REGISTERED_SCHEMA]

**Observed Schema (current):**
[OBSERVED_SCHEMA]

**Tool Name:** [TOOL_NAME]
**Tool Version:** [TOOL_VERSION]
**Dependent Agent Workflows:** [DEPENDENT_WORKFLOWS]

## INSTRUCTIONS

1. Parse both schemas as structured type definitions. Normalize field ordering, whitespace, and formatting before comparison.
2. Identify all differences between the registered and observed schemas. Classify each difference as one of:
   - **BREAKING**: A change that will cause existing agent workflows to fail, produce incorrect results, or violate output contracts. Examples: removed required fields, changed field types, narrowed enum values, removed response properties, changed array item types.
   - **NON-BREAKING**: A change that is backward-compatible. Examples: added optional fields, widened enum values, added response properties, loosened constraints, added default values.
   - **UNCERTAIN**: A change whose impact cannot be determined without additional context about how dependent workflows consume the field. Flag for human review.
3. For each breaking change, describe the specific impact on the dependent agent workflows listed in [DEPENDENT_WORKFLOWS]. If no dependent workflows are provided, describe the general risk.
4. For each non-breaking change, note whether it introduces new capabilities that dependent workflows could optionally adopt.
5. Assign an overall severity level: **CRITICAL** (workflows will fail), **HIGH** (workflows may produce incorrect results), **MEDIUM** (workflows may degrade gracefully), **LOW** (cosmetic or additive only), **NONE** (schemas are identical).

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "tool_name": "string",
  "tool_version": "string",
  "comparison_timestamp": "string (ISO 8601)",
  "schemas_identical": boolean,
  "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "NONE",
  "changes": [
    {
      "field_path": "string (dot-notation path to the changed field)",
      "change_type": "BREAKING" | "NON-BREAKING" | "UNCERTAIN",
      "registered_value": "string (summary of expected)",
      "observed_value": "string (summary of current)",
      "description": "string (human-readable explanation of the change)",
      "impact_on_workflows": ["string (specific impact per dependent workflow)"],
      "recommended_action": "string (migration step, rollback instruction, or review request)"
    }
  ],
  "summary": "string (one-paragraph executive summary of all changes and recommended response)",
  "requires_human_review": boolean
}

## CONSTRAINTS

- Do not hallucinate changes. If the schemas are identical, return schemas_identical: true with an empty changes array and severity NONE.
- If either schema is malformed or unparseable, return a single change entry with change_type UNCERTAIN, severity HIGH, and requires_human_review: true. Include the parse error in the description.
- Field paths must use dot notation (e.g., "response.body.items.id.type").
- If [DEPENDENT_WORKFLOWS] is empty, set impact_on_workflows to ["No dependent workflows specified"].
- Do not suggest automatic migration for BREAKING changes. Require human review.

To adapt this template, replace the square-bracket placeholders with data from your tool registry and runtime introspection system. The [REGISTERED_SCHEMA] and [OBSERVED_SCHEMA] inputs should be serialized JSON Schema or an equivalent structured type definition. If your tool ecosystem uses OpenAPI, extract the response schema from the relevant endpoint's responses block. For MCP servers, pull the output schema from the tool's capability manifest. The [DEPENDENT_WORKFLOWS] field is critical for impact assessment—populate it from your agent workflow registry so the model can trace breaking changes to specific downstream failures. If you run this prompt in a CI/CD pipeline or pre-deployment gate, cache the registered schema as a build artifact and compare against live introspection results. Always route CRITICAL and HIGH severity outputs to a human review queue before allowing dependent workflows to execute against the changed tool.

This prompt is designed to be called by an automated monitoring job, not a human chat interface. It should be triggered whenever a tool's response schema is observed to differ from its registered contract, typically by a middleware layer that intercepts tool call results or by a periodic schema reconciliation cron job. The harness must provide the prompt with the registered schema, the observed schema, and the tool's dependency graph so the model can assess impact, not just detect a diff.

The implementation should wrap the LLM call in a validation layer that parses the expected JSON output and checks for required fields: change_type, breaking, impacted_workflows, and recommended_action. If the output fails to parse or is missing a required field, the harness should retry once with a stricter prompt variant that includes the parse error. All outputs, including raw model responses and parse failures, must be logged to your observability stack with the tool name, schema version, and a unique detection event ID. For high-severity breaking changes, the harness should automatically create an incident ticket and notify the owning team rather than relying on a human to read a dashboard.

Model choice matters here. Use a model with strong structured output support and a large context window, as production tool schemas can be verbose. Enable JSON mode or structured outputs if your provider supports it, and set a low temperature (0.0–0.1) to maximize deterministic comparisons. The prompt's [DEPENDENCY_GRAPH] input should be generated programmatically from your agent registry or workflow definitions—do not ask a human to write it. If the dependency graph is unavailable, the harness should substitute an empty graph and flag the detection result as lower confidence, preventing false alarms about impact on unknown workflows.