工具设计的艺术 用 Agent 优化 Agent 的工具 工具写得好不好，Agent 最有发言权。业界验证了一套「用 Agent 写工具 → 跑评测 → 自动优化」的工作流，让工具设计从手工打磨变成系统化迭代。 一句话速览 Claude Code 实践：用 AI 写工具描述、跑评测、自动迭代优化 核心思路
传统方式： 人类写工具 → 人类测试 → 人类改进。周期长、反馈慢、依赖开发者的直觉。 新方式： 让 Claude Code 写工具 → 用评测自动度量 → 让 Claude Code 读评测结果并自动优化。 Agent 成了自己工具的产品经理。
三步工作流：Prototype → Evaluate → Optimize
Prototype
Evaluate
Optimize
评测结果不满意？重复循环，直到达标
01 Prototype 用 Claude Code 快速生成工具原型。描述你想要的工具功能，让它生成 MCP 工具的代码框架。
输入： 「帮我写一个 Jira 工具，能创建 issue、列出 issue、更新 issue 状态」 输出： Claude Code 生成完整的 MCP 工具代码，包括工具定义、参数校验、API 调用逻辑
02 Evaluate 建立评测体系，系统化度量工具表现。要用数据证明好不好用，光看起来能用不算数。
评测维度：
- Agent 是否选对了工具？
- 参数填写是否正确？
- 返回结果是否被正确理解？
- 端到端任务完成率如何？
03 Optimize 让 Claude Code 读评测结果，自动分析失败原因，并改进工具描述和实现。
Claude Code 分析： 「Agent 在 23% 的 case 中混淆了 search 和 list，因为描述太相似」 自动修复： 重写工具描述，增加区分说明和使用示例
五个工具设计原则
1 选对工具：少即是多
不要实现太多工具。如果人类开发者分不清该用 search 还是 find 还是 lookup ，Agent 也分不清。 原则： 如果两个工具的使用场景有 50% 以上重叠，合并它们。宁可一个工具多几个参数，也不要两个容易混淆的工具。
2 命名空间：分组管理
相关工具用前缀分组，让 Agent 一眼就能看出工具之间的关系。 好的命名： jira_create_issue / jira_list_issues / jira_update_status 差的命名： create_issue / list_tasks / update
3 返回有意义的上下文
工具返回不要只说 "success"，要返回 Agent 下一步需要的信息。 差： {"status": "success"} 好： {"status": "success", "issue_id": "PROJ-123", "url": "https://...", "assignee": "Alice"}
4 Token 效率：精简返回
大量结果要做精简。返回 1000 条记录意味着消耗大量 Token，而 Agent 只需要前 10 条。 策略： 总结（只返回统计信息）、截断（默认返回前 N 条）、分页（支持翻页参数）、过滤（支持条件筛选）
5 Prompt 工程化工具描述
工具描述不只是说明书，它是 Prompt 的一部分。要告诉 Agent 什么时候用 这个工具，更重要的是 什么时候不用 。 好的描述模板： 「[工具名] 用于 [具体用途]。当你需要 [场景A] 或 [场景B] 时使用此工具。不要在 [场景C] 时使用，那种情况请用 [另一个工具] 代替。示例：[具体输入输出]」
命名空间实战：让 Agent 看到工具地图
工具命名空间分组
jira_ -- 项目管理
jira_create_issue jira_list_issues jira_update_status jira_add_comment
git_ -- 版本控制
git_diff git_commit git_log git_create_branch
db_ -- 数据库
db_query db_insert db_update db_schema
命名空间的价值： 当 Agent 看到 jira_ 前缀的一组工具时，它立刻知道这些工具是相关的、操作的是同一个系统。这大幅降低了选错工具的概率。
Token 效率：返回结果的学问
全量返回
[ {"id": 1, "title": "Fix login bug", "desc": "Users cannot login...", "created": "2025-01-15T...", "updated": "2025-01-16T...", "assignee": {"name": "Alice", ...}, "labels": [...], "comments": [...]}, {"id": 2, ...}, ... // 共 847 条记录 ]
~52,000 Tokens -- Agent 根本处理不过来
精简返回
{ "total": 847, "showing": 10, "page": 1, "results": [ {"id": 1, "title": "Fix login", "status": "open", "assignee": "Alice"}, {"id": 2, ...}, ... // 前 10 条核心字段 ], "hint": "Use page=2 for more" }
~800 Tokens -- 信息密度高，Agent 轻松消化
真实例子：工具描述的差距
search_issues 工具描述对比
BEFORE -- 敷衍描述 { "name": "search_issues", "description": "Search for issues in the project tracker." } Agent 不知道搜索语法、不知道返回格式、不知道和 list_issues 有什么区别
AFTER -- 工程化描述 { "name": "search_issues", "description": "Full-text search across issue titles and descriptions. Use when the user mentions specific keywords. Returns max 20 results sorted by relevance.
For browsing by status/label, use list_issues instead.
Example: search_issues({ query: 'login timeout', status: 'open' })" } 语义清晰、有使用边界、有示例、有和相似工具的区分
优化循环的关键洞察： 让 Claude Code 跑完评测后，它能精确地说出「43% 的错误是因为 Agent 混淆了 search 和 list」，然后自动修改工具描述来解决这个问题。这比人类凭直觉调试快得多。
工具质量决定 Agent 质量上限。 用 Prototype → Evaluate → Optimize 的循环系统化地提升工具质量。记住五原则：选对工具、命名空间、有意义的返回、Token 效率、工程化描述。让 Agent 成为自己工具的产品经理。