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 越稳。