Merge pull request #2191 from dgageot/board/fix-docker-agent-issue-2190-bfa77c62

docs: clarify think tool is for models without native reasoning

Author: dgageot

docs/concepts/multi-agent/index.md

@@ -305,7 +305,7 @@ toolsets:
 - **Keep agents focused** — Each agent should have a clear, narrow role
 - **Write clear descriptions** — The coordinator uses descriptions to decide who to delegate to
 - **Give minimal tools** — Only give each agent the tools it needs for its specific role
-- **Use the think tool** — Give coordinators the think tool so they reason about delegation
+- **Use the think tool when needed** — For models without native reasoning, give coordinators the think tool so they reason about delegation. Models with built-in thinking (e.g., via `thinking_budget`) don't need it
 - **Use the right model** — Use capable models for complex reasoning, cheap models for simple tasks
 - **Choose the right pattern** — Use `sub_agents` for hierarchical task delegation, `handoffs` for pipeline workflows and conversational routing
 

docs/guides/tips/index.md

@@ -169,16 +169,16 @@ agents:
 - Order by preference (best first)
 - Include a cheaper/faster model as last resort
 
-### Use Think Tool for Complex Tasks
+### Use Think Tool for Non-Reasoning Models
 
-The `think` tool dramatically improves reasoning quality with minimal overhead:
+The `think` tool provides a reasoning scratchpad for models that lack built-in thinking capabilities:
 
 ```yaml
 toolsets:
-  - type: think # Always include for complex agents
+  - type: think # Useful for models without native reasoning
 ```
 
-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.
 
 ## Security Tips
 

docs/tools/think/index.md

@@ -12,7 +12,7 @@ _Step-by-step reasoning scratchpad for planning and decision-making._
 
 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.
 
 ## Configuration
 
@@ -24,7 +24,7 @@ toolsets:
 No configuration options.
 
 <div class="callout callout-tip">
-<div class="callout-title">💡 Tip
+<div class="callout-title">💡 When to use
 </div>
-  <p>Include the think tool in every agent. It adds minimal overhead while significantly improving reasoning quality on complex tasks.</p>
+  <p>Use the think tool with models that don't have native reasoning capabilities. If your model already supports a <a href="{{ '/configuration/models/#thinking-budget' | relative_url }}">thinking budget</a>, you likely don't need this tool.</p>
 </div>