MCP Tool 设计：参数、结果与错误处理的工程要点

本文从工程实现角度梳理这一问题，重点放在系统边界、工具调用、权限控制和结果处理。

把 API 转成 MCP Tool，技术上可能并不复杂。真正费时间的地方，是把一个“程序能调用的接口”，整理成一个“Agent知道什么时候该用、怎样用、出了问题怎么办”的企业工具。

如果只是把接口名称换一层，Agent仍然可能调用错、参数填错，或者拿到结果却无法继续处理。

一、工具名称要让人和 Agent都看得懂

“getData”“executeTask”这样的名称，对开发人员可能勉强够用，对业务人员和 Agent 都不够清楚。

工具名称应该说明对象和动作。比如“查询客户回款情况”“创建维修工单”“提交采购申请草稿”，比“query01”“processOrder”更容易理解和使用。

工具描述还要写清适用场景、输入条件、返回内容和不适用的情况。Agent需要知道什么时候调用它，也要知道什么时候不应该调用。

二、工具颗粒度不能过大

把客户查询、合同查询、回款查询、跟进记录写回放进一个“客户全量处理”工具，表面上省了工具数量，实际会让调用过程变得难以控制。

颗粒度过大的工具，参数多，失败点多，权限边界也不清楚。颗粒度过小，又会让 Agent需要频繁调用，增加链路复杂度。

我倾向于把工具设计在清晰的业务动作上：查什么、生成什么、更新什么、提交什么。涉及高风险动作时，再把草稿和正式提交拆开。

三、输入参数要有业务约束

工具参数不能只写字段类型。还要说明哪些字段必填，日期范围允许多大，金额是否需要校验，组织和人员是否必须在授权范围内。

例如，“查询订单”至少要明确客户、区域、时间范围、订单状态等参数的取值规则。没有边界的参数，容易产生过宽查询、重复调用和无效结果。

参数校验应该尽可能放在工具和服务侧，不能完全依赖模型自己记住规则。

四、返回结果要能被下一步继续使用

工具返回一大段没有结构的文本，Agent很难稳定处理。更适合的做法，是让结果包含清晰的状态、数据字段、错误信息和后续建议。

查询工具返回数据，写入工具返回单据编号和处理状态，流程工具返回是否发起成功、当前节点和待处理人。这样，Agent才能继续向用户说明发生了什么，也能在失败时给出准确提示。

五、工具要把失败当成正常情况来设计

系统超时、权限不足、数据不存在、参数错误，都是企业系统里的常见情况。

如果工具只设计成功路径，Agent在遇到异常时就可能生成一段看起来合理、实际不准确的解释。工具应返回可识别的错误类型，并区分“可以修改参数重试”“需要人工处理”和“不能继续执行”。

这也是后续运营的重要基础。没有明确错误类型，就很难统计哪些工具经常失败，问题到底出在参数、权限、系统还是业务规则。

六、工具设计最终要服务于业务任务

企业工具不是越多越好。得帆的 MCP 平台强调工具封装、协议标准化、服务注册和发现，目的是让 Agent能够稳定调用企业外部能力。

在得小帆里，工具还要和角色、知识、模型、Skill以及发布权限一起配置。工具进入智能体之后，仍然需要经过测试、发布、运行监控和持续优化。

最后看一个判断

好的 MCP Tool，不是把接口名称换成英文，也不是把所有系统能力全部暴露出来。它需要有清楚的业务语义、适当的动作边界、可校验的参数、结构化的结果和可处理的错误。

工具设计得越清楚，Agent越容易稳定执行；治理规则越明确，企业越敢把它放进真实工作里。

事实核实记录

本文依据得帆智能 MCP 平台、得小帆智能体编排与 Dolphin Integration 产品资料整理。文中工具设计方法为通用实践建议，不包含未核实的客户工具清单或效果数据。

说明：文中业务场景为通用示例，接口名称、参数和权限模型需要按实际系统调整。