Gemini 2.5 Flash was returning 37 tokens. Here's why.

I set max_tokens: 1000 on a Gemini 2.5 Flash call. The response came back with 37 tokens. finish_reason: "MAX_TOKENS". No error. No warning. Just a string that stopped mid-sentence. I changed it to 2000. Got back 41 tokens. Then 5000. Got back 38. That's when I knew something was actually broken, not just a config issue. I spent a day tracing this. The root cause is surprising, the official docs don't explain it, and the fix depends on which version of which SDK you're using. Here's what I learned, and a diagnostic script at the end so you can figure out which variant of the bug you hit.