工具設計的藝術
用 Agent 優化 Agent 的工具
工具寫得好不好，Agent 最有發言權。業界驗證了一套「用 Agent 寫工具 → 跑評測 → 自動優化」的工作流，讓工具設計從手工打磨變成系統化迭代。
核心思路
傳統方式：人類寫工具 → 人類測試 → 人類改進。週期長、回饋慢、依賴開發者的直覺。
新方式：讓 Claude Code 寫工具 → 用評測自動度量 → 讓 Claude Code 讀評測結果並自動優化。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 呼叫邏輯
輸出：Claude Code 生成完整的 MCP 工具程式碼，包括工具定義、參數校驗、API 呼叫邏輯
02
Evaluate
建立評測體系，系統化度量工具表現。要用資料證明好不好用，光看起來能用不算數。
評測維度：
- Agent 是否選對了工具？
- 參數填寫是否正確？
- 返回結果是否被正確理解？
- 端到端任務完成率如何？
- 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 / update3
返回有意義的上下文
工具返回不要只說 "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 成為自己工具的產品經理。