[DOCS] Documentation for Extended Thinking feature is unclear and incomplete

Documentation Type

Unclear/confusing documentation

Documentation Location

https://docs.claude.com/en/docs/claude-code/common-workflows

Section/Topic

The "Use extended thinking" section.

Current Documentation

Tips to get the most value out of extended thinking: [Extended thinking](/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as: Planning complex architectural changes Debugging intricate issues Creating implementation plans for new features Understanding complex codebases Evaluating tradeoffs between different approaches Use Tab to toggle Thinking on and off during a session. The way you prompt for thinking results in varying levels of thinking depth: "think" triggers basic extended thinking * intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking

What's Wrong or Missing?

There are three main issues with the current documentation and its corresponding in-app behavior:

1. Unclear UI for Thinking State: The documentation states that Tab toggles thinking on and off "during a session," and the v2.0.0 changelog mentions it is "sticky across sessions". However, the UI does not reflect this persistently. When toggling thinking on or off with Tab, the status message "Thinking on" or "Thinking off" appears in the status line for only a second or two before disappearing. This leaves the user unsure of the current state without having to toggle it again to see the momentary message.

1. Vague Explanation of Thinking Levels: The documentation mentions "varying levels of thinking depth" and lists several "intensifying phrases" but provides no clarification on what this means in practice. It's unclear how much "deeper" the thinking is for "think hard" versus "think a lot". This lack of detail makes it difficult for users to know which phrase to use for a given task. It is also not clear if these phrases are additive to the Tab toggle or if they override it for a single prompt.

1. Missing Keyword Documentation: The keyword ultrathink, which appears to trigger the maximum level of thinking, is not mentioned anywhere in the official documentation. This is an undocumented feature that users might discover by chance, but its behavior and intended use case are completely undefined.

Suggested Improvement

1. Clarify UI Behavior: The documentation should explain that the "Thinking on/off" status is not persistently displayed. Better yet, the UI should be updated to include a permanent indicator in the status line (e.g., a "Thinking" or "💡" icon) that clearly shows whether the mode is active for the session.

1. Provide More Detail on Thinking Levels: The documentation should be updated to provide more concrete information about the different thinking levels. For example:

• Explain the mechanism (e.g., "These keywords allocate a larger pre-computation token budget for the thinking process.").
• Provide guidance on when to use different levels (e.g., "think hard is suitable for multi-file refactoring, while think is for single-function analysis.").
• Relate this feature to the MAX_THINKING_TOKENS environment variable mentioned in the settings documentation.

1. Document All Keywords: If ultrathink is an official feature, it should be added to the documentation along with the other intensifying phrases, with an explanation of its intended effect.

Impact

High - Prevents users from using a feature

Additional Context

Screenshot showing the issue:
The UI briefly shows "Thinking on (tab to toggle)" but this message disappears, leaving no persistent indicator of the mode's status. Toggling it on shows a "Thinking on" message that also disappears after about one second.

Related Documentation:

• Changelog: The v2.0.0 changelog states: Tab to toggle thinking (sticky across sessions). This implies a persistent state that the UI does not currently reflect.
• Settings: The settings documentation mentions the MAX_THINKING_TOKENS environment variable, which seems related to this feature but is not cross-referenced. Clarifying the relationship between the toggle, keywords, and this setting would be very helpful.