第 2 章 工具与MCP

学习目标

• 设计智能体难以误用、又节省 token 的工具，并通过评估确认改进效果。
• 通过分页、筛选、截断与引用管理工具结果的大小。
• 说明 MCP 中主机、客户端、服务器的角色，以及 2026-07-28 版规范的无状态模型。
• 区分协议错误与工具执行错误，设计能够引导恢复行动的错误信息。
• 根据信任边界处理工具注解、认证和 scope，授予最小权限。

引言

想象一下，你把 300 页内部系统手册交给新员工，说“需要的东西都在这里”。信息很完整，但他可能整整一周都在打开错误页面、混淆名称相近的菜单，并在错误代码面前停住。智能体拿到几十个直接封装现有 API 的工具时，遭遇的也是同样的问题。

工具是智能体观察世界的窗口，也是它的双手。本章首先讨论应该创建哪些工具，以及如何设计名称、参数、结果和错误。接着介绍 MCP 的结构、2026-07-28 版规范的变化，以及如何用注解、认证与 scope 划定权限边界。深入阅读则讨论工具增加到数百个时的策略，以及用代码调用工具的方式。

核心概念

工具是面向智能体的接口

正如为人设计界面称为 HCI（人机接口），Anthropic 把为智能体设计工具及其说明称为 ACI（智能体-计算机接口），并建议投入与 HCI 同样的精力。同一篇文章提到，在构建 SWE-bench 智能体时，团队花在工具优化上的时间，比花在整个提示词上的时间还多。

一个典型方法是防错设计（poka-yoke），也就是让错误难以发生。模型离开根目录后，总是弄错相对路径，团队便让工具只接受绝对路径，模型也能正确使用这种路径格式。与其在指令中写“注意路径”，不如直接消除会出错的输入形式。这与 SIM 卡采用缺角设计、防止反向插入的思路相同。

检查问题很简单：只看说明和参数，能否明确知道如何使用？是否有使用示例与边界情况？交给新入职开发者，会不会困惑？还应以大量输入测试，观察模型在哪些地方犯错。

选择合适的工具

Anthropic 的《Writing effective tools for agents》强调，工具更多并不代表结果更好。常见错误是把 API 端点逐个直接包装为工具。文章建议围绕影响较大的工作流，用少量工具整合多个步骤。例如，通讯录不要使用返回全部联系人的 list_contacts，而应使用 search_contacts 或 message_contact；日程则可以用一个 schedule_event 完成查找空闲时间和预约。

划定边界的标准是：“如果由人工负责，会不会一次处理完这件事？”拆得太细会增加组合负担和调用次数；合得太宽又会使参数过多，容易调用错误。应合并重叠的工具，并在名称与说明中明确区分看似相近、实际用途不同的工具。

名称、说明与参数

同时使用多个服务的工具时，名称是选择工具的第一条线索。同一篇文章建议采用命名空间，用服务或资源级前缀归类（asana_search、jira_search、asana_projects_search）。参数应仅凭名称就能看懂含义，例如 user_id 比 user 更好。

说明应写明工具会做什么、不会做什么、输入格式与单位，以及结果的含义。对于一个说明仅为“修改记录”、只接收 id 与 value 的 update 工具，按下例改进后即可看出区别。

{
  "name": "shipment_set_weight",
  "description": "记录出库前货物的实测重量。已出库货物不可修改。重量单位为千克，保留一位小数。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "shipment_number": { "type": "string", "description": "例如：SH-2026-004211" },
      "weight_kg": { "type": "number", "minimum": 0.1, "maximum": 30000 }
    },
    "required": ["shipment_number", "weight_kg"],
    "additionalProperties": false
  }
}

改进方案把单位放进参数名称，用 schema 限制允许范围，并在说明中明确不可修改的情况。对于时区等模型经常弄错的值，可以强制使用 ISO 8601 格式和时区标注，或只接受 UTC，从格式上消除犯错空间。schema 无法约束的业务规则（例如出库数量不能超过库存）应在服务器检查，因为格式正确的调用在业务上仍可能错误。

返回有意义的结果

工具结果是下一步行动的原料。同一篇文章建议，与其返回 uuid、256px_image_url、mime_type 等底层标识，不如返回名称等智能体可以直接使用的字段。文章指出，把难以辨认的标识转换为可读文本后，检索准确率提高了。如果下一次调用确实需要 ID，可以与名称一起返回。

也可以让智能体选择响应详细程度。通过 response_format 等枚举参数提供“concise”和“detailed”选项，通常使用简洁响应，只有需要 ID 时才选择详细响应。该文示例中的详细响应为 206 token，简洁响应为 72 token，约为前者的三分之一。

管理工具结果大小

结果越大，占用的上下文越多，也越容易提前出现第 3 章所讨论的上下文退化（context rot）。同一篇文章建议分页、范围选择、筛选，以及设置合理默认阈值的截断机制，并提到 Claude Code 默认将工具响应限制在 25,000 token。

截断时，必须在结果中写明已截断的事实与范围。否则，智能体会以为收到的 20 条就是全部。MCP 工具可以用 resource_link 返回供之后读取的 URI；如果定义了 outputSchema，则通过 structuredContent 返回结构化结果。存在输出 schema 时，服务器必须（MUST）返回符合 schema 的结果，客户端应当验证（SHOULD）；为保持向后兼容，还建议把相同 JSON 放入文本块。

错误是恢复指引

MCP 规范把工具错误分为两类。

规范建议客户端把工具执行错误传给模型，让它自行纠正（SHOULD）。执行错误以正常结果的结构返回。2026-07-28 版的所有结果都包含表示结果类型的 resultType，已完成的结果为 "complete"。

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "配送日期必须晚于今天。今天是 2026-10-20。" }],
    "isError": true
  }
}

好的错误信息会说明下一步行动。应区分需要修改输入、等待后再试、获取更多权限，还是转交人工。还有一种情况需要注意：超时等无法确认是否已经执行的错误。付款请求可能已经处理，只是响应丢失，此时正确指引应是“查询处理结果”，而不是“重试”。错误信息中不要包含内部堆栈或敏感值。

有副作用的工具：预览与确认执行

查询工具调用错误通常只损失 token，修改工具则会改变外部系统的状态。对难以撤销的修改，分离预览与确认执行很有效。

1. 准备工具计算并返回修改对象、目标值与影响（金额、收件人、数量），同时签发一个短期有效的预览标识。
2. 由人工或策略检查确认预览内容。
3. 确认执行工具只接收预览标识，服务器严格按该标识对应的内容执行。
4. 同一标识即使确认两次，也只产生一次效果（幂等性）。

这种结构消除了审批内容与执行内容不一致的空隙，也能阻止重试演变为重复执行。使用绝对值（“将日预算设为 30 万韩元”）而不是相对值（“增加 10%”），也是同样的防错设计，因为同一请求即使到达两次，结果也相同。

MCP 的组成

MCP（Model Context Protocol）是连接 LLM 应用与外部数据、工具的开放协议。消息遵循 JSON-RPC 2.0 格式，参与者有三类。

服务器提供三种能力：资源（供用户或模型使用的上下文与数据）、提示词（面向用户的模板消息与工作流）、工具（由模型执行的函数）。客户端可以提供信息征集机制（elicitation），让服务器向用户请求补充信息。2026-07-28 版将 Roots、Sampling、Logging 标为已弃用（Deprecated），意思是暂时仍可运行，但新实现不应引入。规范给出的替代方式分别是：通过工具参数或服务器设置传递目录；直接对接 LLM 提供商 API；通过标准错误输出或 OpenTelemetry 记录日志。

按规范的安全原则，应把工具视作任意代码执行。建议主机在调用工具前获得用户的明确同意，并让用户能够拒绝调用（SHOULD）。

2026-07-28 版规范：无状态与句柄

这一版最大的变化是 MCP 成为无状态（stateless）协议。处理所需的信息全部包含在请求内，服务器不得（MUST NOT）从同一连接的先前请求中取得协议版本、客户端能力、身份等上下文。因此，所有客户端请求都必须在 _meta 中包含 io.modelcontextprotocol/protocolVersion 与 io.modelcontextprotocol/clientCapabilities；缺少时，服务器以无效参数错误（-32602）拒绝。规范也建议携带客户端名称和版本（io.modelcontextprotocol/clientInfo），但这是自行申报的值，不得用于安全判断。旧版的 initialize 握手和会话 ID 头已被移除，新增了让服务器声明支持版本与能力的 server/discover。即使 stdio 进程仍然打开，也不代表一个对话或会话。

如果需要跨多次调用保存状态（购物车、打开的浏览器、数据库事务），创建工具应返回明确的句柄，后续调用把句柄作为参数传入。规范的非规范性指引如下。

• 在需要认证的服务器中，句柄只是标识，本身不代表访问权限。每次调用都应将调用者权限与句柄对应的对象核对。
• 句柄应是不暴露内部结构的不透明标识，保留期限应写在创建工具的说明中。
• 对于已过期或未知句柄，应返回说明该情况的工具执行错误，让模型重新创建。

处理过程中需要补充用户输入时，使用多轮往返请求（MRTR）。服务器在 resultType: "input_required" 的结果中携带所需请求与不透明的 requestState，客户端填入响应后，以新 ID 重新发送原请求。因为 requestState 会经过客户端，服务器应将其视为可能遭篡改的输入；如果它会影响权限或业务逻辑，就必须保护其完整性（MUST）。信息征集机制（elicitation）有两种模式：表单模式在客户端界面收集输入，URL 模式把用户引导到外部页面。表单模式不得请求密码、API 密钥、token 或付款信息；这类信息应使用不经过客户端的 URL 模式收集。

传输、取消与长时任务

MCP 有两种标准传输：stdio，由客户端把服务器作为子进程启动，通过标准输入输出通信；以及 Streamable HTTP，通过 HTTP 与远程服务器通信。旧的 HTTP+SSE 传输已被弃用。

取消和超时因传输方式而异。对 Streamable HTTP，关闭请求的响应流即表示取消；客户端连接断开时，服务器必须将该请求视为已取消。2026-07-28 版移除了流恢复功能，因此断开的请求必须用新 ID 重新发送。stdio 则发送 notifications/cancelled。规范建议为所有请求设置超时，并补充：收到进度通知（progress）时可以重新计时，但无论是否有进度通知，都应始终强制执行最大超时限制（SHOULD）。

把耗时数分钟乃至数小时的任务绑在单个连接上，很容易受中间代理超时或客户端重启影响。使用官方 Tasks 扩展后，服务器返回持久化任务句柄，而不是最终结果；客户端通过 tasks/get 查询状态（working、input_required、completed、failed、cancelled），重启后也能用同一 ID 继续。只有双方都声明支持时，才能使用这一扩展。

工具注解与信任

工具定义包含 name、title、description、inputSchema、outputSchema、annotations 等字段。规范建议名称长度为 1～128 个字符，只使用英文字母、数字、下划线、连字符与半角句点（.）。汇集多个服务器的工具时可能重名，因此规范建议采用服务器标识前缀等区分策略，并提醒 serverInfo 中的服务器名称不保证唯一，不能依赖它。

注解（annotations）是描述工具行为的提示。

请注意默认值是保守的：没有任何注解的工具，应被假定为会改变环境、可能有破坏性、能够与外部世界交互。规范还警告，除非来自可信服务器，否则客户端必须把注解视为不可信（MUST）。注解是服务器的自我陈述，不是保证书。自动批准等权限决定应与服务器信任等级和主机策略绑定。

认证与最小权限

规范中认证的适用范围因传输方式而异。对于基于 HTTP 的传输，建议遵循 MCP 授权（Authorization）规范（SHOULD）；对于 stdio，则建议不要套用该规范，而应从运行环境取得凭据。

安全最佳实践文档的核心规则如下。

scope 是 token 允许执行的操作范围。与其给一把万能钥匙，不如只给当前需要的房间钥匙，需要时再增加，这样丢失后的损害更小。tools/list 不得因连接不同而变化，但可以因请求授权不同而变化，所以服务器可以只展示调用者 scope 允许的工具。不过，隐藏只是便利措施，真正的阻断依赖每次调用时的服务器端权限检查。

人工审批与安全要求

规范对工具安全的要求，分别由服务器和客户端承担。

哪些调用需要人工确认，将在第 5 章讨论。这里先记住：确认界面必须展示实际将发送的输入。只问“要发送邮件吗”，就连收件人已经改变的调用也可能通过。

深入阅读

工具增加到数百个时

接入多个 MCP 服务器后，仅工具定义就可能占据大量上下文。MCP 客户端最佳实践文档建议采用渐进式发现（progressive discovery）：主机接收工具定义，但不立刻放入上下文，而是通过轻量的 search_tools 元工具查找所需工具，再加载其完整定义。文档举出了列表（名称与一行说明）、详情（单个工具的完整 schema）、执行三个层次，并建议当工具定义超过上下文窗口的一定比例（例如 1%～5%）时切换。检索可使用关键词、嵌入、小模型选择，或这些方法的组合；有些模型提供商提供内置工具搜索。

一个陷阱是提示词缓存。多数提供商会缓存包括 tools 数组在内的提示词前部，因此在对话中增删工具定义或改变顺序会破坏缓存。文档建议把新发现的定义追加在缓存点之后；或使用一个固定的 call_tool 元工具，接收工具名称与参数并代为调用，将所有调用都经由它发送，从而保持数组不变。规范建议 tools/list 按确定性顺序返回，也是同一原因。

模型用代码调用工具时

直接调用工具时，每次调用返回的完整结果都要经过模型。如果任务是读取数千行日志，为每一种不同的错误创建工单，那么模型就必须读完这数千行日志。编程式工具调用（code mode）则让模型编写用于调用工具的代码，再由沙箱运行这些代码，只把最终结果返回给模型。由于中间数据不再进入上下文，token 消耗和延迟都能大幅减少。

相应的代价是出现了代码执行这一新的攻击面。MCP 文档提出了六项条件：不允许沙箱直接访问网络，所有通信都要经过主机中介；凭据由主机掌握，不得暴露给生成的代码；不能因为批准了脚本，就把脚本内的所有调用都视为已获批准；对于另一个服务器而言，一个服务器返回的结果应被视为不可信的输入；限制代码的执行时间与内存用量；沙箱的输出必须经过验证和截断，之后才能交给模型。对于只有一两次调用的交互式任务，增加的复杂度可能超过收益，因此请先将这种方式用于大批量数据的筛选与汇总工作。

把工具变更作为契约管理

即使 schema 不变，说明中的一句话或某个结果字段的含义变化，也会改变智能体行为。因此，应把名称、说明、schema 和业务语义一起纳入版本管理，保留变更记录，并在部署前评估。Anthropic 建议，用真实任务测量执行时间、工具调用次数、token 和工具错误，并用单独留出的测试集（held-out test set）确认，避免只对评估集优化。关于研究系统的文章报告，借助重写工具说明的智能体，后续任务完成时间缩短了 40%。服务器改变列表时，可以用 notifications/tools/list_changed 通知，客户端此时应丢弃缓存列表并重新获取。

工作场景

浪潮广告：为预算修改工具加上安全措施

广告代理公司“浪潮广告”的运营智能体使用了直接封装广告平台 11 个 API 的工具。上季度出现两类事故：9 次误改名称相近的广告活动（“秋季特惠_搜索”和“秋季特惠_搜索_再访”），以及 3 次超时重试导致“日预算增加 20%”被执行两次。

团队考虑了三种方案。增加系统提示词中的提醒，上季度已经做过，因此被否决。保留 11 个工具、只完善说明，也被否决，因为无法消除相对值增加和重复执行这一结构性原因。最终选择重新设计工具。

查询合并为一个 campaigns_find(query, status)，结果包含活动名称、ID、当前日预算和负责人。修改拆成两步：budget_change_preview(campaign_id, new_daily_budget_krw) 只接受绝对值，返回修改前后金额、预计月支出，以及有效期 10 分钟的预览 ID；budget_change_apply(preview_id) 只接受预览 ID，同一 ID 即使到达两次，也只应用一次。相对原预算增加超过 50% 时，返回 isError: true，并提示“需要负责人审批，请使用审批请求工具”。超时后，智能体通过预览 ID 查询是否已应用，而不是重试。

团队把过去 12 起事故变形成 40 项任务，并另外留出 25 项新任务进行评估。两组中误改活动与重复增加预算均为 0 次，每项任务的工具调用次数从 4.8 次降至 2.6 次。

蔚蓝软件：重新划定部署 MCP 服务器的权限

开发平台企业“蔚蓝软件”构建了远程 MCP 服务器，让智能体查询部署状态，并在出问题时回滚。第一版只求快速实现：直接接收用户持有的 CI 系统 token 并传给 CI API；scope 只有一个 deploy:*；只要知道部署 ID，就能回滚任何人的部署。

安全审核指出三点问题：服务器接收并转发并非签发给自己的 token（token 透传）；只需查询的用户也拥有回滚权限（scope 过大）；把部署 ID 当成权限使用（将句柄视为认证）。

重新设计后，服务器只接受通过 MCP 授权签发给自己的 token，并验证受众（audience）。访问 CI API 时使用服务器自身凭据，但每次调用都向内部权限系统检查用户的部署权限，并在下游调用的审计记录中保留真实用户标识。最初只请求 deploy:read；首次尝试回滚时，要求 deploy:rollback，引导权限逐步提升。tools/list 按 scope 隐藏回滚工具，但回滚调用始终会在服务器再次检查。回滚工具添加了 destructiveHint: true；主机把内部服务器登记为可信服务器，再依据该注解展示确认界面。

被否决的方案是“在工具说明里写上‘请谨慎回滚’”，因为说明只是给模型的建议，不是权限边界。

易错点

1. “完整暴露所有 API 为工具，智能体就会自行选择。” 封装现有 API 能快速完成，看起来很有吸引力，但组合负担转移给了模型，相似工具也容易混淆。围绕工作流设计少量工具更合适。
2. “错误都应以协议错误抛出。” 这符合一般 API 习惯，看似自然，但模型能够纠正的业务错误，应以 isError 和具体说明返回，才能让它自行恢复。
3. “带有 readOnlyHint 就是安全的。” 这是规范定义的字段，看起来像官方保证，但注解是服务器的自我声明。不得依据不可信服务器的注解做权限决定。
4. “把收到的 token 原样传给下游 API 很方便。” 这种实现最简单，但属于规范禁止的 token 透传，会同时破坏审计追踪、速率限制与信任边界。
5. “截断结果就解决了大小问题。” token 数量虽少了，但如果不说明截断事实与范围，智能体会把部分当作全部并下结论。
6. “MCP 变成无状态，所以服务器不能保存状态。” 名称容易让人这样理解，但可以保存状态。只需将其绑定明确句柄而非连接，并逐个检查句柄权限。
7. “从列表中隐藏的工具无法调用。” 工具从界面消失，似乎已被阻断，但列表筛选只是便利措施，真正的阻断依赖每次调用时的服务器端权限检查。

要点速览

• 工具是 ACI，应从格式上消除会出错的输入（绝对路径、绝对值、含单位的名称）。
• 按工作流而非端点设计少量工具，并用命名空间区分。
• 结果提供下一步行动需要的字段，用 response_format 控制详细程度，用分页、筛选、截断提示和引用管理大小。
• 业务错误应返回 isError 与恢复指引；无法确认是否执行的错误，应先查询而非重试。
• 难以撤销的修改应拆分为预览与确认执行，并保证幂等性。
• 2026-07-28 版 MCP 是无状态协议，_meta 必须包含版本与能力，状态通过句柄管理，句柄不是权限。
• 无论是否收到进度通知，都强制执行最大超时限制；长时任务可考虑 Tasks 扩展。
• 注解默认值是保守的，不信任来自不可信服务器的注解。
• 禁止 token 透传，从最小 scope 逐步提升，每次调用都进行服务器端权限检查。

查阅官方文档

• Anthropic: Writing effective tools for agents — 工具选择、命名空间、有意义的结果、token 效率、错误与基于评估的改进
• Anthropic: Building effective agents — 附录中的 ACI 与防错设计
• MCP 2026-07-28: Specification — 组成部分与安全原则
• MCP 2026-07-28: Base protocol — 无状态模型、_meta、认证适用范围
• MCP 2026-07-28: Tools — 工具定义、结果、错误、状态句柄与安全要求
• MCP 2026-07-28: Key changes — 与旧版的差异、已弃用功能
• MCP: Security best practices — 禁止 token 透传、scope 最小化、句柄劫持与本地服务器
• MCP: Client best practices — 渐进式发现、缓存与编程式工具调用

自测

2-1. 从上下文成本和选择错误的角度，解释为什么方便人工开发者使用的 API，与适合智能体的工具会有所不同。

2-2. 选择响应详细程度的参数（如 response_format）解决什么问题？智能体何时应选择详细响应？

2-3. 工具截断结果后返回时，必须同时在结果中写明哪两项信息？缺少它们时，智能体会犯什么错误？

2-4. 在 2026-07-28 版规范中，列出服务器不得从同一连接的先前请求中取得的三类信息，并说明这些信息应放在哪里。

2-5. 客户端应如何看待没有任何注解的工具？请结合规范中的注解默认值解释。

2-6. 分别用一句话解释，为什么 token 透传会破坏审计追踪和速率限制。

2-7. 将内部图书借阅系统的“续借”功能设计为智能体工具。为避免误用，分别确定工具名称、参数（含格式）、一种业务错误及其消息，以及需要人工确认的条件。

实操练习