[DOCS] Discrepancy in `MAX_THINKING_TOKENS` stability advice between General Settings and Bedrock-specific documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/settings#environment-variables - https://code.claude.com/docs/en/amazon-bedrock#5-output-token-configuration

Section/Topic

The documentation for the MAX_THINKING_TOKENS environment variable and how it interacts with tool execution stability.

Current Documentation

From General Settings:

MAX_THINKING_TOKENS: "Thinking is enabled at max budget (31,999 tokens) by default. Use this to limit the budget... Extended thinking improves performance on complex reasoning and coding tasks but impacts prompt caching efficiency."

From Amazon Bedrock Configuration:

MAX_THINKING_TOKENS=1024: "This provides space for extended thinking without cutting off tool use responses... This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically." Additionally, it notes regarding CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096: "Setting this lower ... may cut off long tool uses, causing the Claude Code agent loop to fail persistently."

What's Wrong or Missing?

There is a conflict between what is presented as a safe "default" and what is presented as "stable" for agent operation:

1. The Settings page presents 31,999 tokens as the standard default without any stability warnings regarding tool usage.
2. The Bedrock page suggests a much lower value (1024) is required to ensure that thinking tokens do not consume the shared output budget, which would otherwise truncate tool calls (like file writes) and cause the agent loop to "fail persistently."
3. It is unclear if this risk is exclusive to Bedrock or if users on the standard Claude API (1P) should also be wary of the 31,999 default when performing large file edits.

Suggested Improvement

The MAX_THINKING_TOKENS entry in the Settings table should include a cautionary note about the shared output budget.

Suggested text for Settings page:

MAX_THINKING_TOKENS: Override the extended thinking token budget. Defaults to 31,999. Note: Thinking tokens share the total output token budget with tool calls. If this value is set too high relative to your CLAUDE_CODE_MAX_OUTPUT_TOKENS, the model may run out of space to return full tool results (like long file edits), potentially causing the agent loop to fail. For most stable performance with tools, a value of 1024-4096 is recommended unless complex reasoning is required.

Impact

High - Prevents users from using a feature

Additional Context

The Bedrock documentation specifically highlights that "Bedrock's burndown throttling logic" and the resulting 4096 limit make this balance critical. If this is a provider-specific limitation, the Settings page should clarify that the 31,999 default is safe for 1P/Console users but requires adjustment for 3P providers. However, since the model's total output limit is finite across all providers, the risk of truncation exists everywhere.