[DOCS] Conflict between "Forced Tool Use" guidance and "Extended Thinking" compatibility requirements

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/agents-and-tools/tool-use/implement-tool-use.md - docs/en/about-claude/models/extended-thinking-models.md

Section/Topic

The "Forcing tool use" and "Guaranteed tool calls with strict tools" sections in the implement-tool-use.md guide.

Current Documentation

In implement-tool-use.md, the documentation states:

"any tells Claude that it must use one of the provided tools... tool allows us to force Claude to always use a particular tool."

It also provides a tip regarding Guaranteed tool calls with strict tools:

"Combine tool_choice: {"type": "any"} with strict tool use to guarantee both that one of your tools will be called AND that the tool inputs strictly follow your schema."

However, in extended-thinking-models.md (and the identical extended-thinking.md), it states:

"Tool use with thinking only supports tool_choice: {"type": "auto"} (the default) or tool_choice: {"type": "none"}. Using tool_choice: {"type": "any"} or tool_choice: {"type": "tool", "name": "..."} will result in an error because these options force tool use, which is incompatible with extended thinking."

What's Wrong or Missing?

The main "How to implement tool use" guide encourages the use of tool_choice: any or tool to increase reliability and "guarantee" tool calls. However, it fails to mention that this configuration is a breaking change that causes an API error if the user has enabled Extended Thinking.

Since many developers using tools for complex agentic tasks will naturally want to use the high-intelligence Extended Thinking models (like Claude 3.7 Sonnet or Claude 4.5), they are likely to follow the "Best Practices" in the tool use guide and unknowingly trigger runtime errors.

Suggested Improvement

Add a prominent warning in docs/en/agents-and-tools/tool-use/implement-tool-use.md under the "Forcing tool use" and "Guaranteed tool calls" sections.

Suggested Text:

Warning: Compatibility with Extended Thinking Forced tool use (any or tool) is currently incompatible with Extended Thinking. If you enable the thinking parameter in your request, you must use tool_choice: auto (default) or tool_choice: none. Attempting to force a tool call while thinking is enabled will result in an API error.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation:
• Building with extended thinking
• Examples from other projects:
• Most API documentations for breaking feature-collisions (like OpenAI's incompatibility between certain response_format types and stream_options) place warnings in both relevant sections, not just the "newer" feature's page.
• Impact: This is a high-priority fix because "Forced Tool Use" + "Extended Thinking" is a high-intent combination for developers building autonomous agents, leading to a high "First Time to Error" rate for new SDK users.