MCP Tool 是 Server 暴露的可执行操作，模型通过 Client 调用 Tool 来与外部系统交互。Tool 是 MCP 中最常用、也最需要仔细设计的能力类型。

一、基本定义

Tool 是 MCP Server 通过协议暴露给 Client 的可调用操作。每个 Tool 有：

• 名称（name）：唯一标识符
• 描述（description）：说明工具的功能和适用场景
• 输入 Schema（inputSchema）：使用 JSON Schema 定义参数结构
• 执行结果：返回给 Client 的结构化内容

Tool 的核心特征：

• 模型主动选择并调用
• 可以执行操作、产生副作用
• 接受参数化输入
• 返回结构化结果

二、为什么 Tool 是 MCP 的核心能力

Tool 是模型与外部世界交互的主要方式：

• 查询信息：搜索、读取、获取
• 执行操作：创建、修改、删除、发送
• 触发流程：启动任务、调用 API
• 计算处理：分析、转换、格式化

Tool 的设计质量直接影响：

• 模型能否正确选择工具
• 参数是否正确传递
• 结果是否可理解
• 系统是否安全可靠

三、Tool 的数据结构

一个 Tool 定义通常包含：

Tool {
  name: string          // 工具名称，唯一标识
  description: string   // 工具描述，影响模型选择
  inputSchema: object   // JSON Schema 定义的输入参数
}

Tool 调用结果通常包含：

ToolResult {
  content: Content[]    // 返回内容（文本、图片等）
  isError: boolean      // 是否为错误结果
}

具体字段以当前 MCP 规范版本为准。

四、Tool 分类

按操作性质分类

类型	特征	示例	风险等级
查询型 Tool	只读取数据，无副作用	搜索笔记、获取天气	低
修改型 Tool	创建或修改数据	创建笔记、更新记录	中
高风险 Tool	不可逆操作或影响外部系统	删除文件、发送消息	高
长耗时 Tool	执行时间较长	数据分析、批量处理	中
批处理 Tool	处理多个对象	批量更新、批量导出	中-高

按副作用分类

类型	是否有副作用	是否幂等	是否需要确认
纯查询	否	是	否
幂等写入	是	是	视情况
非幂等写入	是	否	建议
不可逆操作	是	否	必须

五、Tool 设计维度

名称设计

好的名称应该：

• 简洁：search_notes 而非 perform_a_search_operation_on_notes
• 明确：create_note 而非 handle_note
• 一致：统一使用 verb_noun 格式
• 无歧义：delete_file 和 archive_file 有明确区别

命名规范建议：

✅ search_notes, create_note, update_section, check_links
❌ doSearch, handleNote, process, thing1

描述设计

描述是影响模型选择准确性的关键因素。

好的描述应该包含：

• 做什么：一句话说明功能
• 何时使用：适用场景
• 何时不使用：避免误选
• 关键参数说明：重要参数的含义
• 返回值说明：返回什么信息
• 副作用说明：是否有外部影响

✅ "搜索 Obsidian Vault 中的笔记，支持按标题、内容和标签搜索。
   返回匹配的笔记列表，包含标题、路径和摘要。
   不创建或修改笔记。如需修改请使用 update_note。"

❌ "搜索"
❌ "这个工具可以帮你搜索很多东西，非常强大"

输入 Schema 设计

使用 JSON Schema 定义参数：

• 区分必填和可选参数
• 每个参数添加描述
• 限制参数值范围（enum、minLength、maxLength、pattern）
• 避免过度嵌套
• 提供默认值（如果适用）

好的参数设计：
{
  "query": "搜索关键词（必填）",
  "scope": "搜索范围：title, content, tags（可选，默认 all）",
  "limit": "最大返回数量（可选，默认 10，最大 50）"
}

差的参数设计：
{
  "data": "数据",
  "options": "选项",
  "config": { "nested": { "deeply": { "value": "值" } } }
}

输出设计

• 结果结构化，便于模型解析
• 返回适量信息（不过多也不过少）
• 错误信息可理解
• 大结果集分页
• 考虑 Token 消耗

幂等性设计

操作	幂等性	说明
读取操作	天然幂等	多次读取结果相同
设置操作	可设计为幂等	set_status("active") 多次执行结果相同
追加操作	非幂等	每次追加都会新增
递增操作	非幂等	每次递增都会变化

对于非幂等操作：

• 提供幂等键（idempotency key）
• 或明确告知模型该操作不可重复

六、Tool 调用流程

七、高级特性

用户确认

高风险操作需要用户确认：

风险分级：
- 低风险：自动执行（查询、读取）
- 中风险：通知用户（创建、修改）
- 高风险：等待确认（删除、发送、支付）

超时处理

• 每个 Tool 调用设置超时时间
• 长耗时 Tool 支持进度通知
• 超时后支持取消

错误处理

Tool 执行可能遇到：

• 参数错误（Invalid params）
• 权限不足（Permission denied）
• 外部依赖失败（External service error）
• 超时（Timeout）
• 内部错误（Internal error）

错误信息应该：

• 对人类可读
• 对模型可理解
• 不包含敏感信息
• 提供恢复建议

工具组合

多个 Tool 可以组合完成复杂任务：

示例：代码审查工作流
1. search_code(query) → 找到相关代码
2. read_file(path) → 读取文件内容
3. analyze_code(content) → 分析代码质量
4. submit_review(comment) → 提交审查意见

八、Tool 与业务 API 的区别

维度	MCP Tool	业务 API
调用者	模型（通过 Client）	程序代码
参数来源	模型生成	程序构造
结果消费者	模型（理解语义）	程序（解析结构）
描述目的	帮助模型选择	帮助开发者理解
错误处理	模型需要理解并调整	程序 try-catch
安全模型	需要防止提示注入和越权	需要防止注入和越权

九、设计原则

1. 单一职责：每个 Tool 做一件事
2. 描述优先：投入足够精力写好描述
3. 参数最小化：只暴露必要的参数
4. 结果可理解：返回模型能理解和利用的信息
5. 安全分级：根据风险等级设计确认机制
6. 幂等优先：尽量设计为幂等操作
7. 错误友好：错误信息帮助模型调整行为

十、常见误区

1. 描述过于简略：模型无法正确选择工具
2. 参数过于复杂：模型难以正确构造参数
3. 返回信息过多：消耗大量 Token
4. 不区分风险等级：所有操作都同等对待
5. 忽视幂等性：重复调用导致数据异常
6. Tool 粒度不当：一个 Tool 做太多事或太少事
7. 错误信息不友好：模型无法从错误中学习
8. 不测试模型选择：假设模型能自动理解工具用途

十一、实践检查清单

• 每个 Tool 有清晰的名称和描述
• 描述包含"做什么"和"何时不使用"
• 参数使用 JSON Schema 定义
• 必填和可选参数区分明确
• 返回值结构化且信息适量
• 高风险操作有确认机制
• 错误信息可理解且不泄露敏感信息
• 测试了模型对工具的选择准确性
• 考虑了超时和取消
• 考虑了幂等性

十二、完整示例

以 KnowledgeOS MCP Server 的 Tool 为例：

搜索笔记 Tool

名称：search_notes
描述：搜索 Obsidian Vault 中的笔记。支持按标题、内容和标签搜索。
     返回匹配的笔记列表。不创建或修改笔记。
参数：
  - query (string, required): 搜索关键词
  - scope (enum: title/content/tags/all, optional, default: all)
  - limit (integer, optional, default: 10, max: 50)
返回：匹配的笔记列表，包含 title, path, snippet
风险：低（只读操作）
幂等：是

创建笔记 Tool

名称：create_note
描述：在指定路径创建新的 Markdown 笔记。如果文件已存在会失败。
参数：
  - path (string, required): 笔记路径（相对于 Vault 根目录）
  - content (string, required): 笔记内容（Markdown 格式）
  - create_dirs (boolean, optional, default: false): 是否自动创建目录
返回：创建的笔记路径和大小
风险：中（写入操作）
幂等：否（重复创建会失败）
确认：建议

十三、与其他概念的关系

• MCP基础：Tool 在 MCP 中的基本定位
• MCP Server设计：Tool 如何注册到 Server
• MCP Client设计：Client 如何调用和管理 Tool
• MCP资源模型：Resource 与 Tool 的区别
• MCP Prompt能力：Prompt 与 Tool 的区别
• MCP能力设计指南：如何选择 Tool vs Resource vs Prompt
• MCP安全边界：Tool 的安全考量
• MCP与Agent协作：Agent 如何选择和使用 Tool

十四、适用边界

Tool 适用于：

• 需要执行操作或产生副作用的场景
• 需要参数化输入的场景
• 需要模型主动选择的场景
• 需要实时执行结果的场景

不适用于：

• 纯数据暴露（更适合 Resource）
• 可复用的交互模板（更适合 Prompt）
• 不需要模型选择的后台任务
• 实时流式数据（当前 MCP 以请求-响应为主）

十五、延伸思考

1. 如何评估 Tool 描述的质量？
2. 如何实现 Tool 的自动发现和组合？
3. 如何处理 Tool 数量增长导致的模型选择困难？
4. 是否需要在协议层面支持 Tool 的进度反馈？

十六、参考资料

• MCP 官方规范 - https://modelcontextprotocol.io/specification
• Tool Use 最佳实践 - https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview
• JSON Schema - https://json-schema.org/