Invalid Tool Call Schema Repair Prompt Template

This prompt is a surgical recovery tool for AI engineers building agent harnesses where a model-generated tool call is rejected by a downstream JSON Schema validator. The job-to-be-done is strictly post-validation repair: the model has already attempted a tool call, the application layer has caught a ValidationError, and you need a corrected payload that passes schema checks without losing the original intent. The ideal user is an integration engineer or platform developer who controls the retry loop, has access to the exact validation error message, and can inject the target schema into the model context. This prompt is not for initial tool call generation, nor for debugging why the model produced an invalid call in the first place—those are separate concerns addressed by system prompt design and tool description hygiene.

Use this prompt when you have three concrete artifacts available: the invalid payload exactly as the model returned it, the target JSON Schema that defines the expected structure, and the specific validation error message produced by your validator (e.g., 'required' property 'user_id' is missing, 'status' value 'activee' is not a valid enum, or additionalProperty 'phoneNumber' is not allowed). The prompt works best inside a structured retry loop with a bounded budget—typically 1–3 attempts—because schema repair is a narrow, well-defined task that should converge quickly. Do not use this prompt when the failure is semantic rather than structural (e.g., the tool call is valid JSON but selects the wrong tool or passes logically incorrect arguments), when the tool execution itself timed out or returned a business-logic error, or when the schema is unavailable or too large to fit in the context window alongside the payload and error message.

Before wiring this into production, establish clear retry budget limits and escalation paths. If the repair prompt fails to produce a valid payload after two attempts, escalate to a human operator or log the failure for offline analysis rather than burning tokens in an infinite loop. For high-risk domains—such as finance, healthcare, or infrastructure automation—require human review of any repaired payload before execution, even if it passes schema validation, because structural correctness does not guarantee semantic safety. The next section provides the copy-ready prompt template you can adapt directly into your retry handler.

This prompt template is designed to be injected into your retry handler immediately after a tool call is rejected by your schema validator. It forces the model to confront the exact validation error, the original (invalid) arguments, and the expected schema simultaneously. The goal is not to re-explain the task but to surgically repair the structural defect while preserving the user's original intent and any valid parameters that were already correct.

textCopy
You are a tool-call repair agent. Your only job is to fix an invalid function call argument payload so that it strictly conforms to the provided JSON Schema.

## INPUTS
- **Original User Intent:** [USER_INTENT]
- **Function Name:** [FUNCTION_NAME]
- **Expected JSON Schema:**
  ```json
  [EXPECTED_SCHEMA]

• Invalid Arguments (failed validation):

  jsonCopy
  [INVALID_ARGUMENTS]

• Validation Error Message: [VALIDATION_ERROR]

REPAIR RULES

1. Schema Conformance: The output must validate cleanly against the Expected JSON Schema. Fix type errors, missing required fields, extra fields, and enum violations.
2. Intent Preservation: Do not change the semantic meaning of the original arguments. Infer missing required parameters from the User Intent only if the inference is unambiguous. If a required parameter cannot be inferred, set its value to null and add a note to the _repair_warnings array.
3. Hallucination Prevention: Do not invent values for fields that were not present in the invalid arguments and cannot be directly inferred from the User Intent. Do not add fields that are not defined in the Expected JSON Schema.
4. Error Addressing: The repair must directly resolve the specific issue described in the Validation Error Message.

OUTPUT FORMAT

Return a single JSON object with exactly two keys:

• repaired_arguments: The corrected arguments object that strictly conforms to the Expected JSON Schema.
• _repair_warnings: An array of strings describing any non-critical issues, such as parameters that were set to null due to insufficient context.

EXAMPLE

User Intent: "Find me a direct flight from SFO to JFK tomorrow morning" Function Name: search_flights Expected JSON Schema: {"type": "object", "properties": {"origin": {"type": "string"}, "destination": {"type": "string"}, "departure_date": {"type": "string", "format": "date"}}, "required": ["origin", "destination", "departure_date"]} Invalid Arguments: {"from": "SFO", "to": "JFK"} Validation Error: "Required property 'departure_date' is missing. Unknown properties: 'from', 'to'."

Your Response: { "repaired_arguments": { "origin": "SFO", "destination": "JFK", "departure_date": null }, "_repair_warnings": ["'departure_date' set to null because 'tomorrow morning' is ambiguous without a current date context."] }

To adapt this template, replace the square-bracket placeholders in your application code before sending the request to the model. [EXPECTED_SCHEMA] should be the raw JSON Schema object for the tool's parameters. [VALIDATION_ERROR] is the exact string returned by your JSON Schema validator (e.g., Ajv, jsonschema). The _repair_warnings array in the output is critical for downstream logic—it allows your harness to decide whether to proceed with a null value or escalate for human clarification without needing to parse the model's free-text reasoning. For high-stakes actions where a null required field is unacceptable, configure your harness to treat any non-empty _repair_warnings array as a terminal failure that triggers an escalation prompt.

The schema repair prompt is not a standalone fix; it is one step inside a structured retry harness. When a tool call fails validation, the harness must catch the error, extract the exact validation failure message and the invalid payload, inject them into the repair prompt, and submit the corrected output for re-validation before execution. This loop must be bounded by a retry budget to prevent infinite cycles when the model cannot converge on a valid payload.

Implement the harness as a retry loop with three clear stages: catch, repair, and re-validate. In the catch stage, intercept the validation error from your schema validator (e.g., jsonschema, pydantic, or a custom function signature checker) and capture both the full error message and the offending JSON. In the repair stage, populate the prompt template's [INVALID_TOOL_CALL] with the raw failed payload, [EXPECTED_SCHEMA] with your tool's JSON Schema or function signature, and [VALIDATION_ERROR] with the exact error string. Submit the repair prompt and parse the [CORRECTED_TOOL_CALL] from the response. In the re-validate stage, run the corrected payload through the same validator. If it passes, proceed to tool execution. If it fails, increment the retry counter and loop, feeding the new error back into the repair prompt. After a configurable maximum retries (typically 3–5), exit the loop and escalate to a human review queue or a fallback model.

Log every attempt with the retry count, the validation error, and the corrected payload for observability. Track the schema_repair_success_rate and retry_budget_exhaustion_rate metrics to detect when the repair prompt itself needs tuning. Avoid silent retries that mask systemic schema mismatches; if the same validation error repeats across attempts, the repair prompt may need stronger constraints or a few-shot example of the correct output shape. For high-risk domains, require human approval before executing the first corrected tool call in a session, then allow autonomous retries for subsequent repairs once the pattern is trusted.