stop_reason: max_tokens and Truncation

Reading stop_reason

stop_reason is one of the fields step 2 of the isolation procedure calls out for inspection, and it deserves its own attention because one value in particular is a frequent source of misdiagnosis: **`stop_reason: max_tokens` means the output was cut off before Claude finished -- the response is truncated**, not malformed on its own terms.

Truncation Disguised as a Format Bug

A truncated response very often *looks* like a schema or formatting failure: JSON that ends mid-object, a missing closing brace, an unterminated string. Without checking `stop_reason` first, it is easy to conclude the model produced invalid JSON, when the real story is that the model was still writing valid JSON and ran out of the token budget it was given.

The Fix

The correct fix is to **raise `max_tokens`**, not to redesign the schema, simplify the output format, or otherwise treat this as a model quality issue. The model didn't fail to produce valid structure -- it wasn't given enough room to finish.

Common exam traps

• Rewriting the JSON schema to be "simpler" or lowering temperature in response to a truncation-caused parse error -- neither addresses the actual cause. `stop_reason: max_tokens` is a direct signal that the fix is a token-budget change, not a prompt, schema, or sampling change.
• Treating every invalid-JSON symptom as a model-output error before checking stop_reason -- truncation is an integration-layer configuration problem (the caller set too small a `max_tokens`), even though the symptom shows up as "bad" model output.