如何让你的 Agent 调用更准确:MCP 工具设计技巧(上)

作者:暴富20212026.11.17 03:32浏览量:0

简介:工具能跑通、schema 也没写错,Agent 却总是选错工具、传错参数,甚至在明明该调用工具时回答"我无法完成"。根因通常不在模型,而在于我们用写 REST API 的思维写了 Agent 工具。本文给出可直接落地的一套 MCP 工具设计原则。顺带一提,工具调用准确率与底层模型强相关,动手改造前不妨先到 [百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article) 对比不同模型的能力与调用成本,再决定用哪个模型驱动你的 Agent。

agent-agent-">先给结论:Agent 工具是 Agent 的”用户界面”

技术实现完全正确的工具,Agent 却用不好,这几乎是每个 Agent 项目的必经阶段。原因很直接:人类开发者会读文档、看上下文、出错后翻代码调试;而 Agent 这个”用户”只能通过 工具名称、描述文本和参数 schema 三样东西理解你的工具,并且它每次调用都要消耗 token,试错成本高且不稳定。

所以真正的问题不是”接口能不能调通”,而是”接口能不能被一个不会读文档的智能体正确使用”。MCP(Model Context Protocol) 由 Anthropic 推出,本质上是大模型与数据源、工具之间的标准化”转接头”,被形容为大模型应用生态里的 Type-C 接口。但协议只解决了”怎么接”,没解决”怎么设计”——这两件事必须分开做。

一、先认清你的”用户”:LLM 的能力边界

设计工具前,先明确这个用户的特长与短板,再逐条转化为设计约束:

LLM 的特点 对工具设计的要求
擅长自然语言理解、意图推理、信息组合 描述可以写成语义清晰的说明,不必只堆关键词
不擅长精确计算、长上下文记忆 计算类逻辑放进工具内部,不要让模型算
无法看到你的代码实现 schema 与描述就是全部契约,隐含逻辑必须显式写出
上下文有限,工具越多性能越差 控制工具数量,合并同类工具,精简返回值
会从模糊描述里”猜”参数 用 enum、默认值、格式约束消灭歧义

一个实用的判断标准:如果某个信息模型必须知道才能正确调用,而它不在 name / description / schema 里,那就是设计缺陷。

二、命名:让工具名自带路由信息

工具名是模型做选择的第一道信号。search、query、get_data 这类名字在只有三个工具时没问题,在三十个工具的环境里就是灾难。

推荐结构是 平台_对象_动作 或 动作_对象:

  1. ❌ search
  2. ✅ web_search # 联网搜索
  3. ✅ knowledge_search # 企业知识库检索
  4. ✅ product_get_detail # 商品详情查询

要点有三个:一是把 领域前缀 写进名字,让模型能靠名字完成第一层筛选;二是 避免近义工具同名 ,如果两个工具都叫 search,模型只能随机挑;三是名字用 snake_case,与主流框架的默认约定保持一致,减少工具名被改写带来的语义损失。

三、描述:写给模型看的 prompt,不是写给同事看的注释

这是收益最高、也最常被敷衍的一步。差的描述只说明”这个工具做什么”,好的描述还要说明 什么时候用它、什么时候不要用、和邻居工具的区别 。

  1. {
  2. "name": "knowledge_search",
  3. "description": "检索企业内部知识库(产品文档、制度、FAQ)。当用户询问公司内部规定、产品使用方法、历史工单结论时使用。不要用于:实时新闻、天气等外部信息(用 web_search);不要用于计算或数据加工。返回最相关的 3 段原文及来源链接。",
  4. "inputSchema": {
  5. "type": "object",
  6. "properties": {
  7. "query": { "type": "string", "description": "用户原始问题的核心表述,保留专有名词,不要改写或翻译" }
  8. },
  9. "required": ["query"]
  10. }
  11. }

三个可直接套用的技巧:

  • 写清负向边界 。”不要用于 X,请用 Y” 这一句对降低工具误选率的作用,往往大于把所有功能都夸一遍。
  • 描述里给出使用时机 ,而不是只给功能列表。模型是先判断”该不该用”,再判断”怎么用”。
  • 参数描述写清语义与约束 ,尤其是”不要改写用户原话””日期用 YYYY-MM-DD”这类模型容易自作主张的地方。

四、参数 schema:用结构消灭歧义

参数设计的目标是让模型”没有猜的空间”:

  1. 能用 enum 就不用自由文本 。{"channel": {"enum": ["app", "web", "mini_program"]}} 比 "渠道名称" 可靠得多。
  2. 能合并的不要拆成一堆布尔开关 。sort: "asc" | "desc" 优于 is_ascend: true;status: "paid" | "unpaid" 优于 is_paid + is_cancelled 两个布尔值——后者会出现互相矛盾的组合。
  3. 必填项尽量少 。每个必填参数都是一个可能失败的点,能给默认值的就给默认值。
  4. 复杂输入用嵌套对象或字符串 DSL ,而不是十几个平铺参数。参数超过 8~10 个时,模型的漏填和错填概率会明显上升。
  5. 不要让模型做计算 。分页、时间范围换算、金额单位换算,全部在工具内部完成。

五、返回值:为”下一步决策”而设计

很多工具失败在返回上:接口返回了 80 个字段的原始 JSON,模型在长上下文里抓不住重点,后续推理质量随之下降。

  • 只返回模型和用户需要的字段 ,原始数据留在服务端。
  • 控制长度 ,长列表做截断并明确告知”共 N 条,已返回前 M 条,可加分页参数获取更多”。
  • 结构化优先 ,用清晰的层级和字段名,而不是拼接好的自然语言长段落。
  • 给出可执行的下一步 ,比如返回 {"results": [...], "refine_hint": "未找到精确匹配,可尝试放宽时间范围"}。

六、错误信息是给模型的指令,不是给人看的堆栈

500 Internal Server Error、Invalid parameter 这类返回对 Agent 毫无帮助,它只会重试同样的调用或直接放弃。错误信息应当包含三件事:哪里错了、为什么错、下一步怎么做。

  1. ❌ {"error": "invalid date format"}
  2. ✅ {"error": "date 格式非法:收到 '2026/11/17',要求 YYYY-MM-DD。",
  3. "action": "请用 start_date='2026-11-01', end_date='2026-11-17' 重新调用"}

同理,参数校验失败时返回 可选值列表 ,模型下一轮就能自己纠正,而不是陷入”调用—失败—回复用户无法完成”的循环。

七、工具粒度与数量:少而正交

工具越多,选择难度越大,上下文占用也越高。判断标准是 正交性 :任意两个工具之间,不应该存在”看起来也能干这事”的重叠。发现重叠时,优先合并为一个带 type 参数的工具,而不是保留两个相似工具让模型去猜。

粒度上,一个工具对应一个 完整的用户意图 ,而不是一个 HTTP 端点。把”创建订单 + 校验库存 + 计算运费”拆成三个工具暴露给模型,失败率会显著高于封装成一个 create_order。

八、怎么验证工具好不好用

不要靠感觉调 prompt。建一个 30~50 条的真实提问集,标注每条的 期望工具与期望参数 ,然后统计三个指标:

  • 工具选择准确率 :是否选对了工具;
  • 参数填充准确率 :必填参数是否正确、枚举值是否越界;
  • 无效调用率 :格式错误、缺参、重复调用占比。

改造前后跑同一套集合,才能判断描述改写到底有没有用。同时留意 token 消耗:工具描述会常驻上下文,描述写得又长又重复,等于持续付费。想量化这部分成本,可以在 词元所 上按不同模型的单价做一版调用量估算,再决定是精简描述还是换用性价比更高的模型。

九、生态现状:不必从零造轮子

MCP 已经不是纸面标准。百度智能云 AppBuilder 已支持 MCP 协议,可把网页组件市场的组件、自定义工作流组件以及 SDK 侧组件转成 MCP Server 对外提供;百度智能云还把图像识别、图像增强与特效等 AI 开放能力封装成标准 MCP Server,接入后应用直接获得车型识别、菜品识别、图像去雾、无损放大等能力。在 Cursor 等支持 MCP-SSE 的客户端里,也可以直接填入 https://appbuilder.baidu.com/v2/ai_search/mcp/sse?api_key=xxx 形式的地址,把云端组件接进本地 Agent。

这类现成 Server 的价值不只是省事,更是 优质样本 :去读它们怎么命名工具、怎么切分粒度、怎么写描述,比自己摸索快得多。

小结

MCP 工具设计的核心可以压成一句话: 把工具当成 Agent 的 UI 来设计,而不是把 API 包一层壳 。命名承担路由、描述承担决策、schema 承担约束、返回值承担下一步、错误信息承担纠错——五处都做到位,工具调用准确率会有肉眼可见的变化。

下篇会继续讲进阶部分:多工具环境下的上下文压缩、工具描述的分层加载、以及用评测集驱动工具迭代的完整闭环。在此之前,建议先把手上 Agent 的工具清单拉出来,逐个问一句:一个从没读过我代码的智能体,只看这三样东西,能正确使用它吗?