[DOCS] Incompatibility between Forced Tool Use and Extended Thinking

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use#forcing-tool-use - https://platform.claude.com/docs/en/build-with-claude/extended-thinking#feature-compatibility - https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool

Section/Topic

• The "Forcing tool use" subsection in the Tool Use guide and the "Quick start" section of the Computer Use tool guide.

Current Documentation

The How to implement tool use guide (https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use#forcing-tool-use) states:

"Note that when you have tool_choice as any or tool, we will prefill the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before tool_use content blocks..."

The Building with extended thinking guide (https://platform.claude.com/docs/en/build-with-claude/extended-thinking#feature-compatibility) states:

"Thinking isn't compatible with... forced tool use."

What's Wrong or Missing?

There is a functional contradiction that leads to silent or confusing errors for developers.

Extended Thinking requires the model to emit a thinking block before the final answer/tool call. However, the documentation for Forced Tool Use (tool_choice: any or tool) states that the API uses a prefill mechanism that suppresses all content blocks (including text and, implicitly, thinking) prior to the tool_use block.

While the "Extended thinking" page briefly mentions this incompatibility under "Feature compatibility," the primary documentation for "Forcing tool use" does not. Furthermore, the Computer Use tool guide (https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool), which often involves complex reasoning where a developer might want to enable thinking, does not warn that forcing a tool call will cause the request to fail if a thinking budget is provided.

Suggested Improvement

A. Update the "Forcing tool use" section at https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use#forcing-tool-use with a warning block:

Warning: Incompatibility with Extended Thinking Forced tool use (tool_choice set to any or tool) is not compatible with Extended Thinking. Because forced tool use suppresses all content blocks before the tool call to ensure a direct invocation, it prevents the model from emitting the required thinking block. If you enable a thinking budget, you must use tool_choice: auto (or omit the parameter).

B. Add a similar note to the Computer Use tool guide at https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool:**

Note on Tool Choice: If you enable the thinking capability for Computer Use, ensure your tool_choice is set to auto. Using any or a specific tool name with a thinking budget will result in an API error.

Impact

High - Prevents users from using a feature

Additional Context

• This issue is frequently encountered by developers attempting to migrate complex agent loops to Claude 4.5 or 3.7 Sonnet where they want to ensure the agent uses a computer or bash tool immediately while also leveraging the increased reasoning power of extended thinking.
• Related documentation on pause_turn handling (https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause_turn) could also benefit from this clarification, as long-running turns often involve both tools and thinking.