智能体调用API总出错？先看看工具描述写对了没

问智能体调用业务系统的API时经常选错工具、传错参数。换了更大的模型也没解决问题。问题到底出在哪答问题可能出在工具Tool的描述上而不是模型能力上。大多数智能体工具调用的失败不是因为模型不够聪明是因为工具描述写得不够清晰。大模型选工具依赖的是描述文本不是代码注释。一、工具描述的常见问题问题一描述太短模型不知道这个工具是干什么的错误示例这种描述对大模型来说信息量严重不足——这个“订单”是什么业务含义是销售订单、采购订单、还是生产工单参数“订单号”的格式是什么查询结果返回哪些字段问题二没有说明适用场景大模型需要知道“什么时候该用这个工具”。同一个订单查询功能可能有两种不同的工具一个用于客服查单返回状态、物流、收货人信息一个用于财务查单返回金额、支付状态、发票信息。如果描述里不说清楚适用场景模型可能用错。问题三没有写异常处理指引工具调用失败时模型应该怎么处理返回“订单不存在”时该怎么说超时时该怎么办这些如果不在工具描述里写清楚模型就“自由发挥”——可能编造数据、可能美化错误、可能反复调用同一个工具。二、一个经过验证的工具描述结构以“销售订单查询”工具为例三、好的工具描述让模型“知道怎么干活”用这个结构描述清楚之后模型的工作流程就清晰了用户说“查一下订单”模型识别意图是查询订单但缺少必要参数订单号先反问用户要订单号用户说“X12345678”模型确认格式正确调用工具传入订单号工具返回“订单已发货物流单号SF1234567890”模型将结果组织成自然语言反馈给用户如果工具描述没写清楚模型的执行流程可能是混乱的——参数格式不对、不知道要反问、甚至调用错了工具。目前市场上做企业AI智能体定制的服务商在交付智能体时通常会把工具描述的设计作为标准环节包含一套经过验证的模板和示例。如果企业自己写Prompt遇到了选错工具的问题按上述结构重写一遍工具描述通常能解决大部分问题。FAQQ工具描述写多长合适A每个工具描述200-400字比较合适。太短信息量不够太长会占用上下文窗口。如果工具本身逻辑复杂可以考虑拆分成多个更细粒度的工具。Q工具描述里的“不适用场景”要不要写A建议写。模型知道“什么时候不用这个工具”和知道“什么时候用”同样重要。加了“不适用场景”后模型调用错误工具的概率会明显下降。Q工具描述需要持续优化吗A需要。上线后至少观察两周记录模型选错工具的案例分析是描述不够清晰还是遗漏了某种场景。每次迭代优化描述模型的工具选择准确率会逐步提升。一句话总结智能体调用API出错大概率是工具描述写得不够好。把适用场景、参数格式、返回字段、异常处理四个部分写清楚模型自然知道什么时候用什么工具、参数怎么传、出错了怎么处理——不需要换更大的模型。