Cognitive Tools¶

A unified cognitive tool for structured reasoning, combining knowledge recall, logical reasoning, and creative exploration into a single flexible interface. Design inspired by Anthropic's Claude Think Tool and the cognitive psychology paper "Eliciting Reasoning in Language Models with Cognitive Tools".

Design Philosophy¶

Why a Unified Tool?¶

When interacting with AI models, we found that the model's "thinking" process is often a black box. The core goal of cognitive tools is: transform the model's thinking process from "black box" to "white box", making its reasoning visible, traceable, and correctable.

Design Evolution¶

Generation 1-3: From Complexity to Simplicity¶

We went through several iterations:

Single think() tool - Simple but lacked structure
Three tools (recall + reason + think) - Theoretically perfect but models struggled to choose
Two tools (recall + think) - Better, but recall was rarely used in practice

Generation 4: Current Design (Unified `think`)¶

Based on real-world usage feedback, we made a key insight: models almost never used recall separately. They preferred to dump everything into think. So we:

Merged recall into think - Added "recalling" as a thinking mode
Reordered parameters - thinking_mode → focus_area → thought_process (decide HOW to think before WHAT to think)
Simplified modes - Reduced from 9 to 6 core modes with clear use cases

Design philosophy:

One tool, many modes: Simpler mental model for the AI
Parameter order matters: Guide the model to decide thinking approach first
Modes as guidance: Predefined modes provide direction but don't limit creativity

Quick Start¶

from toolregistry_hub import ThinkTool

# Recall facts and knowledge (using "recalling" mode)
ThinkTool.think(
    thinking_mode="recalling",
    focus_area="Python async patterns",
    thought_process="FastAPI uses dependency injection. Project has blocking DB calls "
                    "that need to be converted to async for proper performance."
)

# Analyze a problem
ThinkTool.think(
    thinking_mode="reasoning",
    focus_area="Database performance optimization",
    thought_process="Blocking calls in async context cause performance issues. "
                    "Need to use asyncpg for async PostgreSQL. "
                    "Solution: Replace sync DB calls with async equivalents."
)

# Plan implementation steps
ThinkTool.think(
    thinking_mode="planning",
    focus_area="Migration strategy",
    thought_process="1. Identify all sync DB calls. 2. Install asyncpg. "
                    "3. Create async connection pool. 4. Migrate one endpoint at a time."
)

API Reference¶

`think(thinking_mode, focus_area, thought_process)`¶

Record your cognitive process - thinking, reasoning, planning, or recalling.

Parameters (in recommended order):

thinking_mode (str, optional): The type of cognitive operation. Choose this FIRST to guide your thinking.
- Core modes: "reasoning", "planning", "reflection"
- Memory mode: "recalling" (use this to dump knowledge/facts)
- Creative modes: "brainstorming", "exploring"
- Or use any custom string
focus_area (str, optional): What specific problem or topic you're thinking about. Set this SECOND.
thought_process (str): Your detailed stream of thoughts. Write this LAST. Can be long and messy.

Thinking Mode Descriptions:

Mode	Purpose	When to Use
`reasoning`	Logical analysis and deduction	Analyzing problems, evaluating options, making logical deductions
`planning`	Breaking down tasks, creating strategies	Designing implementation steps, creating action plans
`reflection`	Reviewing, verifying, self-correction	Checking your work, finding errors, correcting assumptions
`recalling`	Dumping knowledge/facts from memory	Gathering background info, stating what you know
`brainstorming`	Generating ideas freely	Exploring possibilities without judgment
`exploring`	Mental simulation, what-if scenarios	Imagining how things play out, considering hypotheticals

Usage Guide¶

Parameter Order Matters¶

The parameter order is intentional: thinking_mode → focus_area → thought_process

This guides the model to: 1. First decide HOW to think (mode) 2. Then narrow the scope (focus) 3. Finally write the actual thoughts

# Good: Mode first, then focus, then content
ThinkTool.think(
    thinking_mode="planning",           # 1. Decide approach
    focus_area="API refactoring",       # 2. Narrow scope
    thought_process="Step 1: ..."       # 3. Write thoughts
)

When to Use Each Mode¶

reasoning - For logical analysis:

ThinkTool.think(
    thinking_mode="reasoning",
    focus_area="Error diagnosis",
    thought_process="The error occurs after the database call. "
                    "Looking at the stack trace, it's a connection timeout. "
                    "This suggests the connection pool is exhausted..."
)

planning - For task breakdown:

ThinkTool.think(
    thinking_mode="planning",
    focus_area="Feature implementation",
    thought_process="1. Create the data model. 2. Add API endpoint. "
                    "3. Write tests. 4. Update documentation."
)

reflection - For self-correction:

ThinkTool.think(
    thinking_mode="reflection",
    focus_area="Previous assumption",
    thought_process="Wait, I assumed the error was in the database layer, "
                    "but looking more carefully, it's actually a network issue..."
)

recalling - For knowledge dump:

ThinkTool.think(
    thinking_mode="recalling",
    focus_area="Python 3.9 features",
    thought_process="Python 3.9 introduced dict merge operator |. "
                    "Also added removeprefix() and removesuffix() to strings. "
                    "Type hints got more flexible with built-in generics."
)

brainstorming - For idea generation:

ThinkTool.think(
    thinking_mode="brainstorming",
    focus_area="Performance optimization",
    thought_process="Could use caching. Maybe Redis? Or in-memory LRU? "
                    "What about lazy loading? Or precomputing results? "
                    "Database indexing might help too..."
)

exploring - For what-if scenarios:

ThinkTool.think(
    thinking_mode="exploring",
    focus_area="Architecture decision",
    thought_process="If we use microservices, we'd need service discovery. "
                    "That adds complexity but improves scalability. "
                    "What if we start monolithic and split later?"
)

Best Practices¶

1. Don't Summarize - Show the Full Process

# Good: Detailed thinking
ThinkTool.think(
    thinking_mode="reasoning",
    focus_area="Bug investigation",
    thought_process="First checking error logs... found timeout errors. "
                    "Timeout occurs in database queries. Looking at the query, missing index. "
                    "Adding index should solve it. But need to verify in test environment first..."
)

# Avoid: Too brief
ThinkTool.think(
    thinking_mode="reasoning",
    focus_area="Bug investigation",
    thought_process="Found it's an index issue"  # Lost the thinking process
)

2. Use Modes Appropriately

Choose the mode that best describes your current thinking type, but don't overthink it - modes are guidance, not restrictions.

Important Notes¶

What This Tool Does¶

Records various forms of cognitive processes
Makes thinking visible and traceable
Guides structured reasoning through modes

What This Tool Does NOT Do¶

Access external information or APIs
Make changes to code or data
Execute code or run tests
Perform actual computations

This tool is a recorder of thinking processes, not an executor. Its value lies in making thinking visible, traceable, and improvable.

References¶

Anthropic, "Claude Think Tool" - Original inspiration
Brown et al., "Eliciting Reasoning in Language Models with Cognitive Tools" - Theoretical foundation
Cognitive psychology research on knowledge vs. reasoning separation

Calculator - For actual mathematical computations
Todo List - For task tracking and planning
File Operations - For reading/writing files