Agent inventing tool parameters that don't exist? Fixing hallucinated tool arguments

Your agent works fine, then starts failing intermittently. The logs show tool calls with parameters you never defined — an include_metadata flag on a function that has no such option, or a required field quietly omitted. The model isn't hallucinating facts here; it's hallucinating the shape of your API, and the call dies on validation before your tool ever runs.

What's actually happening

The model generates a tool call from the pattern of the conversation, not from your schema. When your schema is loose or ambiguous, it fills the gaps creatively. The failure shows up in a few recognisable shapes:

• Invented parameters. The function name is right, but the model adds a flag or field that doesn't exist in the schema — the most insidious case, because it looks plausible.
• Missing required arguments. The opposite: it omits a field the schema requires, generating a call that fails validation.
• Wrong argument types. A string where a number is expected, a scalar where an array belongs.

In SDK terms this surfaces as errors like AI_InvalidToolArgumentsError — the call is rejected before execution. That's the good case (it failed closed). The bad case is a loose schema (additionalProperties: true) that accepts the invented field and does something wrong with it.

Why it's a system problem, not a prompt problem

Better prompts don't reliably fix this. Hallucinated arguments almost always trace back to a system weakness the agent exposed: an ambiguous schema, inconsistent null handling, a stale definition pushed out of context. The agent amplified what was already loose. The durable fixes are structural.

The fix

1. Strict schemas. Set additionalProperties: false so invented fields are rejected, not absorbed. Use JSON Schema or Pydantic and make required fields explicit.
2. Validate before execution. Check the arguments against the schema before the tool runs, and fail closed on anything invalid.
3. Return structured errors. When a call is rejected, hand the model a typed, readable error (status: "invalid_argument", field: "...") so it can correct — not a raw exception it will hallucinate a recovery for.
4. Keep tool definitions in context. If the context window fills and pushes the schema out of scope, the model is guessing. Keep definitions fresh at decision points.

Diagnose a run that already failed this way

Send the trace to diagnose_trace and Snapback returns failure_class: "hallucinated_tool_args" with the specific argument that was wrong and the concrete fix — so you know whether to tighten the schema, add validation, or fix an ambiguous definition:

diagnose_trace({trace: { final_status: "failed", steps: [
  {index:1, action:"book_flight",
   inputs:{destination:"NYC", include_metadata:true}, // invented arg
   error:"AI_InvalidToolArgumentsError", status:"failed"} ]}})

// → { failure_class: "hallucinated_tool_args", root_cause, fix_suggestion, confidence }