Tool Call Version Tracking Prompt for Schema Changes

API platform teams managing tool schema evolution face a hard problem: when a tool definition changes, existing AI workflows may silently break because the model calls a tool with arguments that no longer match the current schema. This prompt solves that by annotating every tool call with the exact tool definition version used, detecting whether the call was made against a deprecated, drifted, or current schema. Use it inside your tool-call pipeline before execution to generate a versioned audit record that supports regression testing, migration monitoring, and safe schema deprecation.

This is not a prompt for selecting tools or constructing arguments. It assumes a tool has already been selected and arguments have been filled. Its job is to add version metadata so that downstream systems can decide whether to execute, warn, or block the call. The prompt requires the current tool schema, the tool name, the filled arguments, and a version registry mapping tool names to their active and deprecated versions. Without this context, the prompt cannot accurately detect schema drift or deprecation.

Do not use this prompt when you need to choose which tool to call, validate argument types against a schema, or explain why a tool was selected. Those are separate concerns handled by tool selection, argument validation, and decision explanation prompts. This prompt is also inappropriate for real-time latency-sensitive paths where the added metadata step introduces unacceptable delay—consider caching version mappings in application code instead. For high-risk or regulated environments, always pair this prompt's output with a human-in-the-loop approval gate before executing a call flagged as deprecated or drifted.

This prompt runs as a pre-execution annotation step inside your tool call pipeline. It receives the model's intended tool call and the current tool definition, then outputs a structured annotation that records the schema version used, detects whether the call was made against a deprecated or drifted definition, and flags any argument mismatches. The annotation is designed to be logged alongside the tool call for downstream audit, regression testing, and migration tracking—not shown to end users.

textCopy
You are a tool call schema auditor. Your job is to annotate a proposed tool call with version metadata and drift detection before execution.

## INPUT
- Tool Call: [TOOL_CALL_JSON]
- Current Tool Definition: [CURRENT_TOOL_DEFINITION]
- Deprecated Tool Definitions (if any): [DEPRECATED_DEFINITIONS]
- Migration Map: [MIGRATION_MAP]

## TASK
1. Extract the tool name and arguments from the tool call.
2. Identify which version of the tool definition the call appears to target by comparing argument shapes against the current and deprecated definitions.
3. Detect schema drift: flag any arguments present in the call that do not exist in the current definition, any required arguments that are missing, and any type mismatches.
4. If the call matches a deprecated definition, check the migration map for a recommended replacement and note it.
5. Output a structured annotation following the output schema exactly.

## OUTPUT SCHEMA
```json
{
  "tool_name": "string",
  "called_arguments": {},
  "matched_definition_version": "string | null",
  "matched_definition_status": "current | deprecated | unknown",
  "drift_detected": true | false,
  "drift_details": [
    {
      "field": "string",
      "issue": "missing_required | unexpected_field | type_mismatch | deprecated_field",
      "expected": "string",
      "actual": "string"
    }
  ],
  "migration_recommendation": "string | null",
  "annotation_timestamp": "ISO8601",
  "confidence": "high | medium | low"
}

CONSTRAINTS

• Do not modify the tool call. Only annotate it.
• If the tool name is not recognized in any provided definition, set matched_definition_version to null and matched_definition_status to "unknown".
• If multiple deprecated versions could match, select the most recent one by version number.
• Set confidence to "low" if the tool call is ambiguous between two definitions.
• Never invent migration recommendations. Only use the provided migration map.
• If no drift is detected, drift_details must be an empty array.

EXAMPLES

[EXAMPLES]

Replace each square-bracket placeholder before sending this prompt to the model. [TOOL_CALL_JSON] must contain the raw tool call object the model produced, including the function name and arguments. [CURRENT_TOOL_DEFINITION] should be the live tool schema from your API specification or function registry, including parameter types, required fields, and the version identifier. [DEPRECATED_DEFINITIONS] is an array of previous tool schemas that are still in circulation but no longer the canonical version—include these only if you maintain a version history. [MIGRATION_MAP] is a mapping from deprecated tool versions to their recommended replacements, such as {"v1_search": "v2_search", "v1_lookup": "v2_lookup"}. The [EXAMPLES] placeholder should contain two to three few-shot examples showing correct annotations for current, deprecated, and drifted calls. If you lack a migration map, pass an empty object and the prompt will leave migration_recommendation as null. Always validate the output against the JSON schema before logging it, and route any annotation with drift_detected: true or confidence: low to a human review queue in production.

This prompt is designed to operate as a pre-execution middleware step in a tool-call pipeline. Before a tool call is dispatched to the execution layer, the model receives the selected tool name, the constructed arguments, and the current tool definition. The prompt's job is to annotate the call with version metadata and detect schema drift—not to execute the tool or modify the arguments. This separation keeps version tracking orthogonal to business logic, making it easy to add or remove without touching the core tool execution path.

Wire the prompt into your application by intercepting the tool call object after argument construction but before dispatch. Pass the following inputs: [TOOL_CALL] (the full tool call object with name and arguments), [TOOL_DEFINITION] (the current schema for that tool, including its version field), and [DEPRECATED_VERSIONS] (a list of known deprecated schema versions with deprecation dates and migration notes). The model should return a structured annotation containing the tool_version_used, a schema_drift_detected boolean, and a drift_details object if drift is found. Validate the output against a strict schema before logging or storing it—reject any annotation that doesn't include a version string or that claims no drift when the tool definition version doesn't match the call's expected schema shape.

For production deployment, implement a retry-and-log pattern. If the model fails to produce valid JSON or the annotation schema validation fails, retry once with the same inputs and a stricter instruction to return only the specified fields. If the second attempt fails, log the raw model output alongside the tool call for manual review and allow the tool call to proceed with a version_unknown flag. Never block tool execution on annotation failure—this prompt is an observability sidecar, not a gate. Store annotations in a dedicated tool_call_versions table or append them to your existing audit log, indexed by tool name and timestamp. This enables downstream queries for regression testing (e.g., "show all calls made against deprecated schema v2.1 after the migration cutoff") and migration monitoring dashboards.

Choose a model that reliably follows strict JSON schemas for this task. GPT-4o and Claude 3.5 Sonnet perform well on structured annotation with low hallucination rates. Avoid smaller or older models that may invent version numbers or miss subtle schema drift signals. If your tool definitions are large, consider passing only the version field and a hash of the full schema rather than the entire definition to save tokens—but ensure the hash is computed deterministically so drift detection remains accurate. For high-compliance environments, add a human review step when schema_drift_detected is true and the tool call is a write operation, ensuring that deprecated schema usage is acknowledged before side effects occur.