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