tool-design

工具設計 skill 概覽

tool-design 的用途

tool-design skill 能幫你設計讓模型能正確選擇並呼叫的 agent-facing tools。當你在打造新工具、簡化過度龐雜的工具組，或審查第三方 tool interface 是否適合 agent 使用時，這個 skill 特別有用。它聚焦的是一個很實際的問題：把工具描述寫得夠精準，讓 agent 不會誤判。

什麼情況最適合

在 Design Implementation 的工作中，如果主要難題是 tool selection、命名、範圍重疊，或 agent 邊界上的行為不清楚，就適合用 tool-design skill。它很適合 MCP tool design、tool consolidation，以及 agent 呼叫錯函式或忽略正確函式的除錯情境。如果你只是需要給人看的通用 API 文件，它就沒那麼有幫助。

它的不同之處

這個 tool-design skill 對「減法」很有立場：如果工具彼此重疊，agent 就會用錯。它強調的是清楚、無歧義的 tool contract、明確的啟用規則，以及 description engineering，而不是泛泛的 prompt 建議。當你需要的是更少、但更好的工具，而不是更多說明時，它就特別有價值。

如何使用 tool-design skill

安裝並檢視來源

先用 npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering --skill tool-design 安裝 tool-design skill。接著先讀 skills/tool-design/SKILL.md，再讀 references/best_practices.md、references/architectural_reduction.md 和 scripts/description_generator.py。這些檔案會呈現最重要的設計邏輯、減法取捨，以及影響輸出品質的輔助模式。

提供正確的問題描述

當你的提示詞不只是寫 feature，而是直接點出 tool boundary 時，tool-design usage 的效果最好。好的輸入會說明這個工具必須判斷什麼、會收到哪些輸入，以及目前設計在哪裡失效。比如說：「設計一個 agent tool，從日曆資料中找出可用會議室；它不應該和預約或搜尋工具重疊。」這樣就比「建立一個會議室工具」更有幫助。

使用包含限制條件的提示詞

要得到最佳結果，請提供這個工具的用途、預定呼叫者、預期輸入、失敗案例，以及任何自動化權限上的限制。如果你是在重設一組工具，請把所有候選工具都列出來，並要求做 consolidation。如果你是在建立單一工具，請附上參數名稱、資料型別，以及有效與無效呼叫的例子。tool-design guide 最適合讓模型比較選項，而不是自己推測選項。

Design Implementation 的實作流程

先列出 agent 可以做的每一個動作，再把意圖相同的動作合併。接著，每個工具用一句話定義「它做什麼」和「什麼時候該用」。最後，拿這些描述去測試最可能造成混淆的情境：如果兩個工具聽起來可以互換，表示描述還沒準備好。對 Design Implementation 來說，這是在加更多邏輯之前，先降低 tool selection errors 的最快方式。

tool-design skill 常見問題

tool-design 只適用於新工具嗎？

不是。當既有工具過於細碎、命名不一致，或經常被 agent 誤用時，tool-design skill 也同樣有用。對很多團隊來說，重整一組雜亂的工具，往往比再發明一個函式更有價值。

它和一般 prompt 有什麼不同？

一般 prompt 可以要求一些工具點子，但 tool-design skill 的重點是把 tool contract 做到 agent 可以執行。這代表更小的範圍、更強的描述、明確的啟用規則，以及對重疊問題的處理。當輸出必須經得起真實 agent 的選擇行為，而不只是人類看起來順眼時，它會更合適。

新手也能用嗎？

可以，只要你能描述使用者任務和工具的預期輸入就行。要把 tool-design skill 用好，不需要深入了解 agent internals，但你必須清楚界定邊界。模糊的需求，最後通常只會產生模糊的工具。

什麼時候不該用？

如果你是在寫給終端使用者看的 API 文件、做純 UI flow，或你已經有一組邊界清楚、呼叫穩定的極簡工具，就可以跳過 tool-design。如果主要問題是模型推理，而不是 tool design，那它也不是正確選擇。

如何改進 tool-design skill

提供更精準的來源材料

最好的 tool-design 輸出，來自具體範例：工具名稱、實際動作、預期參數，以及兩三個常見誤用情境。如果你只提供 feature 名稱，結果通常會太泛，難以直接給 agent 使用。當你希望做 consolidation 時，一定要附上目前的工具清單，因為重疊正是這個 skill 最想避免的主要失敗模式。

要求明確的取捨說明

當你想把工具設計做得更好時，請要求 skill 說明哪些內容被合併、哪些被刪除，以及原因是什麼。這會比單純改寫，產生更有用的 Design Implementation 指引。例如，可以要求提供改版前後的 tool map、建議描述，以及一句簡短說明，指出每個變更消除了哪個主要歧義。

從錯誤呼叫迭代，不要靠猜

如果 agent 已經出錯，把失敗的 tool call、選錯的工具，或含糊的描述帶進下一輪提示詞。tool-design skill 最擅長修補真實的失敗模式。第一次處理完後，針對 agent 展現出的那個具體混淆點把措辭收緊，再測一次。