This playbook is for production engineers who need to repair malformed or invalid tool calls within an agent loop without aborting the entire execution. The core job-to-be-done is recovering from a schema validation failure on a function call generated by an LLM, where the system has a finite number of retry attempts before it must escalate or fail gracefully. The ideal user is an agent platform developer or backend engineer who already has a defined tool schema, a validation layer that produces specific error messages, and a retry budget (e.g., 3 attempts total). The required context includes the original user request, the conversation history, the invalid tool call JSON, the exact validation error, and the full tool schema. You should not use this prompt for initial tool call generation, for systems without a defined retry budget, or as a substitute for fixing a fundamentally broken system prompt that causes persistent tool call errors.

The prompt template embeds the remaining retry budget directly into the repair instruction, causing the model to shift its strategy based on how many attempts are left. On an early retry (e.g., attempt 1 of 3), the model is instructed to infer aggressively from conversation context and fix the issue with minimal changes. On a final attempt (e.g., attempt 3 of 3), the model is instructed to escalate conservatively—either by requesting human intervention, returning a safe default, or producing a structured error that the agent loop can handle without further retries. This prevents the common failure mode where a repair loop burns through all retries making the same type of mistake. The prompt requires the following placeholders: [INVALID_TOOL_CALL] for the malformed JSON, [VALIDATION_ERROR] for the specific schema violation message, [TOOL_SCHEMA] for the expected function definition, [CONVERSATION_CONTEXT] for the preceding turns, [RETRY_ATTEMPT] for the current attempt number, and [MAX_RETRIES] for the total budget.

Before implementing this prompt, ensure your agent framework can accurately track retry counts and inject them into the repair step. A common failure mode is a mismatch between the actual retry count in the orchestrator and the count passed to the prompt, which causes the model to use the wrong repair strategy. You should also implement structured logging that captures the repair attempt number, the model's chosen strategy (inferred vs. escalated), and whether the repaired call passed validation. This data is critical for tuning the retry budget and identifying whether the root cause is a prompt issue, a schema ambiguity, or a model capability gap. After reading this section, proceed to the prompt template to copy and adapt the repair instruction, then review the implementation harness for wiring it into your agent loop with proper validation and observability.

This template is designed to be injected into your agent's repair step when a tool call fails validation. Unlike a generic repair prompt, it explicitly incorporates the [RETRY_BUDGET]—the number of remaining attempts—to adjust the model's strategy. On early retries, the prompt encourages aggressive, context-based inference to fix the issue quickly. On the final attempt, it forces a conservative fallback to a safe, no-op, or clarification request, preventing an infinite loop of hallucinated repairs. The prompt expects the original failing arguments, the validation error, and the tool's schema to be provided as dynamic context.

textCopy
You are an expert tool-call repair agent inside an autonomous system. Your goal is to fix a malformed function call so it passes schema validation.

# CONTEXT
- Remaining repair attempts: [RETRY_BUDGET]
- The original user request and conversation history are provided below.

# FAILED TOOL CALL
- Tool Name: [TOOL_NAME]
- Invalid Arguments: [INVALID_ARGUMENTS_JSON]
- Validation Error: [ERROR_MESSAGE]

# EXPECTED SCHEMA
```json
[TOOL_SCHEMA_JSON]

REPAIR STRATEGY BASED ON RETRY BUDGET

• If [RETRY_BUDGET] > 1: You may infer missing or incorrect values from the conversation context, tool description, and parameter descriptions. Prioritize getting a valid call executed. Be aggressive but grounded.
• If [RETRY_BUDGET] == 1: This is the final attempt. Do not guess. If you cannot fix the arguments with absolute certainty, you must output a safe fallback. The fallback is a call to [CLARIFICATION_TOOL_NAME] asking the user for the specific missing or invalid parameters.

CONSTRAINTS

• Do not invent values that are not strongly implied by the context.
• Do not add parameters that are not in the schema.
• Ensure all required parameters are present.
• Output ONLY the repaired JSON tool call, enclosed in a ```json code block. No other text.

CONVERSATION CONTEXT

[CONVERSATION_HISTORY]

Repair the tool call now.

To adapt this template, replace the square-bracket placeholders with live data from your agent loop. [RETRY_BUDGET] should be an integer decremented by your orchestration framework before each repair attempt. [INVALID_ARGUMENTS_JSON] is the exact string that failed validation, and [ERROR_MESSAGE] is the raw output from your schema validator. The [TOOL_SCHEMA_JSON] must be the complete JSON Schema definition for the tool's parameters. Crucially, you must define a [CLARIFICATION_TOOL_NAME] in your tool registry that the agent can use to ask the user for help when a repair is impossible. Before deploying, test this prompt with a golden dataset of known malformed calls to ensure the retry-budget logic triggers the correct behavior at each stage.

The retry-budget-aware repair prompt is designed to sit inside a structured agent loop, not as a one-off correction call. The harness must track the remaining retry budget, pass it into the prompt as [REMAINING_ATTEMPTS], and enforce the escalation path when the budget reaches zero. This means the calling code should maintain a counter decremented on each repair attempt, inject the current count into the prompt template, and route the final attempt's output to a human review queue or a dead-letter log rather than looping indefinitely.

Validation is the gate before and after repair. Before invoking the repair prompt, validate the original tool call against the expected schema using a JSON Schema validator or the tool platform's native validation. Capture the exact validation error message and the failing argument payload—these become [VALIDATION_ERROR] and [FAILING_TOOL_CALL] in the prompt. After the repair prompt returns a corrected call, re-validate it against the same schema. If validation passes, execute the tool call and log the repair attempt count, latency, and whether it was an early-retry aggressive fix or a final-attempt conservative escalation. If validation fails again and budget remains, loop back with the new error. If budget is exhausted, route to the escalation path defined in [ESCALATION_ACTION].

Model choice matters for repair quality. Early retries (high remaining budget) benefit from faster, cheaper models that can attempt aggressive inference—filling missing fields, normalizing enums, and fixing syntax. Final retries (budget at 1 or 0) should use a more capable model with stronger instruction-following, since the prompt instructs conservative escalation: returning a safe fallback, requesting clarification, or aborting with a structured error. Implement model routing in the harness by checking [REMAINING_ATTEMPTS] before selecting the model endpoint. Log which model handled each repair attempt so you can measure whether the routing strategy improves repair success rates.

Observability is non-negotiable. For every repair attempt, emit a structured log event containing: the original tool call, the validation error, the remaining budget, the repair prompt version, the model used, the corrected output, the re-validation result, and the final disposition (executed, escalated, or abandoned). This log becomes your repair quality dataset. Use it to track metrics like repair success rate by attempt number, hallucination rate in repaired arguments, and escalation frequency. Set alerts on sudden increases in final-attempt escalations—this often signals a model behavior change or a schema update that the repair prompt hasn't been adapted to handle.

Avoid wiring this prompt into a blind retry loop without budget awareness. The most common production failure mode is an agent that retries indefinitely, burning tokens and latency on unfixable tool calls. The [REMAINING_ATTEMPTS] injection is what prevents this. Test your harness by feeding it intentionally unfixable tool calls—missing required arguments with no context to infer from, completely hallucinated tool names, or schema violations that require information the agent doesn't have. Confirm that when budget hits zero, the system escalates rather than retrying. Pair this with a dead-letter queue or review interface so escalated cases don't silently disappear.