Tool Call Repair with Schema-Aware Suggestions Prompt Template

This prompt is for agent platform engineers and tool-integration developers who need to recover from invalid tool calls by generating multiple ranked repair candidates. Use it when a tool call fails validation and you want the agent loop to have options to choose from, rather than a single best-guess repair. The prompt takes the original invalid tool call, the tool's JSON schema, the validation error, and optional conversation context, then returns a ranked list of candidate repairs with confidence scores and explanations. This is not a single-repair prompt. It is designed for developer tooling that provides inline repair suggestions where the agent or a downstream validator selects the best candidate.

The ideal user is building an agent harness or orchestration layer where tool call failures must not abort the entire agent loop. You need the original invalid tool call payload, the exact JSON schema for the tool (including required fields, types, and enum values), and the specific validation error message. Optionally, you can include the preceding conversation context to help the model infer missing arguments or disambiguate intent. The output is a ranked list of candidate repairs, each with a confidence score and a brief explanation of what was changed and why. This structure allows your agent loop to try the top candidate, fall back to alternatives, or escalate to a human if no candidate meets a confidence threshold.

Do not use this prompt when you need a single deterministic repair, when the tool schema is unavailable, or when the validation error is ambiguous and cannot be traced to specific fields. If the failure is a simple syntax error in the JSON, a deterministic parser-based repair is more reliable and cheaper. If the tool schema is missing, the model cannot ground its repairs and will hallucinate field names and types. If the validation error is vague (e.g., 'invalid request'), the prompt cannot produce targeted repairs and will generate low-quality guesses. In high-risk domains such as finance or healthcare, always route low-confidence candidates to human review before execution.

This prompt template is designed to be placed directly into your agent's repair harness. When a tool call fails validation, this prompt instructs the model to act as a schema-aware repair engine. Instead of guessing a single fix, it generates multiple candidate repairs, each with a confidence score and a rationale. This allows your agent loop to select the best candidate, attempt validation again, or escalate to a human if no high-confidence repair is available. The key advantage is that it provides a ranked set of options, turning a binary pass/fail event into a decision point with measurable quality signals.

textCopy
You are a schema-aware tool call repair engine. Your task is to analyze a failed tool call and generate multiple candidate repairs.

**Original Failed Tool Call:**
```json
[FAILED_TOOL_CALL_JSON]

Target Tool Schema:

jsonCopy
[TOOL_SCHEMA_JSON]

Validation Error Message: [VALIDATION_ERROR_MESSAGE]

Conversation Context (for inferring missing values): [CONVERSATION_CONTEXT]

Repair Constraints:

• Generate exactly [NUM_CANDIDATES] distinct repair candidates.
• Each candidate must be a complete, valid JSON object conforming to the Target Tool Schema.
• Do not invent values that cannot be reasonably inferred from the Conversation Context or the Original Failed Tool Call.
• If a required field cannot be inferred, use null and set the confidence for that field to 0.0.
• Prioritize repairs that make the minimal necessary changes to the original arguments.

Output Format: Return a JSON object with a single key "candidates" containing an array of repair objects. Each repair object must have the keys "repair", "confidence", and "rationale".

• "repair": The fully repaired tool call arguments as a JSON object.
• "confidence": A score from 0.0 to 1.0 indicating your confidence that this repair is correct and will pass validation.
• "rationale": A brief, specific explanation of what was changed and why.

Output Example:

jsonCopy
{
  "candidates": [
    {
      "repair": {
        "location": "London",
        "units": "celsius"
      },
      "confidence": 0.95,
      "rationale": "Corrected 'unit' to 'units' based on schema and set location to 'London' from context."
    },
    {
      "repair": {
        "location": "London, UK",
        "units": "celsius"
      },
      "confidence": 0.7,
      "rationale": "Inferred a more specific location string from context, though the schema may expect a simpler form."
    }
  ]
}

To adapt this template, replace the square-bracket placeholders with live data from your application. [FAILED_TOOL_CALL_JSON] should be the exact string that failed parsing or schema validation. [TOOL_SCHEMA_JSON] is the expected parameter schema for the target function. [VALIDATION_ERROR_MESSAGE] provides critical signal—pass the raw error from your validator (e.g., pydantic, jsonschema) to guide the repair. [CONVERSATION_CONTEXT] should include the last few messages from the agent's history to help infer missing arguments. Set [NUM_CANDIDATES] to a small odd number like 3 or 5 to enable a simple majority-vote or selection mechanism in your harness. The output format is strict JSON, making it straightforward to parse and feed into a validation retry loop. For high-risk domains, always log the original failure, all candidates, and the final selected repair for auditability.

The Tool Call Repair with Schema-Aware Suggestions prompt is designed to be called as a recovery step inside an agent execution loop, not as a standalone utility. When a tool call fails validation, the agent should invoke this prompt to generate multiple candidate repairs, each with a confidence score. The agent loop then selects the best candidate, re-validates it against the tool schema, and either executes the repaired call or escalates. This harness must track the retry budget, log repair attempts for observability, and prevent infinite repair loops when the model cannot produce a valid suggestion.

To wire this into an application, wrap the prompt in a repair function that accepts the original tool call, the validation error, the tool schema, and the conversation context. The function should call the LLM with the prompt template, parse the response into a list of candidate repairs with confidence scores, and sort them by score descending. Each candidate must be validated against the tool schema before execution. If the top candidate passes validation, execute it. If it fails, try the next candidate. If no candidate passes, decrement the retry budget and call the repair prompt again with the new failure context. After exhausting the retry budget, escalate to a human or log the failure for offline analysis. Log every repair attempt with the original error, the candidates generated, the selected repair, and the validation result to build a dataset for future fine-tuning or prompt improvement.

Model choice matters here: use a model with strong JSON generation and instruction-following capabilities. The prompt expects a structured output containing an array of repair objects, so enable structured output mode or use a JSON schema constraint if the model API supports it. For high-throughput systems, consider caching the tool schema to avoid passing it repeatedly. The confidence scores from the model are not calibrated probabilities—treat them as relative rankings. Implement a minimum confidence threshold below which repairs are discarded without attempting validation. Avoid using this repair prompt for security-critical tool calls where a hallucinated repair could cause harm; those should fail closed and require human review.