Agent Tool Output Validation and Retry Prompt

This prompt is designed for the specific failure mode where a tool call succeeds at the transport layer—returning an HTTP 200 status—but the response payload fails structural validation against the expected schema. This is a critical distinction: the tool executed, but its output is unusable by the downstream application logic. The job-to-be-done is to programmatically diagnose the mismatch between the expected schema and the actual output, then produce a corrected retry instruction with adjusted arguments or a different tool selection, all without losing the agent's original intent or restarting the entire agent loop. The ideal user is an AI reliability engineer or agent-framework builder integrating this prompt into a validation-and-retry harness within an autonomous or semi-autonomous agent workflow.

Concretely, you should route to this prompt when a post-tool-call validator raises specific error types: missing required fields, type mismatches (e.g., a string where an integer is expected), enum violations, or structural inconsistencies like a JSON array where an object is required. The harness should capture the raw tool output, the expected schema definition, and the exact validation error message as inputs to this prompt. The expected output is a structured diagnosis containing the identified mismatch and a corrected tool call payload. Do not use this prompt for errors that occur before tool execution, such as malformed function call arguments generated by the model. Those failures belong in a separate tool call argument recovery playbook. Similarly, do not use this prompt for infrastructure-level failures like HTTP 5xx errors, network timeouts, or authentication denials (HTTP 401/403). Those require infrastructure-level retry logic with exponential backoff and circuit breakers, not semantic output repair.

Before implementing this prompt, ensure your agent harness has a clear separation of concerns: a transport layer that handles network reliability, a tool call constructor that validates arguments before execution, and a post-execution validation layer that triggers this prompt. A common anti-pattern is routing all tool-related errors into a single catch-all retry block, which leads to inappropriate retries and wasted compute. Instead, classify the error at the harness level first. If the error is a schema validation failure on a successful response, use this prompt. If the retry budget for a specific tool call is exhausted, bypass this prompt and escalate to a human-in-the-loop or a fallback tool selection prompt. This prompt is a precision instrument for a narrow, high-frequency failure mode; using it outside these boundaries will produce unreliable results and complicate your agent's error-handling architecture.

This prompt is designed to be invoked inside an agent loop immediately after a tool output fails schema validation. Instead of discarding the failed output and retrying blindly, the prompt instructs the model to analyze the mismatch between the expected schema and the actual output, then produce a corrected tool call that preserves the original intent. Use it when your agent harness has a defined output schema per tool and a validator that can surface specific field-level errors.

textCopy
You are an agent tool-output validator and retry planner. Your job is to diagnose why a tool output failed validation and produce a corrected retry instruction.

## INPUT
- Original tool call: [ORIGINAL_TOOL_CALL]
- Expected output schema: [OUTPUT_SCHEMA]
- Actual tool output: [ACTUAL_OUTPUT]
- Validation errors: [VALIDATION_ERRORS]
- Agent goal context: [AGENT_GOAL]
- Retry budget remaining: [RETRY_BUDGET]

## CONSTRAINTS
- Do not change the agent's goal or intent.
- Only modify the tool call if the error is recoverable through argument or tool selection changes.
- If the error is unrecoverable (e.g., tool unavailable, auth failure, data missing), flag for escalation.
- Preserve all successfully validated fields from the original output.

## OUTPUT SCHEMA
Return a JSON object with these fields:
{
  "diagnosis": "string explaining what validation failed and why",
  "recoverable": true|false,
  "corrected_tool_call": {
    "tool_name": "string",
    "arguments": {}
  } | null,
  "escalation_reason": "string explaining why escalation is needed" | null,
  "retry_instruction": "string with the corrected call or escalation directive"
}

## INSTRUCTIONS
1. Compare [ACTUAL_OUTPUT] against [OUTPUT_SCHEMA] using [VALIDATION_ERRORS] as the specific failure points.
2. Classify each error: schema mismatch, missing required field, wrong type, enum violation, tool execution failure, or unrecoverable.
3. If recoverable, construct a corrected tool call that addresses the errors while preserving the original intent from [AGENT_GOAL].
4. If unrecoverable, set recoverable to false and provide a clear escalation reason.
5. If [RETRY_BUDGET] is 0, escalate regardless of recoverability.

Adaptation notes: Replace each square-bracket placeholder at runtime. [VALIDATION_ERRORS] should contain structured error details from your schema validator (e.g., field name, expected type, received value). [RETRY_BUDGET] is an integer; the prompt enforces escalation when it reaches zero. If your agent harness uses function-calling APIs, map corrected_tool_call directly into the next function call request. For high-risk domains, route the diagnosis and corrected_tool_call through a human review queue before re-execution. Always log the full prompt, output, and retry decision for observability and retry budget tracking.

The Agent Tool Output Validation and Retry Prompt is not a standalone fix; it is a recovery node inside a larger agent harness. The harness is responsible for catching a tool response, running it through a schema validator, and deciding whether to route the output forward or invoke this retry prompt. The prompt itself expects the original tool call, the raw tool output, the expected schema, and the validator error message as inputs. The harness must supply these cleanly—do not rely on the model to remember them from prior turns. Store the original tool call arguments and expected schema in harness-side state so they are available even if the agent context window has scrolled past the initial invocation.

A production-grade implementation wraps the retry prompt in a bounded loop with a configurable retry budget. For each retry attempt, the harness calls the model with the retry prompt, extracts the corrected tool call arguments from the structured output, re-executes the tool, and re-validates the result. If validation passes, the loop exits and the agent continues. If validation fails again, the harness increments a retry counter, appends the new validator error to the retry context, and re-invokes the retry prompt. The harness must track: retry_count, max_retries, last_error, and original_intent. Log every attempt with a correlation ID so operators can trace retry storms back to their root cause. When retry_count exceeds max_retries, the harness must not retry again—it must escalate.

Escalation means producing a structured failure record that a human or a higher-level recovery agent can consume. The failure record should include the original tool call, every retry attempt with its corrected arguments and validator error, and a flag indicating retry budget exhaustion. In semi-autonomous systems, this record is posted to a review queue. In fully autonomous pipelines, it may trigger a fallback tool, a degraded-mode response, or a plan-level re-anchoring prompt from the Agent Plan Deviation Recovery pillar. The key design rule: the retry prompt diagnoses and corrects; the harness enforces limits and decides what happens when correction fails. Never let the model control its own retry budget—that is a harness-side policy, not a language-model decision.