前言¶

Agent 能連上數據庫、GitHub 或自建 API，並不等於能穩定用對這些能力。常見故障往往不是後端掛了，而是模型選錯工具、參數格式不對，或錯誤信息裏沒有任何可自我糾正的線索。人類面向的 API 文檔可以靠約定和追問補全；面向 Agent 的工具必須把契約寫進 description 和 schema，讓單次推理就能選對、填對、從失敗裏改對。下面介紹 Context Engineering 技能集裏的 tool-design，它專門覆蓋「單個工具或整份工具目錄」這一層的接口設計。

這是什麼¶

tool-design 是 Agent Skills for Context Engineering 倉庫中的一條 Skill，維護者爲 Agent Skills for Context Engineering Contributors（SKILL 元數據版本 2.2.0，最近更新 2026-05-15）。

一句話定位：把每個工具當作確定性系統與非確定性 Agent 之間的契約，指導你編寫可被路由的工具描述、設計 schema 與響應格式、統一命名、設計可操作的錯誤恢復信息，並處理 MCP 服務與工具集合並/裁剪。

它與同集合中的 project-development（項目形態與流水線）、multi-agent-patterns（是否拆子 Agent）、context-optimization（軌跡級 token 與 observation masking）分工明確：本 Skill 只負責工具接口層，不替你做架構選型或全項目成本決策。

何時啓用¶

官方在 SKILL 中寫明，當工作單元是「一個工具或一組工具」時應激活，例如：

1. 編寫新工具的描述、schema 或響應格式。
2. 排查 Agent 選錯工具或生成畸形調用。
3. 合併重疊工具目錄（典型表述：「有 17 個工具，一半時間選錯」）。
4. 設計可操作的錯誤信息，便於 Agent 自我糾正。
5. 在目錄內統一工具與參數命名（含 MCP 命名空間、verb-noun）。
6. 在接入第三方工具前，用合併原則評估是否值得加入。

不應激活的場景包括：是否用 LLM、流水線階段劃分（歸 project-development）；單 Agent 多工具 vs 多 Agent（歸 multi-agent-patterns）；多輪工具輸出的 token 減重（歸 context-optimization）。

核心概念與能力¶

合併原則（Consolidation）¶

若人類工程師都無法在給定場景下唯一確定該用哪個工具，就不應指望 Agent 做得更好。Agent 靠比較各工具 description 做路由，功能重疊會直接變成選錯工具。Skill 建議把工具集收縮到「每個工具只有一個清晰目的」，並在合適時用單一綜合工具替代多條窄工具鏈（例如用 schedule_event 在內部完成查檔與創建，而不是讓 Agent 依次 list_users、list_events、create_event）。

合併也有邊界：行爲本質不同、上下文不同、或必須獨立調用的能力應保持分離；過度合併會導致參數過多、模式混雜，Agent 反而填不對參數。

工具即契約、描述即 Prompt¶

工具 description 會進入 Agent 上下文，直接參與推理，不是給人看的附錄。契約需在描述塊裏自洽：格式示例、約束、返回形態都要寫全，因爲 Agent 不能在調用前追問。

描述應穩定回答三類問題（選型時 Agent 實際在問這些）：

• 做什麼？
• 何時用？
• 返回什麼？

工程上還可擴展爲四點結構：做什麼、何時用、接受什麼輸入、返回什麼（含成功與錯誤）。

命名、命名空間與 MCP¶

工具名建議 verb-noun（如 get_customer、create_order），跨工具參數名一致（始終 customer_id，避免 id / identifier 混用）。目錄變大時用前綴分組（如 db_*、web_*），減輕扁平靜掃帶來的選型噪聲。

對接 MCP 時，官方要求使用完全限定名，格式爲 ServerName:tool_name，避免多 Server 並存時出現「找不到工具」：

# 正確
BigQuery:bigquery_schema
GitHub:create_issue

# 錯誤（多 Server 時易失敗）
bigquery_schema

響應格式與錯誤恢復¶

爲控制上下文佔用，可爲工具提供響應格式選項（如 concise vs detailed），並在 description 裏說明何時選哪種。錯誤信息需對 Agent 可操作：說明錯因、如何改參、是否可重試；僅返回 failed 或 invalid input 無法支撐自我糾正。

架構縮減（Architectural Reduction）¶

在數據層文檔齊全、模型推理足夠、專用工具反而限制發揮時，Skill 討論用少量原語（如文件系統 + 標準 Unix 命令）替代大量領域專用工具的路徑，並指向倉庫內 references/architectural_reduction.md 作進一步閱讀。同時提醒：數據混亂、強安全邊界、或流程確實需要結構化編排時，不宜盲目刪減。

實踐清單與評估維度¶

工具選型框架（設計工具集時）：

1. 列出 Agent 必須完成的 distinct workflows。
2. 把相關動作歸入綜合工具。
3. 確保每個工具目的唯一、無歧義。
4. 文檔化錯誤與恢復路徑。
5. 用真實 Agent 交互測試。

入庫前審計清單（節選）：verb-noun 命名與命名空間；描述覆蓋 what / when / returns；參數含類型、約束、默認值與示例；成功與錯誤 payload 可解析；錯誤含重試指引；與同目錄其他工具無重疊激活場景；大響應支持 concise 或文件引用模式。

設計質量可從五維自檢：unambiguity、completeness、recoverability、efficiency、consistency。Skill 還提供「工具測試 Agent」模式：收集失敗樣例，讓 Agent 分析描述缺口並迭代 description（效率提升需在你的工具目錄上覆現驗證）。

安裝與啓用¶

本 Skill 採用倉庫統一的 SKILL.md 格式，源碼路徑爲：

https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/tool-design

目錄內除 SKILL.md 外，還有 references/（如 best_practices.md、architectural_reduction.md）供深入閱讀。

啓用方式取決於你所用的 Agent 產品如何加載 Skill：將上述目錄（或其中 SKILL.md 及引用文件）加入該產品約定的 Skills 路徑，並在任務涉及「工具描述 / schema / MCP 工具集」時由路由邏輯選中 tool-design。官方 SKILL 未單獨列出 Cursor、Codex CLI 或 Claude Code 的差異配置，此處不臆造安裝命令；以你當前環境的 Skill 加載文檔爲準，並保證 name: tool-design 與 front matter 中的 description 可被識別。

Skill 元數據中的 description 摘要如下，供路由參考：

name: tool-design
description: "This skill should be used for the tool-interface layer of an agent system specifically: writing tool descriptions agents can route on, designing tool schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, tool-set consolidation, and deciding when to add or remove an individual tool. ..."

典型用法示例¶

良好工具描述（官方 Example 1）¶

下面展示 description 如何同時承載「何時用、參數格式、返回與錯誤碼」：

def get_customer(customer_id: str, format: str = "concise"):
    """
    Retrieve customer information by ID.

    Use when:
    - User asks about specific customer details
    - Need customer context for decision-making
    - Verifying customer identity

    Args:
        customer_id: Format "CUST-######" (e.g., "CUST-000001")
        format: "concise" for key fields, "detailed" for complete record

    Returns:
        Customer object with requested fields

    Errors:
        NOT_FOUND: Customer ID not found
        INVALID_FORMAT: ID must match CUST-###### pattern
    """

反例與失敗模式（官方 Example 2）¶

def search(query):
    """Search the database."""
    pass

Skill 歸納的問題包括：名稱含糊、缺少庫與查詢格式、無返回與錯誤說明、無與其他工具的邊界——易導致誤選工具、亂填參數、無法解讀結果、無法從錯誤恢復。

用失敗樣例迭代描述（Tool-Testing Agent 思路）¶

官方給出的優化流程骨架：Agent 在多任務上試調工具 → 收集失敗 → 分析描述缺失與歧義 → 改 description → 同任務迴歸。實現上可用類似下面的 prompt 結構（摘自 SKILL）：

def optimize_tool_description(tool_spec, failure_examples):
    prompt = f"""
    Analyze this tool specification and the observed failures.

    Tool: {tool_spec}

    Failures observed:
    {failure_examples}

    Identify:
    1. Why agents are failing with this tool
    2. What information is missing from the description
    3. What ambiguities cause incorrect usage

    Propose an improved tool description that addresses these issues.
    """
    return get_agent_response(prompt)

適用場景與注意¶

適合誰：正在爲 Agent/MCP 設計或維護工具目錄的工程師；遇到選型錯誤或參數畸形需要系統性改接口而非只改 system prompt 的團隊；準備在接入新 MCP Server 前做合併與命名審計的場景。

限制與坑（來自官方 Gotchas，擇要）：

• 描述隨 API 演進會「腐爛」，應像代碼一樣版本化並在 API 變更時迴歸測試。
• MCP 多提供方易出現同名 search 等碰撞，必須用 ServerName:tool_name 並審計衝突。
• 單工具參數過多（Skill 提示超過約 8–10 個或承載完全不同 workflow）應考慮拆分。
• 可選參數爆炸時，用合理默認值與 format preset，少用裸 optional 堆砌。

與同集合 Skill 的銜接：context-fundamentals 解釋工具定義如何佔用注意力；evaluation 覆蓋工具集整體效果評估；接口層以外的決策應顯式路由到對應 Skill。

結尾¶

tool-design 把「工具能不能被 Agent 可靠調用」收斂到可執行的契約設計：合併與命名、描述結構、響應與錯誤、MCP 限定名，以及用真實失敗驅動迭代。若你當前的工作單元正是某一個工具或整份工具目錄，優先按該 Skill 的審計清單改接口，往往比繼續堆 prompt 更省回合。

官方地址：https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/tool-design