[DOCS] Logical contradiction in "Toggling thinking modes in conversations" example

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/about-claude/models/extended-thinking-models#toggling-thinking-modes-in-conversations

Section/Topic

Section: "Toggling thinking modes in conversations" -> "Practical guidance"

Current Documentation

The documentation states: "The entire assistant turn must operate in a single thinking mode." It provides the following example of a valid toggle:

✓ Valid: Complete the assistant turn first `` User: "What's the weather?" Assistant: [tool_use] (thinking disabled) User: [tool_result] Assistant: [text: "It's sunny"] User: "What about tomorrow?" (thinking disabled) Assistant: [thinking] + [text: "..."] (thinking enabled - new turn) ``

What's Wrong or Missing?

The example contains a logical contradiction regarding how the Messages API handles requests.

Thinking mode (enabled/disabled) is a property of the API Request, not an inherent property of a user message. In the provided "Valid" example:

1. The line User: "What about tomorrow?" (thinking disabled) implies the API request containing that message has the thinking parameter omitted or disabled.
2. If that request has thinking disabled, the subsequent line Assistant: [thinking] + [text: "..."] (thinking enabled - new turn) is impossible, because the model cannot generate a thinking block if the request that triggered that turn had thinking disabled.

The documentation correctly notes that tool use loops are part of one turn, but the example fails to clarify that the "Thinking Mode" for the entire next turn is determined by the specific request that includes the new user message.

Suggested Improvement

Clarify that "Thinking Mode" is configured at the Request level. The example should be updated to show that the thinking configuration is changed for the new request.

Suggested Text:

✓ Valid: Enable thinking in a new Request
An assistant turn is completed when the model stops with end_turn. You can enable thinking in the subsequent request that continues the conversation.

// Request 1: (thinking: disabled)
User: "What's the weather?"
Assistant: [tool_use: get_weather]
// Request 2: (thinking: disabled)
User: [tool_result]
Assistant: [text: "It's sunny"] // Turn ends here

// Request 3: (thinking: enabled)
User: "What about tomorrow?" 
Assistant: [thinking] + [text: "Tomorrow will be..."] // Valid: New turn starts with thinking

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: [Building with extended thinking - How to use](/docs/en/about-claude/models/extended-thinking-models#how-to-use-extended-thinking)
• Context: In the Python and TypeScript SDKs, this distinction is important because client.messages.create (or query) is where the thinking budget is defined. A user message doesn't "have" a mode until it is wrapped in a request.