简介:工具能跑通、schema 也没写错,Agent 却总是选错工具、传错参数,甚至在明明该调用工具时回答"我无法完成"。根因通常不在模型,而在于我们用写 REST API 的思维写了 Agent 工具。本文给出可直接落地的一套 MCP 工具设计原则。顺带一提,工具调用准确率与底层模型强相关,动手改造前不妨先到 [百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article) 对比不同模型的能力与调用成本,再决定用哪个模型驱动你的 Agent。
技术实现完全正确的工具,Agent 却用不好,这几乎是每个 Agent 项目的必经阶段。原因很直接:人类开发者会读文档、看上下文、出错后翻代码调试;而 Agent 这个”用户”只能通过 工具名称、描述文本和参数 schema 三样东西理解你的工具,并且它每次调用都要消耗 token,试错成本高且不稳定。
所以真正的问题不是”接口能不能调通”,而是”接口能不能被一个不会读文档的智能体正确使用”。MCP(Model Context Protocol) 由 Anthropic 推出,本质上是大模型与数据源、工具之间的标准化”转接头”,被形容为大模型应用生态里的 Type-C 接口。但协议只解决了”怎么接”,没解决”怎么设计”——这两件事必须分开做。
设计工具前,先明确这个用户的特长与短板,再逐条转化为设计约束:
| LLM 的特点 | 对工具设计的要求 |
|---|---|
| 擅长自然语言理解、意图推理、信息组合 | 描述可以写成语义清晰的说明,不必只堆关键词 |
| 不擅长精确计算、长上下文记忆 | 计算类逻辑放进工具内部,不要让模型算 |
| 无法看到你的代码实现 | schema 与描述就是全部契约,隐含逻辑必须显式写出 |
| 上下文有限,工具越多性能越差 | 控制工具数量,合并同类工具,精简返回值 |
| 会从模糊描述里”猜”参数 | 用 enum、默认值、格式约束消灭歧义 |
一个实用的判断标准:如果某个信息模型必须知道才能正确调用,而它不在 name / description / schema 里,那就是设计缺陷。
工具名是模型做选择的第一道信号。search、query、get_data 这类名字在只有三个工具时没问题,在三十个工具的环境里就是灾难。
推荐结构是 平台_对象_动作 或 动作_对象:
❌ search✅ web_search # 联网搜索✅ knowledge_search # 企业知识库检索✅ product_get_detail # 商品详情查询
要点有三个:一是把 领域前缀 写进名字,让模型能靠名字完成第一层筛选;二是 避免近义工具同名 ,如果两个工具都叫 search,模型只能随机挑;三是名字用 snake_case,与主流框架的默认约定保持一致,减少工具名被改写带来的语义损失。
这是收益最高、也最常被敷衍的一步。差的描述只说明”这个工具做什么”,好的描述还要说明 什么时候用它、什么时候不要用、和邻居工具的区别 。
{"name": "knowledge_search","description": "检索企业内部知识库(产品文档、制度、FAQ)。当用户询问公司内部规定、产品使用方法、历史工单结论时使用。不要用于:实时新闻、天气等外部信息(用 web_search);不要用于计算或数据加工。返回最相关的 3 段原文及来源链接。","inputSchema": {"type": "object","properties": {"query": { "type": "string", "description": "用户原始问题的核心表述,保留专有名词,不要改写或翻译" }},"required": ["query"]}}
三个可直接套用的技巧:
参数设计的目标是让模型”没有猜的空间”:
{"channel": {"enum": ["app", "web", "mini_program"]}} 比 "渠道名称" 可靠得多。sort: "asc" | "desc" 优于 is_ascend: true;status: "paid" | "unpaid" 优于 is_paid + is_cancelled 两个布尔值——后者会出现互相矛盾的组合。很多工具失败在返回上:接口返回了 80 个字段的原始 JSON,模型在长上下文里抓不住重点,后续推理质量随之下降。
{"results": [...], "refine_hint": "未找到精确匹配,可尝试放宽时间范围"}。500 Internal Server Error、Invalid parameter 这类返回对 Agent 毫无帮助,它只会重试同样的调用或直接放弃。错误信息应当包含三件事:哪里错了、为什么错、下一步怎么做。
❌ {"error": "invalid date format"}✅ {"error": "date 格式非法:收到 '2026/11/17',要求 YYYY-MM-DD。","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 的工具清单拉出来,逐个问一句:一个从没读过我代码的智能体,只看这三样东西,能正确使用它吗?