docs: clarify think tool is for models without native reasoning#2191
Conversation
The documentation previously recommended including the think tool in every agent. In reality, it is only useful for models that lack built-in reasoning capabilities (e.g., smaller or older models). Models with native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a thinking budget — do not need it. Update docs across three files to reflect this: - docs/tools/think: reword overview and tip to explain when to use it - docs/guides/tips: rename section and clarify it targets non-reasoning models - docs/concepts/multi-agent: qualify the best-practice bullet as conditional Fixes docker#2190 Assisted-By: docker-agent
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This documentation PR clarifies when to use the think tool, which is a valuable improvement. However, there are terminology inconsistencies between this PR and the existing provider documentation that should be addressed.
Summary:
- 3 confirmed issues related to model terminology inconsistencies
- All issues are in documentation (no code bugs)
- The core message of the PR is correct, but the terminology needs alignment with provider docs
| The think tool is a reasoning scratchpad that lets agents think step-by-step before acting. The agent can write its thoughts without producing visible output to the user — ideal for planning complex tasks, breaking down problems, and reasoning through multi-step solutions. | ||
|
|
||
| This is a lightweight tool with no side effects. It's recommended for all agents — it improves the quality of reasoning on complex tasks at minimal cost. | ||
| This is a lightweight tool with no side effects. It is most useful for models that lack built-in reasoning or thinking capabilities (e.g., smaller or older models). For models that already support native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a thinking budget — this tool is unnecessary since the model can reason internally. |
There was a problem hiding this comment.
Terminology inconsistency with provider documentation
The term "extended thinking" is not used in the Anthropic provider documentation. The docs at docs/providers/anthropic/index.md refer to this feature as "Thinking Budget" and "Interleaved Thinking".
Similarly, "OpenAI o-series" is not documented anywhere in docs/providers/openai/index.md. The OpenAI provider docs list models like gpt-5, gpt-5-mini, gpt-4o, and gpt-4o-mini with thinking budget support, but no "o-series".
Suggestion: Use terminology consistent with the provider documentation:
- For Claude: "Claude with Thinking Budget" or "Claude Sonnet 4.5"
- For OpenAI: Refer to specific models like "gpt-5" or "gpt-5-mini" instead of "o-series"
- Consider linking to the provider docs for clarity
| ``` | ||
|
|
||
| The agent uses it as a scratchpad for planning and decision-making. | ||
| The agent uses it as a scratchpad for planning and decision-making. If your model already supports a [thinking budget]({{ '/configuration/models/#thinking-budget' | relative_url }}) (e.g., Claude with extended thinking, OpenAI o-series, Gemini with thinking enabled), you don't need this tool — the model can reason internally. |
There was a problem hiding this comment.
Same terminology issue in tips documentation
This line also uses "extended thinking" and "o-series" which are not found in the provider documentation. Please use the same terminology as documented in docs/providers/anthropic/index.md and docs/providers/openai/index.md.
3 participants
The documentation previously recommended including the think tool in every agent. In reality, it is only useful for models that lack built-in reasoning capabilities (e.g., smaller or older models). Models with native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a thinking budget — do not need it.
Changes
Fixes #2190