Tool Call Output Contract Violation Retry Prompt Template

This playbook addresses a specific and dangerous failure mode in agent systems: the tool call executed without error, but the response body violates the expected output contract. This is distinct from a tool call that fails with an error code or a malformed request. Here, the tool returned a 200 OK, but the JSON structure, field types, or required fields do not match the schema your downstream code expects. Use this prompt when your validator rejects a tool response and you need the model to adjust its arguments to elicit a conformant response, or to escalate when the tool itself appears broken.

Before using this prompt, you must have a validated output schema for the tool in question and a concrete list of violations produced by your validator. The prompt is designed to be injected into a retry loop where the model receives the original arguments, the invalid response, and the specific schema violations. It is not a general-purpose repair prompt for malformed JSON—it assumes the tool call itself was well-formed but the tool's response broke the contract. This prompt is most effective when your harness already distinguishes between transport-layer errors (4xx, 5xx, timeouts) and application-layer contract violations (schema mismatches, missing fields, type errors).

Do not use this prompt when the tool is returning consistent, well-formed errors that indicate a permanent failure (e.g., 'resource not found' with a valid error schema). In those cases, the tool is working correctly, and retrying with adjusted arguments is wasteful. Also avoid this prompt when you lack a machine-readable output schema—without one, the model cannot reliably distinguish between a valid response and a contract violation. If the tool's output schema is undocumented or unstable, invest in schema extraction or tool replacement before building retry logic around it.

This prompt template is designed for the retry step in an agent harness after a tool call has returned a successful HTTP status but the response body fails validation against the expected output contract. The prompt instructs the model to analyze the violation, adjust the original tool call arguments to elicit a conformant response, and either produce a corrected call or escalate if the tool itself appears broken. Replace every square-bracket placeholder with runtime values before sending the prompt to the model.

textCopy
SYSTEM: You are an agent recovery assistant. Your job is to correct tool call arguments when a tool returned a response that violates the expected output schema.

CONTEXT:
- Original user intent: [USER_INTENT]
- Tool called: [TOOL_NAME]
- Original arguments: [ORIGINAL_ARGUMENTS]
- Expected output schema: [OUTPUT_SCHEMA]
- Actual tool response: [ACTUAL_RESPONSE]
- Validation errors: [VALIDATION_ERRORS]

INSTRUCTIONS:
1. Analyze the validation errors against the expected output schema.
2. Determine whether the violation is likely caused by incorrect arguments or by a broken tool.
3. If incorrect arguments: produce a corrected set of arguments designed to elicit a schema-conformant response. Explain which arguments changed and why.
4. If the tool appears broken (e.g., returns HTML instead of JSON, missing entire required sections, or returns data that cannot be coerced to the schema regardless of arguments): set escalation_required to true and provide a clear explanation.
5. If you are uncertain, prefer escalation.

OUTPUT FORMAT:
{
  "analysis": "string explaining the likely cause of the violation",
  "escalation_required": boolean,
  "corrected_arguments": { /* adjusted arguments object, or null if escalating */ },
  "argument_changes": [
    {
      "parameter": "string",
      "original_value": "any",
      "new_value": "any",
      "reason": "string"
    }
  ],
  "escalation_reason": "string or null"
}

CONSTRAINTS:
- Do not invent arguments not present in the original call unless required by the schema.
- Preserve the user's original intent. Do not change what the user asked for.
- If the tool response contains partial valid data, note it in the analysis.
- [ADDITIONAL_CONSTRAINTS]

To adapt this template, populate the placeholders from your harness state. [OUTPUT_SCHEMA] should be the exact JSON Schema or type definition the tool response must satisfy. [VALIDATION_ERRORS] should be the raw error messages from your validator, not a summary. For high-risk domains such as finance or healthcare, add a human review gate before resubmitting corrected arguments. Wire the model's JSON output into a structured parser that checks escalation_required before retrying the tool call. If the model escalates, route to a human operator with the full failure context. If the model produces corrected arguments, validate them against the tool's input schema before retrying.

The output contract violation retry prompt is not a standalone fix—it is a recovery step inside a structured agent harness. The harness must detect the violation, prepare the retry context, invoke the prompt, validate the corrected arguments, and decide whether to re-execute the tool or escalate. This section covers the harness components you need before and after the prompt fires, with concrete validation checks, retry budget logic, and escalation triggers.

Start with a post-execution validator that inspects the tool's response against the expected output schema. The validator should check for missing required fields, type mismatches, enum violations, and structural non-conformance at the specific JSONPath where the violation occurred. Capture the exact validation error message, the violating field path, and the received value. If the response passes validation, skip the retry prompt entirely—only invoke it when a contract violation is confirmed. Log the violation details, the tool name, the original arguments, and the attempt count before calling the retry prompt.

The harness must inject three pieces of context into the retry prompt: the original tool call arguments that produced the bad response, the expected output schema for the tool's return value, and the specific violation details including the field path and the validation error message. Do not send the full tool response unless it is small and relevant—sending large payloads wastes tokens and can distract the model. Instead, extract the violating portion and include it alongside the schema snippet for that subtree. This keeps the prompt focused on the repair task rather than overwhelming the model with conformant data.

Wrap the retry prompt in a retry budget controller. Define a maximum number of output-contract retries per tool call—typically 2 or 3 before escalating. Track the attempt count per tool invocation, not globally, so a single bad tool doesn't consume the budget for unrelated calls. After each retry, validate the new arguments before re-executing the tool. If the model produces arguments that still fail validation, increment the counter and retry with the updated violation feedback. If the model produces the same invalid arguments twice, break the loop immediately—the model is stuck and further retries will waste resources.

When the retry budget is exhausted, the harness must escalate, not loop. Format an escalation payload that includes the original user intent, the tool name, all attempted argument sets, the validation errors for each attempt, and the final tool response if one exists. Route this to a human review queue, a fallback model, or a degraded-response path depending on your system's reliability requirements. Never silently drop the failure—output contract violations often indicate a tool that has changed its behavior, a schema that is out of date, or a model that fundamentally misunderstands the tool's contract. Each of these requires investigation beyond prompt-level recovery.