Function Argument Type Coercion Recovery Prompt Template

Use this prompt when an agent harness receives a type error after attempting a function call. The model produced arguments that fail the target function's type constraints: a string where a number is required, a bare value where an array is expected, or a string like 'true' that needs boolean parsing. This prompt instructs the model to coerce the arguments to the correct types while preserving the original intent. It is designed for AI engineers and platform teams building agent harnesses where tool-call failures break execution pipelines and require structured retry instructions that correct the call shape without losing semantic meaning.

This prompt is appropriate when the model's intent is clearly recoverable from the malformed arguments. For example, if a function expects {"temperature": number} and the model produced {"temperature": "72.5"}, the coercion from string to float is unambiguous and safe. The prompt includes coercion safety rules to prevent silent data corruption, such as coercing 'N/A' to 0 or truncating precision on financial values. Wire this prompt into your retry harness immediately after catching a TypeError or schema validation failure on the arguments payload, before the error propagates to the user or aborts the agent's task loop.

Do not use this prompt when the type error masks a deeper semantic misunderstanding. If the model passed a string because it hallucinated a parameter name or confused units (e.g., passing '72' when the function expects Kelvin), type coercion will produce a valid but wrong call. In those cases, use a schema mismatch retry or a clarification prompt instead. Also, avoid this prompt for high-risk domains like financial transactions or medical dosing where even a correct-seeming coercion could have outsized consequences; those workflows should escalate to a human reviewer after the first type failure. The next section provides the copy-ready template you can adapt and inject into your agent's error-recovery loop.

This prompt template is designed to be injected into your agent's retry harness immediately after a tool call fails with a type error. Its job is to take the original, invalid arguments, the specific type error message, and the function's schema, and produce a corrected JSON payload where every argument conforms to the expected type. The core instruction forces the model to apply explicit coercion rules—such as "123" to 123 or "true" to true—while strictly forbidding it from inventing new values or silently dropping fields. You should use this prompt when your validator rejects a call due to type_error, invalid_type, or similar schema violations, and you want a single, structured recovery attempt before escalating.

textCopy
SYSTEM:
You are a function argument repair agent inside a critical execution pipeline. Your only job is to fix type coercion errors in a JSON payload so it passes strict schema validation. You must preserve the original intent and values exactly. You must never hallucinate, invent, or guess missing data.

INPUT:
- FUNCTION_SCHEMA:
[FUNCTION_SCHEMA]
- ORIGINAL_ARGUMENTS:
[ORIGINAL_ARGUMENTS]
- TYPE_ERROR_MESSAGE:
[TYPE_ERROR_MESSAGE]

COERCION RULES:
1. String-to-Number: If a field expects a number but received a numeric string (e.g., "42"), coerce it to a number (42). If the string is non-numeric (e.g., "abc"), do not coerce; instead, flag it as UNRECOVERABLE.
2. String-to-Boolean: If a field expects a boolean and received "true", "false", "1", or "0" (case-insensitive), coerce it to the corresponding boolean. Any other string is UNRECOVERABLE.
3. Number-to-String: If a field expects a string but received a number, coerce it to its string representation.
4. Single-Value-to-Array: If a field expects an array but received a single value of the correct item type, wrap it in an array (e.g., "item" to ["item"]). Do not wrap if the single value is of the wrong type.
5. Null Handling: If a field is nullable and received null, pass null through. If a field is not nullable and received null, flag as UNRECOVERABLE.
6. No Silent Deletion: Every key in ORIGINAL_ARGUMENTS must appear in the output, either corrected or flagged. Do not drop fields.

OUTPUT_SCHEMA:
{
  "recovery_status": "SUCCESS" | "PARTIAL" | "UNRECOVERABLE",
  "corrected_arguments": { ... },
  "unrecoverable_fields": [
    {
      "field_path": "string",
      "original_value": "any",
      "expected_type": "string",
      "reason": "string"
    }
  ]
}

INSTRUCTIONS:
1. Parse the TYPE_ERROR_MESSAGE to identify the exact field path and expected type.
2. Apply the COERCION RULES to the identified field.
3. If coercion succeeds, set recovery_status to "SUCCESS" and include the fully corrected arguments.
4. If any field cannot be safely coerced, set recovery_status to "PARTIAL" or "UNRECOVERABLE", populate unrecoverable_fields, and still include the partially corrected arguments.
5. Output ONLY the JSON object. No other text.

To adapt this template for your harness, replace the three square-bracket placeholders at runtime. [FUNCTION_SCHEMA] should be the full JSON Schema object for the tool's parameters, injected as a pretty-printed string. [ORIGINAL_ARGUMENTS] is the exact JSON string the model attempted to call. [TYPE_ERROR_MESSAGE] is the raw error string from your validator (e.g., from Pydantic, Zod, or JSON Schema validators). The prompt is designed to be stateless; it does not rely on conversation history. For high-risk domains like finance or healthcare, you must route any output with recovery_status set to "PARTIAL" or "UNRECOVERABLE" to a human review queue instead of automatically retrying. Before deploying, test this prompt against a golden set of known coercion cases—including edge cases like empty strings, NaN, and deeply nested paths—to ensure your model follows the rules without hallucinating corrections for unrecoverable fields.

The Function Argument Type Coercion Recovery prompt is designed to be called programmatically within an agent harness, not as a standalone chat. It should be invoked immediately after a tool call fails with a type error (e.g., TypeError, ValidationError for type mismatches). The harness must capture the exact error message, the original function name, the invalid arguments, and the expected function schema. This context is injected into the prompt's [ERROR_MESSAGE], [FUNCTION_NAME], [INVALID_ARGUMENTS], and [FUNCTION_SCHEMA] placeholders. The model's response should be a strict JSON object containing the corrected_arguments and a coercion_log that explains each change, which the harness parses before retrying the tool call.

A robust implementation requires a validation gate before the retry. After receiving the model's corrected arguments, the harness must validate them against the original function schema using a JSON Schema validator or Pydantic model. If validation fails again, the harness should increment a coercion_attempt counter. For a second failure, re-invoke the prompt but include the new validation error in the [ERROR_MESSAGE] field. Implement a hard retry budget (e.g., 3 attempts). If the budget is exhausted, the harness must not loop infinitely. Instead, it should log the full failure chain, set the task to a terminal coercion_failed state, and escalate to a human review queue or a dead-letter topic with the original intent, all attempted arguments, and the final schema violation. This prevents silent data corruption from a model that persistently hallucinates type conversions.

Logging is critical for observability and debugging. Every coercion attempt should produce a structured log event containing the attempt_number, original_arguments, error_received, model_coerced_arguments, coercion_log, and validation_result. This trace allows you to identify patterns, such as a specific model version consistently failing to coerce ISO 8601 strings to Unix timestamps. Use these logs to refine the [COERCION_SAFETY_RULES] section of the prompt template or to add pre-processing logic in the harness that handles common, deterministic coercions (like trimming whitespace from numbers) before invoking the LLM, saving latency and cost. Avoid using this prompt for high-stakes financial or healthcare data where a coercion error, even if logged, could have compliance implications; those workflows should reject the payload and request explicit human correction immediately.