grey-haven-tool-design

# Tool Design Skill

Design effective MCP tools and Claude Code integrations using the consolidation principle.

## Core Insight

**Fewer tools = Higher success rates**

Vercel d0 achieved 80% → 100% success by reducing from 17 to 2 tools. This isn't coincidence—it's architecture.

## The Consolidation Principle

### Why Fewer Tools Work Better

1. **Reduced decision space** - Model selects correct tool more often
2. **Simpler context** - Less instruction text per tool
3. **Better parameter handling** - Focused parameters vs kitchen-sink
4. **Clearer intent** - Tool purpose is unambiguous

### Tool Count Impact

| Tool Count | Expected Success | Example |
|------------|------------------|---------|
| 1-3 | 95-100% | Vercel d0 (2 tools) |
| 4-7 | 85-95% | Focused agent |
| 8-15 | 70-85% | General assistant |
| 15+ | <70% | Kitchen sink |

## What's Included

### Examples (`examples/`)
- **MCP consolidation** - Real before/after tool reduction
- **Grey Haven patterns** - How Grey Haven MCP servers follow consolidation
- **Anti-patterns** - Common tool design mistakes

### Reference Guides (`reference/`)
- **Consolidation guide** - Complete tool reduction methodology
- **MCP best practices** - Naming, parameters, descriptions
- **Decision framework** - When to use tools vs agents vs skills

### Checklists (`checklists/`)
- **Tool audit checklist** - Evaluate existing tool sets
- **New tool checklist** - Before adding a new tool

## Key Patterns

### 1. Architectural Reduction

Before (17 tools):
```
create_file, read_file, update_file, delete_file,
list_directory, search_files, get_file_info,
create_folder, rename_file, move_file, copy_file,
get_permissions, set_permissions, watch_file,
compress_file, decompress_file, calculate_hash
```

After (2 tools):
```
file_operation(action, path, content?, options?)
directory_operation(action, path, options?)
```

**Result**: 80% → 100% success rate

### 2. Parameter Consolidation

Instead of many tools with few parameters, use