Tool Call JSON Repair Prompt with Error Message Reuse

This prompt is for integration engineers and agent-harness builders who need to recover from invalid JSON tool calls without losing the original intent. The job-to-be-done is straightforward: a model produced a tool call that failed validation, you have the exact error message from the validator, and you need a corrected JSON payload that passes the same schema. The prompt is designed to reuse the error message as the primary repair signal rather than asking the model to guess what went wrong. This works best when the error message is precise—think JSON Schema validation errors, missing required field messages, or type mismatch reports—not vague runtime exceptions.

The ideal user is someone wiring tool-call execution into a production harness. You already have a validation step that rejects malformed calls and produces structured error output. You need a retry instruction that takes the original attempted call, the tool schema, and the validator's error message, then produces a corrected call without hallucinating new parameters or silently dropping required fields. This prompt is not for first-attempt tool-call generation. Use a standard function-calling prompt for initial calls. This prompt is specifically for the repair loop after validation fails. It is also not a substitute for fixing the underlying schema mismatch if your tool definitions have changed—pair this with schema version tracking and deprecation handling.

Do not use this prompt when the error message is empty, misleading, or comes from an external API that returns HTTP 500 with no body. The repair quality depends entirely on the error signal quality. If the validator says 'invalid JSON' without a position or reason, the model has little to work with. In those cases, fall back to a structural repair prompt that re-parses the raw string. Also avoid this prompt when the original tool call was hallucinated—if the model invented a function name that doesn't exist, use a tool-selection recovery prompt instead. For high-stakes tool calls that mutate data, schedule payments, or change production config, always route the repaired output through human approval before execution, regardless of validation pass.

This prompt template is designed to be injected into a retry loop after a model-generated tool call fails JSON schema validation. Instead of asking the model to guess what went wrong, you provide the raw invalid JSON and the precise error message from your validator. The model's only job is to apply the error message to fix the structural problem while preserving the original intent and argument values. This approach reduces repair drift—where the model silently changes correct fields while fixing broken ones—and keeps the repair loop bounded.

textCopy
You are a JSON repair agent. Your task is to fix an invalid JSON tool call using the exact validation error provided.

## INPUT
- Invalid JSON: [INVALID_JSON]
- Validation Error: [ERROR_MESSAGE]
- Expected Tool Schema: [TOOL_SCHEMA]

## CONSTRAINTS
1. Change ONLY what is necessary to resolve the validation error.
2. Preserve all original argument values unless they directly cause the error.
3. If the error message references a specific field path, fix only that path.
4. If the error is ambiguous or you cannot determine the correct fix, output a clarification request instead of guessing.
5. Do not add, remove, or rename fields that are not mentioned in the error message.
6. Return ONLY the corrected JSON object. No markdown fences, no commentary.

## OUTPUT FORMAT
If repairable:
{
  "status": "repaired",
  "corrected_tool_call": { ... }
}

If clarification needed:
{
  "status": "clarification_needed",
  "ambiguous_field": "[FIELD_PATH]",
  "question": "[CLEAR_QUESTION]"
}

To adapt this template, replace [INVALID_JSON] with the raw string that failed validation, [ERROR_MESSAGE] with the exact output from your JSON schema validator (e.g., Ajv, Pydantic, or jsonschema), and [TOOL_SCHEMA] with the expected schema definition. For multi-error scenarios, prioritize errors by severity—structural errors like missing closing braces before type errors—and inject them as a numbered list. If you're using this in a production harness, always validate the corrected_tool_call output against the same schema before submitting it for execution. A repair that introduces a new error is a failure that should increment your retry counter and may require a different recovery strategy.

This prompt is designed to sit inside a tool-call execution loop—the harness code that receives a raw model response, attempts to parse and execute the tool call, and catches validation errors. When a JSON parse failure or schema validation error occurs, the harness should not immediately discard the attempt. Instead, it captures the exact error message from the parser or validator, injects it into the [ERROR_MESSAGE] placeholder alongside the original [INVALID_JSON] payload, and re-invokes the model with this repair prompt. The model receives the specific failure reason (e.g., "missing required property 'user_id' at line 12, column 5") rather than a generic "invalid JSON" message, which dramatically improves repair accuracy.

Harness integration steps: (1) Wrap the initial tool-call attempt in a try/catch or schema validation block. (2) On failure, extract the raw error string from your JSON parser (e.g., json_decode_last_error_msg() in PHP, JSONDecodeError in Python, or the validator library's error output). (3) Populate [INVALID_JSON] with the exact string the model produced and [ERROR_MESSAGE] with the parser's error. (4) Send the repair prompt to the model and parse the response. (5) Re-validate the repaired output against the original tool schema before execution. Critical constraint: Never execute a repaired tool call without re-validation—the repair prompt can itself produce malformed output, especially on the first retry. If the repaired output fails validation again, increment a retry counter and repeat the loop with the new error message. Stop after a configurable MAX_RETRIES (typically 2–3) and escalate to a human or fallback workflow.

Multi-error prioritization: When a validator returns multiple errors (e.g., three missing fields and one type mismatch), do not dump all errors into the prompt at once. Inject the first blocking error on retry 1, the second on retry 2, and so on. This progressive disclosure prevents the model from becoming confused by overlapping correction instructions. If the same error persists across retries, the harness should log the staleness and escalate—the model is likely hallucinating a fix rather than applying the error message. Logging and observability: Record each retry attempt with the original invalid JSON, the error message injected, the repaired output, and the validation result. This trace is essential for debugging prompt drift and identifying tool schemas that are inherently difficult for the model to satisfy. Model choice: Use a model with strong instruction-following and JSON generation capabilities. Smaller or older models may struggle with error-message interpretation and produce repairs that pass validation but lose semantic intent—always eval repair accuracy, not just schema conformance.