[DOCS] Conflicting instructions regarding `budget_tokens` and `max_tokens` limits

Documentation Type

Unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/about-claude/models/extended-thinking-models

Section/Topic

The "How to use extended thinking" and "Interleaved thinking" sections.

Current Documentation

Under the How to use extended thinking header:

"budget_tokens must be set to a value less than max_tokens."

Under the Interleaved thinking header:

"With interleaved thinking, the budget_tokens can exceed the max_tokens parameter, as it represents the total budget across all thinking blocks within one assistant turn."

What's Wrong or Missing?

The documentation provides a "strict" rule in the setup guide that is explicitly contradicted later in the same document. A user reading the initial setup instructions might assume a request is malformed if the budget exceeds max_tokens, not realizing this constraint is lifted when using the interleaved thinking beta.

Suggested Improvement

In the How to use extended thinking section, add a qualifier to the token limit rule:

"budget_tokens must be set to a value less than max_tokens, except when using [interleaved thinking](#interleaved-thinking). In interleaved workflows, the budget can exceed max_tokens as it covers the cumulative total of all thinking blocks in the turn."

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: Building with extended thinking - Interleaved thinking
• Model specific behavior: This inconsistency is particularly relevant for Claude 4 models where interleaved thinking is supported via the interleaved-thinking-2025-05-14 beta header.

---