# Strategy for Maximizing MCP Tool Adoption

To ensure models and agents consistently utilize the Clew MCP tools, we must optimize for **Predictability**, **Efficiency**, and **Information Density**.

## 1. The Value Proposition
Agents avoid tools that:
- Return too little info (requiring 10 more calls).
- Return too much junk (context window overflow).
- Fail often.

Clew's Graph RAG offers a unique "Sweet Spot": **Targeted breadth.**
Instead of just "reading a file" (too dense) or "searching keywords" (too shallow), Clew returns **"The Code + Its Neighbors"**.

## 2. Validation: Vector vs. Graph
*Based on experimental data from `pallets/flask`.*

| Method | Query | Result Context | Usage Probability |
| :--- | :--- | :--- | :--- |
| **Codebase Scan** | "find app context" | Greps thousands of files. Slow. | **Low** (Last resort) |
| **Vector Search** | "app context" | Returns `ctx.py`. Model sees definition but not usage. | **Medium** (Good for definitions) |
| **Graph RAG** | "app context" | Returns `ctx.py` AND `Flask.dispatch_request` (Caller). | **High** (Contextual mastery) |

**Conclusion**: The Graph result provides the "Why" and "Where" alongside the "What".

## 3. Recommended Interface (The "Compelling" Choice)

Don't expose `search` and `traverse` as raw primitives. Agents struggle to chain them effectively.
Expose **High-Level Intent** tools.

### A. `search_codebase(query)`
*Description: "Find code definitions and see how they are used."*
- **Backend Logic**:
    1. Vector Search for `query` -> Top 3 Nodes.
    2. Parallel Graph Traverse (incoming `CALLS`, `IMPORTS`) for each node.
    3. Synthesize result: "Found `AppData` in `ctx.py`. Used by `Flask.py` in `dispatch_request`."
- **Why it wins**: One round-trip gives definition + usage.

### B. `explore_module(path)`
*Description: "Understand the dependencies and API of a module."*
- **Backend Logic**:
    1. Lookup File Node.
    2. Traverse `DEFINES` (classes/funcs), `IMPORTS` (dependencies).
- **Why it wins**: Summarizes a file's role without reading its raw bytes.

## 4. MCP Server Implementation
We should implement a standard MCP Server that wraps the Clew Engine API.

### Tool Definitions
```python
@mcp.tool()
async def search_codebase(query: str, context: str = None) -> str:
    """
    Search for code relevant to the query. 
    Returns the code snippets AND a summary of how they are referenced elsewhere in the codebase.
    Use this to understand feature implementation and usage patterns.
    """
    # ... calls /api/v1/search then /api/v1/traverse
```
