# Cognitive Tools Suite

The Cognitive Tools Suite is a collection of specialized tools designed to **format** structured cognitive outputs generated by an agent (LLM). These tools provide consistent presentation frameworks for different types of reasoning tasks, enhancing clarity and readability.

## Suite Overview

The Cognitive Tools Suite includes formatting tools for:

- **Think Tool**: Formats structured reasoning
- **Reflect Tool**: Formats retrospective analysis and insights
- **Compare Tool**: Formats systematic comparisons (including tables)
- **Critique Tool**: Formats critical evaluations
- **Brainstorm Tool**: Formats categorized idea generation
- **Debate Tool**: Formats multi-perspective analysis

## Key Benefits

1. **Consistent Formatting**: Ensures structured outputs like reasoning, comparisons, etc., are presented uniformly.
2. **Simplified Agent Task**: Allows the agent LLM to focus on generating the core content, delegating the final presentation wrapper to the tool.
3. **No External Dependencies**: Tools operate locally without external API calls.
4. **Visual Distinction**: Standardized titles and structure aid readability in the UI.
5. **Standardized Implementation**: All tools follow a similar, simple architecture.

## Implementation Architecture

Each cognitive tool now follows this pattern:

1. **Schema Definition**: Defines required parameters (topic/subject/challenge and the pre-generated content) using Zod.
2. **Execution Logic**: 
    - Validates that the required parameters (including the main content) are provided.
    - If valid: Trims the content, adds a standard title (e.g., `## 🧠 Thinking about: ...`), and wraps the resulting Markdown in a `ToolResult`.
    - If invalid or on other errors: Throws a standard `Error` to be handled by the API route.
3. **Minimal Formatting**: The tools primarily handle adding the title and basic trimming. Complex Markdown rendering (like tables) is expected in the input content and handled by the `ChatMarkdown` component.

## Integration

Cognitive tools can be added to any agent by including their names in the `nodes` list within the agent's `template.json`:

```json
{
  "nodes": ["think", "reflect", "critique", "compare", "brainstorm", "debate", /* other nodes */]
}
```

## Design Philosophy

The refactored Cognitive Tools Suite focuses on:

1. **Separation of Concerns**: Agent generates content, tool formats the presentation wrapper.
2. **Simplicity**: Tools have minimal logic – validate, trim, add title.
3. **Consistency**: Uniform structure and error handling across all tools.
4. **Standardization**: Relies on standard Markdown for content and standard error throwing.

## Usage Guidelines

For optimal results:

1. **Agent Instructions**: Instruct the agent LLM to generate the *full* cognitive output (reasoning, comparison, critique, etc.) first.
2. **Tool Call**: Instruct the agent to then call the *appropriate* cognitive tool, passing the generated content as the required parameter (e.g., `reasoning`, `comparison`, `analysis`).
3. **Content Structure**: Encourage the agent to use appropriate Markdown within the generated content (e.g., headings, lists, tables for comparisons) which will be rendered by the UI.

## Common Implementation Features

All cognitive tools now share:

1. **Standard Error Handling**: Throw standard `Error` objects on validation failure or exceptions.
2. **Simple Formatting**: Primarily add a standard title and trim whitespace.
3. **Parameter Validation**: Use Zod schemas to ensure required content is provided.
4. **Typescript Type Safety**: Strong typing throughout.

## Future Development

Potential future directions could include:

1. **More Sophisticated Formatters**: Tools that might parse and restructure the provided content more deeply (though this adds complexity).
2. **Visualization Tools**: Tools that format output specifically for charts or graphs.
3. **Workflow Tools**: Tools designed to manage multi-step cognitive processes explicitly. 