摘要AI Agent开发中经常会遇到工具明明写了但模型不调用、调用错工具、返回为空或执行失败的问题。本文从Tool描述、参数设计、上下文、权限和日志五个方面整理常见排查思路适合刚接触Agent开发的程序员参考。最近很多开发者开始做AI Agent。一开始看起来很简单给模型几个工具让它根据用户问题自动选择然后完成查询、写入、搜索、计算等任务。但真正写起来经常会遇到一个很头疼的问题工具明明写了Agent就是不调用。或者调用了但选错工具。再或者工具执行了结果却是空的。这类问题不一定是模型能力不行更多时候是工具设计、描述、参数和上下文没有写清楚。一、Tool描述太模糊Agent能不能正确调用工具很大程度取决于Tool描述是否清楚。比如你写两个工具search_user查询用户query_user获取用户这两个描述太像模型很容易分不清。更好的写法是search_user_by_name根据用户名搜索用户get_user_detail_by_id根据用户ID获取用户详情Tool名字和描述要让模型一眼就知道区别。不要只写“查询”“获取”“处理”这种宽泛词要写清楚查什么按什么字段查返回什么结果适合什么场景。二、参数设计不明确有些Agent不调用工具是因为参数设计太乱。比如工具需要userId但用户输入的是手机号工具需要orderNo但提示词里没有说明订单号格式工具参数是date但用户说的是“今天”“昨天”。这些都会让模型犹豫甚至直接不调用。建议参数设计尽量简单字段名清楚类型明确必填项不要太多能用自然语言推断的最好在描述里说明。例如order_no订单编号字符串用户提供订单号时使用。phone手机号11位数字用于按手机号查询用户。参数越清楚Agent越容易稳定调用。三、工具太多模型会选错很多开发者一上来就给Agent挂十几个工具。搜索用户、查询订单、读取文档、写入数据库、发送消息、生成报告、调用接口全部放进去。结果模型反而更容易选错。工具不是越多越好而是要按场景拆分。如果是客服Agent就优先保留用户查询、订单查询、售后记录这些工具。如果是代码Agent就优先保留文件读取、代码搜索、测试执行这些工具。每个Agent最好只挂和当前任务强相关的工具。四、上下文没有说明使用规则工具写好了还要告诉Agent什么时候该用。比如用户问具体订单状态时必须调用订单查询工具。用户只是问规则说明时优先回答知识库内容。用户要修改数据时先确认再执行写入。涉及删除、付款、权限变更时不允许自动执行。这些规则如果不写Agent可能会靠猜。比较稳的方式是在系统提示词里写清楚哪些情况必须调用工具哪些情况禁止调用工具工具失败后如何回复是否允许连续调用多个工具是否需要用户确认。Agent不是只靠工具函数工作也靠规则工作。五、没有日志就很难排查Agent工具调用失败最怕只看最终回答。因为你不知道它到底是没有识别出要调用工具识别了但没选选了错误工具参数填错了工具执行失败工具返回结果为空。所以开发阶段一定要看日志。至少记录用户原始输入模型选择的工具传入参数工具返回结果错误信息最终回复内容。有了这些信息才能判断问题在哪一层。如果不看日志只反复改提示词很容易越改越乱。总结AI Agent工具不调用通常不是单一原因。常见问题包括Tool名字太像描述不够清楚参数设计复杂工具数量太多上下文规则缺失日志不完整。排查时不要一上来就怀疑模型先看工具本身是否写清楚。一个稳定的Agent不只是模型强还要工具清晰、参数明确、规则完整、日志可追踪。把这几件事做好Agent调用工具的稳定性会提升很多。