Learn Claude Code
s19

Think Tool

Tools & Execution

A Tool That Does Nothing

163 LOC4 toolsthink tool — returns input as-is
The simplest tool can be the most useful; giving the model permission to pause improves quality

s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ] s20 > s21

"The best tool is sometimes no tool — just think." -- Planning before acting prevents wasted iterations.

Harness layer: Tools & Execution -- A zero-side-effect "thinking" tool for deliberate reasoning.

Problem

Agents often "rush to act": immediately executing tool calls without pausing to consider overall strategy. This causes: wasting rounds on wrong approaches, missing hidden dependencies, losing direction in multi-step tasks. Human programmers sketch architecture diagrams before coding. Agents need this "scratchpad" capability too.

Solution

The agent's tool palette now includes a special entry:

┌─────────────────────┐
│  Available Tools     │
│  📂 read_file       │
│  📝 write_file      │
│  🔧 bash            │
│  💭 think  ←── NEW  │  ← Zero side-effects, doesn't count as action
└─────────────────────┘

Agent autonomously decides when to call think():
  1. Complex task received → analyze before acting
  2. Unexpected results mid-task → pause and reflect
  3. Decision point with multiple options → list tradeoffs

Core Concepts

Think Tool Definition

THINK_TOOL = {
    "name": "think",
    "description": (
        "Use this tool to think through a problem step-by-step. "
        "No external effect — just your internal scratchpad. "
        "Call this BEFORE acting when you face: "
        "1) Complex multi-step tasks, "
        "2) Ambiguous requirements, "
        "3) Decisions with multiple options."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "thought": {"type": "string", "description": "Your step-by-step reasoning"}
        },
        "required": ["thought"]
    }
}

Execution: Zero Side Effects

def execute_tool(name, args):
    if name == "think":
        # Key: does NOTHING! Just makes model's thinking visible
        return json.dumps({"status": "thought_recorded",
                          "note": "No action taken. Continue with your plan."})

The value isn't in the return — it's in the reasoning the model generates in the thought parameter. This reasoning stays in context, helping subsequent calls make better decisions.

Key Code

while True:
    response = client.messages.create(
        model=MODEL, system=SYSTEM_PROMPT, messages=messages,
        tools=[READ_FILE_TOOL, WRITE_FILE_TOOL, BASH_TOOL, THINK_TOOL],
    )
    for block in response.content:
        if block.type == "tool_use":
            if block.name == "think":
                print(f"💭 Agent thinking: {block.input['thought'][:200]}...")
                result = {"status": "thought_recorded"}
            else:
                result = execute_tool(block.name, block.input)
            messages.append({"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": block.id,
                 "content": json.dumps(result)}]})

What's New (s02 → s19)

Aspects02 (Tools)s19 (Think Tool)
PlanningNone — act immediatelyThink before acting
ObservabilityOnly see tool callsSee agent's reasoning process
Decision qualityModel intuitionStructured reasoning + tradeoff analysis
Implementation cost—< 10 lines of code
Side effectsAll tools have themThink has zero

Deep Dive: Design Decisions

Q1: How does Think Tool differ from Extended Thinking? Can they coexist?

Think Tool: model chooses to call, fully visible in messages, persists in context. Extended Thinking: API parameter forces activation, invisible to user, doesn't persist. They're complementary: Extended Thinking for deep per-call reasoning (internal), Think Tool for cross-step strategic planning (external, observable).

Q2: When does the agent autonomously call Think? How to guide it?

Through specific trigger conditions in the description. If the agent doesn't think enough, add to system prompt: "For complex tasks, ALWAYS call think() first." This is strong guidance, not forced — the model retains choice.

Q3: Think consumes tokens. Is it worth the cost?

~200-500 tokens per think call. If it saves 1+ wasted tool calls (500-3000 tokens each), it's net positive. Rule of thumb: not worth it for simple tasks, very worth it for complex tasks.

Q4: How important is the Think tool's description design?

Extremely important. The description is the model's sole basis for deciding when to use Think. Follow ACI principles: concise + specific trigger conditions + format guidance.

Q5: Can Think be used for automated testing?

Yes. Think content can be inspected in tests to verify agents plan before complex actions.

Try It

cd learn-claude-code
python agents/s19_think_tool.py

Recommended prompts:

  • "Write a REST API with auth, rate limiting, and database" — watch think() planning
  • "Fix the bug in this complex code" — watch analysis before fixing
  • "SQL or NoSQL for a social media app?" — watch tradeoff reasoning

References