AI Agent 工具描述：让模型知道能做什么，也知道不能做什么

AI Agent 工具描述：让模型知道能做什么，也知道不能做什么

一、工具描述不是说明书装饰

做 AI Agent 时，工具调用是否稳定，很大程度取决于工具描述。描述太模糊，模型会乱用；描述太宽，模型会把它当万能接口；描述不写限制，模型会在不该执行的时候执行。

工具描述的目标，是让模型知道能做什么，也知道不能做什么。

二、描述要包含能力和边界

flowchart TD A[工具描述] --> B[用途] A --> C[参数] A --> D[限制] A --> E[错误] A --> F[示例]

例如文件读取工具，不应该只写“读取文件”。它应该说明只允许读取工作区内文件、路径必须相对、不能读取目录、最大大小是多少。

{ "name": "read_file", "description": "读取工作区内的文本文件，不允许访问工作区外路径", "parameters": { "path": "相对路径，不能包含 ..", "max_bytes": 65536 } }

描述越具体，模型越容易做出合适选择。

三、错误信息也会影响下一步

Agent 工具失败后，错误信息会进入模型上下文。错误如果只写failed，模型不知道怎么修正。应该告诉它是路径非法、权限不足、文件太大还是格式不支持。

enum ToolError { PathOutsideWorkspace, FileTooLarge, UnsupportedEncoding, }

错误类型清楚，模型才可能换一个正确动作。

四、工具要最小能力化

不要给一个工具同时读文件、写文件、执行命令、联网请求。能力越大，越难审计。更好的方式是拆成小工具，每个工具有明确输入输出。

agent_tools: read_file: read_only write_file: workspace_only run_command: allowlist_required

还要给危险工具加确认或策略限制。比如删除文件、执行 shell、访问密钥，都不应该只靠模型自觉。

最后，工具描述要和真实校验一致。描述里说不能访问工作区外，代码里也必须检查路径。只写描述不写校验，是把安全交给运气。

工具描述还应该写失败后的建议动作。比如文件太大时，提示模型先读取目录或按范围读取；路径不存在时，提示先列出附近目录。这样 Agent 不会在同一个错误上重复尝试。

{ "error_code": "file_too_large", "suggestion": "use read_file_range or summarize smaller file" }

参数 schema 也要尽量收窄。能用枚举就不要用自由字符串，能用布尔值就不要让模型写“yes/no”。参数空间越小，调用越稳定。

还要给工具输出设置上限。Agent 工具如果一次返回几十万字符，会把上下文挤爆。输出可以摘要、分页或返回句柄，让模型按需继续读取。

最后，工具描述要随着真实使用迭代。观察模型经常误用哪些工具，把误用原因写回描述或校验规则里，Agent 会越来越稳。

工具之间也要避免能力重叠。两个工具都能读取文件，一个返回全文，一个返回摘要，模型可能反复选择错误工具。命名、描述和适用场景要拉开差异，让选择路径更明确。

还可以给高风险工具加 dry-run 模式。模型先生成计划和影响范围，用户或策略系统确认后再执行真实动作。这样既保留 Agent 的自动化能力，也给危险操作留出刹车。

踩过一个坑：工具描述里写了"只读取工作区内的文件"，但实现时漏掉了路径检查。模型直接生成了一个/etc/下的绝对路径，代码居然照做了。从那以后我把"描述里写了什么，代码里必须对应断言"写进了开发规范。工具描述和实际校验不一致，比没写描述更危险。

给工具加能力时还有个安全准则：新能力的权限默认关闭，需要用户在配置里显式开启。这样做看起来保守，但这道"门"会把误激活的概率降到几乎为零。

五、总结

AI Agent 工具描述要写清用途、参数、限制、错误和示例，并让代码校验与描述一致。

让模型知道能做什么，也知道不能做什么。工具越清楚，Agent 越稳。