工具设计的艺术

用 Agent 优化 Agent 的工具

工具写得好不好，Agent 最有发言权。业界验证了一套「用 Agent 写工具 → 跑评测 → 自动优化」的工作流，让工具设计从手工打磨变成系统化迭代。

核心思路
传统方式：人类写工具 → 人类测试 → 人类改进。周期长、反馈慢、依赖开发者的直觉。
新方式：让 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 成为自己工具的产品经理。