Back to Details

grey-haven-tool-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tool Design Skill

工具设计技能

Design effective MCP tools and Claude Code integrations using the consolidation principle.
运用整合原则设计高效的MCP工具与Claude Code集成。

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.
工具越少 = 成功率越高
Vercel d0通过将工具从17个精简至2个，成功率从80%提升至100%。这并非巧合——而是架构设计的成果。

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
  1. 减少决策空间 - 模型能更频繁地选择正确工具
  2. 简化上下文 - 每个工具的说明文本更少
  3. 优化参数处理 - 聚焦关键参数而非面面俱到
  4. 明确意图 - 工具用途清晰无歧义

Tool Count Impact

工具数量的影响

Tool CountExpected SuccessExample
1-395-100%Vercel d0 (2 tools)
4-785-95%Focused agent
8-1570-85%General assistant
15+<70%Kitchen sink
工具数量预期成功率示例
1-395-100%Vercel d0（2个工具）
4-785-95%专注型Agent
8-1570-85%通用助手
15+<70%面面俱到型

What's Included

包含内容

Examples (
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
  • MCP整合 - 真实的工具精简前后对比
  • Grey Haven模式 - Grey Haven MCP服务器如何遵循整合原则
  • 反模式 - 常见的工具设计错误

Reference Guides (
reference/
)

参考指南（
reference/
）

  • Consolidation guide - Complete tool reduction methodology
  • MCP best practices - Naming, parameters, descriptions
  • Decision framework - When to use tools vs agents vs skills
  • 整合指南 - 完整的工具精简方法论
  • MCP最佳实践 - 命名、参数、描述规范
  • 决策框架 - 工具、Agent与技能的适用场景判断

Checklists (
checklists/
)

检查表（
checklists/
）

  • Tool audit checklist - Evaluate existing tool sets
  • New tool checklist - Before adding a new tool
  • 工具审计检查表 - 评估现有工具集
  • 新工具检查表 - 添加新工具前的核查项

Key Patterns

关键模式

1. Architectural Reduction

1. 架构级精简

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
精简前（17个工具）：
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
精简后（2个工具）：
file_operation(action, path, content?, options?)
directory_operation(action, path, options?)
成果：成功率从80%提升至100%

2. Parameter Consolidation

2. 参数整合

Instead of many tools with few parameters, use few tools with structured parameters.
Before (5 tools):
typescript
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):
typescript
search(options: {
  query: string
  type: 'code' | 'files' | 'content'
  path?: string
  regex?: boolean
})
无需为少量参数设置多个工具，而是用少量工具搭配结构化参数。
精简前（5个工具）：
typescript
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)
精简后（1个工具）：
typescript
search(options: {
  query: string
  type: 'code' | 'files' | 'content'
  path?: string
  regex?: boolean
})

3. MCP Fully-Qualified Naming

3. MCP全限定命名

Use prefixes to prevent collisions and clarify scope:
mcp__firecrawl__search          // External MCP
mcp__linear__create_issue       // External MCP
search                          // Claude Code native
使用前缀避免冲突并明确范围：
mcp__firecrawl__search          // 外部MCP
mcp__linear__create_issue       // 外部MCP
search                          // Claude Code原生工具

4. Tool vs Agent Decision

4. 工具与Agent的决策判断

Use Tool WhenUse Agent When
Single operationMulti-step workflow
Deterministic resultJudgment required
Fast execution (<1s)Complex reasoning
Simple I/OContext accumulation
适用工具的场景适用Agent的场景
单一操作多步骤工作流
结果可确定需要判断决策
执行快速（<1秒）复杂推理需求
简单输入输出需要上下文积累

Grey Haven MCP Integration

Grey Haven MCP集成

Grey Haven uses these MCP servers effectively:
ServerToolsPurpose
firecrawl5Web scraping, search
linear12Issue/project management
playwright15Browser automation
context72Documentation lookup
filesystem10File operations
Grey Haven已高效运用以下MCP服务器：
服务器工具数量用途
firecrawl5网页爬取、搜索
linear12事项/项目管理
playwright15浏览器自动化
context72文档查询
filesystem10文件操作

Consolidation Opportunities

整合优化机会

Even well-designed MCPs can be wrapped for consolidation:
typescript
// 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
即使设计精良的MCP也可通过封装实现整合：
typescript
// 无需暴露全部15个playwright工具
// 可创建3个工作流级别的工具：

browser_navigate(url, options?)       // 导航 + 等待
browser_interact(selector, action)    // 点击/输入/选择
browser_extract(selector, format)     // 截图/文本/HTML提取

Anti-Patterns

反模式

1. Feature Creep

1. 功能蔓延

Adding tools "just in case" someone needs them.
Fix: Only add tools with proven usage patterns.
“以防万一”地添加工具。
修复方案：仅添加有明确使用场景的工具。

2. Granular Operations

2. 过度细分操作

Separate tools for each atomic operation.
Fix: Combine related operations with action parameters.
为每个原子操作单独设置工具。
修复方案：将相关操作合并，通过action参数区分。

3. Inconsistent Naming

3. 命名不一致

getUser
, 
fetch_project
, 
listTeams
, 
SEARCH_ISSUES
Fix: Consistent 
verb_noun
pattern: 
get_user
, 
list_projects
getUser
, 
fetch_project
, 
listTeams
, 
SEARCH_ISSUES
修复方案：采用统一的
动词_名词
格式：
get_user
, 
list_projects

4. Missing Descriptions

4. 缺少描述

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
  • 设计新的MCP服务器
  • 审计现有工具集
  • 提升Agent成功率
  • 降低模型的认知负荷
  • 优化Claude Code集成

Related Skills

相关技能

  • api-design-standards
    - REST/GraphQL patterns apply to tools
  • llm-project-development
    - Pipeline architecture
  • context-management
    - Managing context with tools
  • api-design-standards
    - REST/GraphQL设计模式同样适用于工具
  • llm-project-development
    - 流水线架构设计
  • context-management
    - 结合工具管理上下文

Quick Start

快速开始

bash
undefined
bash
undefined

Audit your tool set

审计你的工具集

cat checklists/tool-audit-checklist.md
cat checklists/tool-audit-checklist.md

Learn consolidation patterns

学习整合模式

cat reference/consolidation-guide.md
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
cat examples/mcp-consolidation-examples.md

---

**技能版本**：1.0
**核心指标**：17→2个工具 = 80%→100%成功率
**最后更新**：2025-01-15