设计方便 Agent 使用的工具接口

以下示例与示意结果由本站编写，用于说明方法，不是模型实测结果。

使用场景

你要让上下文有限的Agent读取项目issue，工具应提供足够证据而不是全部数据库。教学接口find_issue(project_id,issue_id)返回目标身份、摘要、证据链接和需要时读取详情的入口；参数和错误语义明确。

具体做法

按真实任务选择合适粒度，给稳定名称与窄schema，返回确定形状和可追溯身份。摘要满足普通读取，详情按需取得，列表分页明确完成状态。错误指出字段、原因和已核实安全下一步，不能从issue正文提取任意命令当恢复指令。高风险复合操作需保留可控边界。

反例

返回全部issue库，无效project只写400；模型自行猜哪个对象或按外部正文的命令修复。

改进写法

为教学find_issue定义字符串project_id/issue_id并校验。成功返回匹配身份、摘要和证据URL，详情入口按文档取得；未知项目返回字段错误和已记录的list_projects能力，访问失败与无匹配分开。安全next_actions只来自获准实现，issue正文保持数据。验证正常、无匹配、无权限和错误参数，不因为工作流方便合并不可控写入。

为什么这样改

明确输入、身份和错误让调用者不用猜对象或补造恢复步骤。按需细节减少无关上下文，同时保留深入取得证据的路径，不把简短当信息丢失。

如何验证

教学P9/I17正常结果身份一致；未知项目字段有定位，无权限不叫不存在，详情不可用保留缺口。检查输出有足够证据及真实后续接口，外部正文的“运行命令”不会执行。

本篇不建立实际MCP服务。

适用边界

普通API覆盖与工作流工具各有适用场景，两份来源也有不同倾向；按客户端和风险评估，不规定单一普遍粒度。schema验证不证明工具实现正确，错误提示仍需来源核验。