# Cerebrum -- MCP Tool Specification

This document specifies the MCP-discoverable tools exposed by the `cerebrum` module. These tools provide case-based reasoning capabilities through semantic retrieval and case storage in the CaseBase.

## General Considerations

- **Auto-Discovery**: Tools use the `@mcp_tool(category="cerebrum")` decorator and are auto-discovered via the MCP bridge.
- **Dependencies**: Requires the `cerebrum` module's `CaseBase`, `CaseRetriever`, and `Case` classes.
- **Error Handling**: All tools return `{"status": "error", "message": "..."}` on failure.

---

## Tool: `query_knowledge_base`

### 1. Tool Purpose and Description

Perform semantic retrieval from the CaseBase. Searches for cases matching a conceptual query and returns ranked results with similarity scores.

### 2. Invocation Name

`query_knowledge_base`

### 3. Input Schema (Parameters)

| Parameter Name | Type | Required | Description | Example Value |
| :--- | :--- | :--- | :--- | :--- |
| `query` | `string` | Yes | The semantic concept or question to search for | `"error handling patterns"` |
| `limit` | `integer` | No | Maximum number of cases to return (default: 5) | `10` |

### 4. Output Schema (Return Value)

| Field Name | Type | Description | Example Value |
| :--- | :--- | :--- | :--- |
| `status` | `string` | `"success"` or `"error"` | `"success"` |
| `results` | `array` | List of matching case objects | `[{"id": "...", "features": {...}, "solution": "...", "similarity_score": 0.92}]` |
| `count` | `integer` | Number of results returned | `3` |
| `message` | `string` | Error description (only on error) | `"Knowledge base query failed: ..."` |

Each item in `results` contains:

| Field Name | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | Unique case identifier |
| `features` | `object` | Feature dictionary of the case |
| `solution` | `string` | The paired resolution or insight |
| `similarity_score` | `number` | Similarity to the query (0.0--1.0) |

### 5. Error Handling

- CaseBase initialization failures return an error status with the exception message.
- Retrieval failures (e.g., empty case base, invalid query) return an error status.

### 6. Idempotency

- **Idempotent**: Yes (for the same case base state)
- **Explanation**: The same query against the same CaseBase content returns the same results. Results may differ if cases have been added or removed between calls.

### 7. Usage Examples

```json
{
  "tool_name": "query_knowledge_base",
  "arguments": {
    "query": "authentication middleware design",
    "limit": 3
  }
}
```

### 8. Security Considerations

- Query strings are used as feature filters and should be validated to prevent injection into the retrieval pipeline.
- Returned case data may contain sensitive solution information; consumers should handle results appropriately.

---

## Tool: `add_case_reference`

### 1. Tool Purpose and Description

Store intelligence context directly into the CaseBase. Creates a new case with a concept feature and a paired solution string.

### 2. Invocation Name

`add_case_reference`

### 3. Input Schema (Parameters)

| Parameter Name | Type | Required | Description | Example Value |
| :--- | :--- | :--- | :--- | :--- |
| `concept` | `string` | Yes | The problem or concept feature string | `"retry logic for HTTP 429"` |
| `solution` | `string` | Yes | The paired resolution or insight | `"Use exponential backoff with jitter, max 5 retries"` |

### 4. Output Schema (Return Value)

| Field Name | Type | Description | Example Value |
| :--- | :--- | :--- | :--- |
| `status` | `string` | `"success"` or `"error"` | `"success"` |
| `message` | `string` | Confirmation or error description | `"Case stored successfully"` |
| `case_id` | `string` | Unique identifier of the stored case (only on success) | `"c8f2e1a0-..."` |

### 5. Error Handling

- CaseBase initialization failures return an error status.
- Case construction or storage failures return an error status with the exception message.

### 6. Idempotency

- **Idempotent**: No
- **Explanation**: Each call creates a new case with a unique ID, even if the same concept and solution are provided.

### 7. Usage Examples

```json
{
  "tool_name": "add_case_reference",
  "arguments": {
    "concept": "database connection pooling",
    "solution": "Use connection pool with max_size=20, timeout=30s, health_check_interval=60s"
  }
}
```

### 8. Security Considerations

- Both `concept` and `solution` are stored as-is in the CaseBase. Callers should avoid storing secrets, credentials, or PII.
- Input strings should be validated for length and content before storage.

---

## Tool: `cerebrum_run_free_energy_loop`

### 1. Tool Purpose and Description

Run a free-energy minimization loop with an active inference agent. Creates a default 2-state generative model and iterates until variational free energy converges or the step limit is reached.

### 2. Invocation Name

`cerebrum_run_free_energy_loop`

### 3. Input Schema (Parameters)

| Parameter Name | Type | Required | Description | Example Value |
| :--- | :--- | :--- | :--- | :--- |
| `observation` | `object` | Yes | Initial observation dict | `{"sensor": 0.5}` |
| `max_steps` | `integer` | No | Max perception-action cycles (default: 50) | `100` |
| `threshold` | `number` | No | Free energy convergence threshold (default: 0.1) | `0.05` |
| `convergence_window` | `integer` | No | Consecutive steps below threshold (default: 3) | `5` |

### 4. Output Schema (Return Value)

| Field Name | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | `"success"` or `"error"` |
| `converged` | `boolean` | Whether the loop converged |
| `steps` | `integer` | Number of steps taken |
| `final_free_energy` | `number` | Final variational free energy |
| `action_history` | `array` | Sequence of actions selected |

### 5. Idempotency

- **Idempotent**: Yes (for the same observation and parameters)

---

## Navigation Links

- **Parent**: [Module README](readme.md)
- **Module Index**: [All Agents](../../AGENTS.md)
- **Home**: [Root README](../../../README.md)
