很多团队做 Agent 工具调用时最自然的起点是**把现有的 REST API 包一层变成 MCP Server。**这很合理。现有 API 已经跑通了业务逻辑已经验证了包一层就能让 Agent 调用看起来是最快的路径。但这也是最容易踩坑的起点。因为 MCP Server 不是把 REST API 原样包装一遍。工具名称、描述、JSON Schema、粒度、错误信息每一个都会直接影响模型调用的准确率和上下文成本。这篇用 checklist 结构列出 Agent 工具调用设计最容易踩的 5 个坑以及每个坑该怎么避。---## 坑 1工具名称和描述写得像给人看的不是给模型看的### 坑是什么工具名称和描述是模型选择工具的唯一依据。但很多团队写工具描述时按给人看的文档来写——写业务背景、写使用场景、写注意事项就是没写清楚什么时候该用这个工具、什么时候不该用。### 更像真实现场的过程Agent 有两个工具- process_data描述是用于处理数据支持多种数据格式和业务场景- handle_request描述是用于处理请求覆盖常见业务流程用户问帮我查昨天的订单。模型在两个工具里选两个描述都和处理沾边模型选了 handle_request但这个工具其实是用来处理工单的不是查订单。### 为什么会踩- 描述写的是这个工具是什么不是什么时候该用- 描述里有业务背景但没有使用边界- 多个工具的描述有语义重叠模型分不清- 描述太长占上下文但关键信息没传递到### 怎么避Checklist- [ ] 描述里必须写什么时候用和什么时候不用- [ ] 相似工具要在描述里显式区分本工具用于 A不要用于 B- [ ] 描述控制在 2-3 句话不要写业务背景- [ ] 工具名称要语义明确不要用 process_data 这种泛化词- [ ] 描述里给出 1-2 个典型调用场景### 一句判断**工具描述是写给模型看的选型指南不是写给开发者看的业务文档。**---## 坑 2JSON Schema 太宽或太严模型要么猜不准要么传不进去### 坑是什么工具的参数定义靠 JSON Schema。Schema 写得太宽模型会乱传参数写得太严模型传不进去调用失败。### 更像真实现场的过程一个 send_email 工具Schema 定义 to 字段为 string没有格式约束。模型传了张三进去工具层没校验邮件发不出去。另一个 create_task 工具Schema 定义 priority 为枚举 [P0,P1,P2,P3]但没给默认值也没写不传时怎么处理。模型有时候传、有时候不传任务优先级忽高忽低。### 为什么会踩- Schema 太宽字段类型不限、格式不限、范围不限模型随便传- Schema 太严必填项太多、枚举值太窄模型传不进去- Schema 没给默认值模型不传时工具行为不确定- Schema 没写示例模型不知道参数长什么样### 怎么避Checklist- [ ] 字符串字段加格式约束email、url、date- [ ] 枚举字段给全枚举值并标注默认值- [ ] 必填项控制在最少能推导的不让模型传- [ ] 复杂字段给 1-2 个示例- [ ] Schema 和工具描述对齐——描述里说的参数Schema 里要有### 一句判断**Schema 是模型和工具之间的契约。太宽模型会乱传太严模型传不进去。**---## 坑 3工具数量爆炸全量注入上下文token 成本和选择错误同步上升### 坑是什么Agent 接的工具越来越多。10 个工具时还能全量塞给模型50 个工具时工具定义本身就占了几千 token模型选择准确率还会下降。### 更像真实现场的过程团队一开始接了 5 个工具Agent 调用准确率 95%。后来业务扩展工具涨到 40 个。团队把 40 个工具的定义全量塞给模型结果- 每次调用上下文多了 3000 token- 模型选择准确率掉到 78%——候选太多模型开始混淆- 高峰期 token 成本翻倍### 为什么会踩- 所有工具全量注入没有按需发现- 工具没有分类模型在所有工具里选- 工具描述重复或相似模型分不清- 没有工具检索机制每次都把全部 schema 塞进去### 怎么避Checklist- [ ] 工具按业务域分类不要平铺- [ ] 实现按需发现先检索候选工具再加载精确 schema- [ ] 工具描述做摘要化全量注入时只给摘要选中后再给完整 schema- [ ] 定期清理低频工具不要让历史工具一直占上下文- [ ] 监控工具数量和调用准确率的关系数量超过阈值时启动按需发现### 一句判断**工具不是越多越好。超过一定数量后全量注入既费 token 又降准确率。**---## 坑 4错误信息不可读模型收到报错后不知道怎么修正### 坑是什么工具调用失败时返回的错误信息是给开发者看的stack trace、错误码不是给模型看的。模型收到报错后不知道怎么修正要么重试同样的参数要么放弃。### 更像真实现场的过程Agent 调 create_order 工具传了 customer_id: abc。工具返回 {error: INVALID_FORMAT, detail: ValidationError: customer_id must be int, got str}。模型收到这个报错看不懂ValidationError是什么意思也不知道该怎么改。它可能会- 重试同样的参数以为只是网络问题- 把 customer_id 改成另一个字符串- 放弃调用告诉用户无法创建订单### 为什么会踩- 错误信息是技术语言不是模型能理解的- 错误信息没告诉模型该怎么修正- 错误信息没区分可重试和不可重试- 错误信息没给出正确参数应该长什么样### 怎么避Checklist- [ ] 错误信息用自然语言写说明哪里错了、该怎么改- [ ] 区分可重试错误超时、限流和不可重试错误参数错、权限不够- [ ] 给出正确参数的示例- [ ] 对参数错误明确指出哪个字段错了、应该是什么格式- [ ] 对权限错误说明需要什么权限或该转人工### 一句判断**错误信息是模型修正自己的依据。写给开发者看的报错模型看不懂。**---## 坑 5没有按需发现机制每次都把所有工具塞给模型### 坑是什么这是坑 3 的延伸但更严重。没有按需发现机制意味着 Agent 永远在全量工具集里选不管当前任务是什么。### 更像真实现场的过程用户问今天天气怎么样。Agent 有 40 个工具其中 1 个是 get_weather。但模型每次都要在 40 个工具里选而不是直接调 get_weather。即使模型选对了上下文里也塞了 39 个无关工具的 schema白白浪费 token。如果选错了用户问天气模型调了 send_email。### 为什么会踩- 没有工具检索/路由层- 没有按任务类型预过滤工具- 没有按用户意图做工具候选集缩减- 工具发现机制被认为是高级功能没在第一版做### 怎么避Checklist- [ ] 实现工具检索根据用户意图先检索候选工具3-5 个再让模型选- [ ] 按业务域分组不同任务类型加载不同工具集- [ ] 用语义检索做工具发现把工具描述向量化按需召回- [ ] 工具发现本身要有评测召回率、准确率要监控- [ ] 工具发现失败时要有兜底检索不到候选时怎么处理### 一句判断**按需发现不是高级功能是工具数量超过 10 个后的必需品。**---## 一个最小可用的 MCP 工具设计 Checklist把上面 5 个坑合并成一个可落地的 Checklist### 工具定义层- [ ] 工具名称语义明确不用泛化词- [ ] 描述写什么时候用 / 什么时候不用2-3 句话- [ ] 相似工具在描述里显式区分- [ ] 描述里给 1-2 个典型调用场景### 参数 Schema 层- [ ] 字符串字段加格式约束- [ ] 枚举字段给全枚举值 默认值- [ ] 必填项控制在最少- [ ] 复杂字段给示例### 工具发现层- [ ] 工具按业务域分类- [ ] 超过 10 个工具时实现按需发现- [ ] 全量注入时只给摘要选中后再给完整 schema- [ ] 定期清理低频工具### 错误处理层- [ ] 错误信息用自然语言写- [ ] 区分可重试和不可重试错误- [ ] 给出正确参数示例- [ ] 明确指出哪个字段错了### 可观测层- [ ] 工具选择准确率要监控- [ ] 参数校验失败率要监控- [ ] 工具调用 token 成本要监控- [ ] 按需发现召回率要监控这个 Checklist 不复杂但每一条都直接对应一个容易踩的坑。做完这 5 层MCP Server 才不是一个包了一层的 REST API而是一个为 Agent 设计的工具系统。---## 结语MCP Server 不是把 REST API 包一层。工具名称、描述、Schema、粒度、错误信息、发现机制每一个都会直接影响模型调用的准确率和上下文成本。最容易踩的 5 个坑- 工具描述写得像给人看的- Schema 太宽或太严- 工具数量爆炸全量注入- 错误信息不可读- 没有按需发现机制这 5 个坑踩了模型再强也会调用出错。工具设计做得好模型一般也能调对。对技术团队来说做 MCP Server 最该先建立的不是能不能包一层 API的能力而是**能不能按 Agent 的使用方式重新设计工具边界。**如果只是把 REST API 原样包一层Agent 调用准确率和 token 成本都会出问题。真正能跑起来的 MCP Server是按 Agent 任务重构了工具边界的系统。