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

Reduced decision space - Model selects correct tool more often
Simpler context - Less instruction text per tool
Better parameter handling - Focused parameters vs kitchen-sink
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 few tools with structured parameters.

Before (5 tools):

search_code(query: string)
search_files(pattern: string)
search_in_file(file: string, query: string)
search_directory(dir: string, query: string)
search_with_regex(regex: string)

After (1 tool):

search(options: {
  query: string
  type: 'code' | 'files' | 'content'
  path?: string
  regex?: boolean
})

3. MCP Fully-Qualified Naming

Use prefixes to prevent collisions and clarify scope:

mcp__firecrawl__search          // External MCP
mcp__linear__create_issue       // External MCP
search                          // Claude Code native

4. Tool vs Agent Decision

Use Tool When	Use Agent When
Single operation	Multi-step workflow
Deterministic result	Judgment required
Fast execution (<1s)	Complex reasoning
Simple I/O	Context accumulation

Grey Haven MCP Integration

Grey Haven uses these MCP servers effectively:

Server	Tools	Purpose
firecrawl	5	Web scraping, search
linear	12	Issue/project management
playwright	15	Browser automation
context7	2	Documentation lookup
filesystem	10	File operations

Consolidation Opportunities

Even well-designed MCPs can be wrapped for consolidation:

// Instead of exposing all 15 playwright tools
// Create 3 workflow-level tools:

browser_navigate(url, options?)       // Navigate + wait
browser_interact(selector, action)    // Click/type/select
browser_extract(selector, format)     // Screenshot/text/html

Anti-Patterns

1. Feature Creep

Adding tools "just in case" someone needs them.

Fix: Only add tools with proven usage patterns.

2. Granular Operations

Separate tools for each atomic operation.

Fix: Combine related operations with action parameters.

3. Inconsistent Naming

getUser, fetch_project, listTeams, SEARCH_ISSUES

Fix: Consistent verb_noun pattern: get_user, list_projects

4. Missing Descriptions

Tools with cryptic names and no description.

Fix: Every tool needs clear description + examples.

Use This Skill When

Designing new MCP servers
Auditing existing tool sets
Improving agent success rates
Reducing cognitive load on models
Optimizing Claude Code integrations

Related Skills

api-design-standards - REST/GraphQL patterns apply to tools
llm-project-development - Pipeline architecture
context-management - Managing context with tools

Quick Start

# Audit your tool set
cat checklists/tool-audit-checklist.md

# Learn consolidation patterns
cat reference/consolidation-guide.md

# See real examples
cat examples/mcp-consolidation-examples.md

Skill Version: 1.0 Key Metric: 17→2 tools = 80%→100% success Last Updated: 2025-01-15

grey-haven-tool-design