Every few hundred requests, I'd spot the same thing in Braintrust: a tool call that clearly understood the user's question but mangled the JSON on the way out. Wrong union variant, missing field, number where a string should be. The model knew what it wanted to say; it just couldn't spell it right.

The standard practice is to fail the tool call and fire off a retry. But I've been experimenting with a different approach; intercepting the validation error, then asking a cheap model to fix the JSON.

The problem

The query DSL is probably the most complex tool schema in the whole app (I've actually written all about it here!). To give you a sense of what the model's working with, it includes:

Discriminated unions for filter types (equals, between, in, isNull, each with different required fields)
Nested logical expressions (and/or groups that can contain other groups)
Optional fields that change meaning depending on the union variant
Multiple valid shapes for the same query (you can express "last 7 days of bench press" in several structurally different ways)

...so you can imagine even capable models like Haiku and GPT-4o getting this wrong sometimes.

When validation failed in a typical setup, the entire tool call produced no result. The main model would see this silence and either retry (burning tokens) or give up and apologise to the user. Both were far from ideal.

The solution: Intercept and repair

Instead of failing, I intercept the validation error and ask Gemini 2.5 Flash to fix the JSON. The Vercel AI SDK has an experimental_repairToolCall hook that fires whenever a tool call fails schema validation, which ended up being exactly what I needed.

Here's the repair function from apps/api/src/lib/tool-repair.ts:

export async function repairToolCall(
  toolCall: { toolName: string; input: string },
  error: { message: string },
  schema: Record<string, unknown>,
  openrouter: OpenRouterProvider,
  traceId: string,
): Promise<typeof toolCall | null> {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), REPAIR_TIMEOUT_MS);
 
  try {
    const { text } = await generateText({
      model: openrouter.chat(REPAIR_MODEL_ID),
      system:
        "Fix the JSON arguments for this tool call so they conform " +
        "to the schema. Return ONLY the corrected JSON object, " +
        "no explanation or markdown.",
      prompt:
        `Tool: ${toolCall.toolName}\n` +
        `Schema: ${JSON.stringify(schema)}\n` +
        `Original args: ${toolCall.input}\n` +
        `Validation error: ${error.message}\n\n` +
        `Corrected JSON:`,
      abortSignal: controller.signal,
    });
 
    const jsonMatch = text.match(/\{[\s\S]*\}/);
    if (!jsonMatch) return null;
 
    return { ...toolCall, input: jsonMatch[0] };
  } catch {
    return null;
  } finally {
    clearTimeout(timeout);
  }
}

The repair model doesn't need to understand fitness coaching; it just needs to fix JSON to match a schema. That's why Gemini Flash works so well here. It's fast, cheap, and this kind of structural JSON correction is kinda its sweet spot.

I'm feeding it everything it needs to succeed: the schema, the original broken arguments, and the specific validation error message. AI SDK hands us the error in a lovely, human-readable format (e.g., "Expected string at path .where.type, received number"), so it doesn't leave the LLM guessing.

The regex extraction (/\{[\s\S]*\}/) is there because the repair model sometimes wraps its output in markdown code blocks or adds explanatory text. This is pretty annoying. If you have any ideas on how to get around this, hit me up.

The 5-second timeout is aggressive on purpose. If the cheap model is being slow, it's better to fail fast(ish) than hold up the user's request; the repair is an optimisation, not a gate.

Wiring it up

Here's how the repair function connects to the chat stream in apps/api/src/routes/chat.ts:

const MAX_TOOL_CALL_REPAIRS = 3;
let repairAttempts = 0;
 
const config = {
  // ... other streamText config ...
  experimental_repairToolCall: async ({ toolCall, error, inputSchema }) => {
    repairAttempts++;
    if (repairAttempts > MAX_TOOL_CALL_REPAIRS) {
      logger.warn("[Chat] Tool call repair limit reached", {
        toolName: toolCall.toolName,
        attempts: repairAttempts,
      });
      return null;
    }
 
    const schema = await inputSchema({ toolName: toolCall.toolName });
    const repaired = await repairToolCall(
      toolCall,
      error,
      schema as Record<string, unknown>,
      openrouter,
      collector.traceId,
    );
    if (!repaired) return null;
    return { ...toolCall, ...repaired };
  },
};

The MAX_TOOL_CALL_REPAIRS cap is important. Without it, a fundamentally broken tool call could trigger an infinite repair loop. I landed on 3 because if the repair model can't fix it in three tries, the mismatch is likely structural (a genuinely unsupported query shape) rather than a simple typo or missing field. Three attempts is generous enough to catch the easy stuff without burning cycles on the impossible stuff. And (anecdotally), it typically repaired within one or two attempts, so three just felt a touch more conservative.

What this ended up getting me

The repair function caught most of the common failures: wrong discriminated union variant, missing required field, incorrect type coercion. It adds ~200ms to the request if it has to fire, but that's far better than the alternative (a failed tool call, a confused model retry and a frustrated user).

The pattern turned out to be pretty generalizable; any agentic system with complex tool schemas could benefit from the same approach. Validation errors contain exactly the information needed to fix the problem. You just need something cheap and fast to act on it.

What's still rough

The regex extraction step is still a bit hacky. Even with strict prompting, the repair model occasionally returns markdown wrappers or extra text, so I still have to defensively parse around it. It works, but I'd much rather rely on fully structured output here.

TL;DR

If your agent's tool schemas are complex enough that the main model occasionally mangles the JSON, consider intercepting validation errors and letting a cheap model fix them instead of failing the whole call.

Takeaways

Feed the validation error, not just the schema. The repair model needs to know what broke, not just what the target shape looks like. AI SDK's human-readable error messages made this trivial.

Cap repair attempts aggressively. Three tries is plenty. If the repair model can't fix it by then, the mismatch is probably structural, not a simple typo.

Keep the repair model's job narrow. It doesn't need conversation context, tool descriptions, or the system prompt. Just the broken JSON, the schema and the error. Smaller context means faster repair.

Treat repair as an optimisation, not a gate. If the repair model fails, return null and let the main model handle it. The worst outcome is the status quo; exactly what would've happened without the repair step.

Self-healing tool calls with a cheap LLM