前言¶

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