工具描述被严重低估了。它们是 Claude 用于工具选择的主要机制。如果你的描述模糊或重叠，选择就会变得不可靠。本领域教你如何做对。
01 工具接口设计
工具描述不是补充文档。它们是模型决定调用哪个工具的 唯一机制。
好的工具描述包含什么
- 工具做什么（主要用途）
- 期望什么输入（格式、类型、约束）
- 擅长处理的示例查询
- 边界情况和限制
- 明确的边界：何时用此工具 vs 类似工具
误路由问题
两个描述重叠或近乎相同的工具会导致选择混乱。考试呈现 get_customer 和 lookup_order，描述分别是"检索客户信息"和"检索订单信息" — 导致持续误路由。
正确的修复是改善描述。 不是少样本示例（用错误的根因换来的 token 开销）。不是路由分类器（第一步就过度工程化）。不是工具合并（工作量太大）。
考试偏好 低成本、高杠杆的修复作为第一步。
工具拆分
将通用工具拆分为目的明确的工具，定义输入/输出契约：
| 之前 | 之后 |
|---|---|
analyze_document | extract_data_points |
summarize_content | |
verify_claim_against_source |
系统提示冲突
系统提示中的关键词敏感指令可能创建意外的工具关联，覆盖精心编写的描述。更新工具描述后，始终检查系统提示是否存在冲突。
练习场景
智能体将"查看订单 #12345 的状态"路由到 get_customer 而非 lookup_order。两者的描述都说"检索 [实体] 信息"。修复： 扩展描述，明确每个工具的用途、接受的输入和使用时机。
02 结构化错误响应
MCP isError 标志
MCP 提供 isError 标志模式，用于将失败信息传回智能体。
四种错误类别
| 类别 | 描述 | 可重试？ | 示例 |
|---|---|---|---|
| 瞬时错误 | 超时、服务不可用 | 是 | 数据库连接超时 |
| 验证错误 | 输入格式无效或缺少字段 | 是（修复输入） | 日期格式错误 |
| 业务错误 | 违反策略 | 否 | 退款超出限额 |
| 权限错误 | 访问被拒绝 | 否（需要升级） | 凭证不足 |
包含结构化错误元数据：errorCategory、isRetryable 布尔值和人类可读的描述。对于业务错误，包含 retriable: false 和面向客户的友好解释。
关键区分
| 情况 | 发生了什么 | 正确响应 |
|---|---|---|
| 访问失败 | 工具无法连接数据源 | 考虑重试 |
| 有效空结果 | 工具成功查询，未找到匹配项 | 不要重试 — 这就是答案 |
混淆这两者会破坏恢复逻辑。考试直接测试这一点。
多智能体系统中的错误传播
- 子智能体对瞬时故障实施本地恢复
- 仅传播无法在本地解决的错误
- 传播时包含部分结果和已尝试的操作
练习场景
一个工具在客户查询后返回空数组。智能体重试 3 次然后升级给人工。实际问题是客户账户不存在。问题： 将有效空结果与访问失败混淆。修复： 区分"无法连接数据源"和"连接成功，未找到结果"。
03 工具分配与 tool_choice
工具过载问题
给智能体 18 个工具会降低选择可靠性。最佳：每个智能体 4-5 个工具，限定在其角色范围内。
- 综合智能体不应该有网络搜索工具
- 网络搜索智能体不应该有文档分析工具
tool_choice 配置
| 设置 | 行为 | 适用场景 |
|---|---|---|
"auto" | 模型决定是否调用工具或返回文本 | 通用操作（默认） |
"any" | 模型必须调用工具，自行选择哪一个 | 从多个 schema 中保证结构化输出 |
{"type": "tool", "name": "extract_metadata"} | 模型必须调用此特定工具 | 强制执行必要的第一步 |
跨角色的限定工具
对于高频简单操作，直接给需要的智能体一个受限工具。示例：综合智能体获得一个限定的 verify_fact 工具用于简单查询，复杂验证则通过协调器路由。
这避免了 85% 简单情况下的协调器往返延迟。
替换通用工具
不要给子智能体 fetch_url（可以获取任何内容），而是给它 load_document，仅验证文档 URL。
练习场景
综合智能体频繁将控制权返回给协调器进行简单事实验证，每个任务增加 2-3 次往返和 40% 的延迟。85% 的验证是简单查询。修复： 给综合智能体一个限定的 verify_fact 工具。
04 MCP 服务器集成
作用域层级
| 级别 | 位置 | 共享？ | 版本控制？ |
|---|---|---|---|
| 项目级 | 项目仓库中的 .mcp.json | 是（团队） | 是 |
| 用户级 | ~/.claude.json | 否（个人） | 否 |
所有已配置服务器的工具在连接时被发现，同时可用。
环境变量扩展
.mcp.json 支持 ${GITHUB_TOKEN} 语法。这将凭证保持在版本控制之外。每个开发者在本地设置自己的令牌。
MCP 资源
将内容目录（Issue 摘要、文档层级、数据库 schema）作为 MCP 资源暴露。让智能体无需探索性工具调用就能了解可用数据。减少不必要的查询。
构建 vs 使用决策
| 情况 | 方法 |
|---|---|
| 标准集成（Jira、GitHub、Slack） | 使用现有的社区 MCP 服务器 |
| 团队特定工作流 | 仅在社区服务器无法处理时构建自定义服务器 |
增强 MCP 工具描述以防止智能体偏好内置工具（如 Grep）而非更强大的 MCP 工具。
05 内置工具
Grep vs Glob
| 工具 | 搜索对象 | 用途 |
|---|---|---|
| Grep | 文件 内容 中的模式 | 查找函数调用者、定位错误消息、搜索 import |
| Glob | 按命名模式匹配文件 路径 | 按扩展名查找文件（**/*.test.tsx）、定位配置文件 |
考试故意设置使用错误工具浪费时间的场景。
Read / Write / Edit
| 工具 | 适用场景 |
|---|---|
| Edit | 使用唯一文本匹配的定向修改。快速、精确。 |
| Read + Write | 当 Edit 失败时的后备方案（非唯一文本匹配）。加载完整文件，写入完整修改后的文件。 |
增量式代码库理解
- 从 Grep 开始查找入口点（函数定义、import 语句）
- 使用 Read 跟踪 import 和追踪流程
- 不要预先读取所有文件 — 这是上下文预算的杀手
练习场景
查找所有调用已弃用函数的文件，并找到这些调用者的测试文件。正确顺序： 用 Grep 搜索函数名（找到调用者），用 Glob 匹配调用者文件名对应的测试文件。
06 动手构建
构建两个功能类似的 MCP 工具：
- 编写足够模糊的描述以导致误路由
- 用具体、差异化的描述修复它们
- 亲身体验差异
然后创建 3 个 MCP 工具：
- 覆盖全部四种错误类别的错误响应
- 在
.mcp.json中配置，使用环境变量扩展 - 用
tool_choice强制选择第一步