Agent tool design

何时使用

为 Agent（语言模型） 而非人类开发者设计工具时使用。工具是 Agent 与世界交互的主要接口，是确定性系统与非确定性 Agent 之间的契约：模型靠工具描述推断契约、推断参数、从自然语言生成调用。设计不当造成的失败，靠堆提示词修不好。

该用：新建 Agent 工具/函数调用；排查工具被漏选、错选、参数填错；优化已有工具集（合并/精简/统一命名）；从零设计工具 API；评估第三方/MCP 工具能否接入；跨代码库统一工具约定。

不该用（边界）：

• 设计给人类调用的普通 REST/SDK API（人类能读文档、理解契约，约束不同）。
• 只是写提示词模板 → 用 prompt-template-designer；只是实现业务逻辑代码 → 这是工程问题不是工具契约问题。
• 任务该用检索而非工具（取文档片段）→ 用 rag-pipeline-builder。

步骤 / 指令

1. 划分工作流，决定工具粒度（合并原则优先）
   - 列出 Agent 必须完成的「独立工作流」
   - 合并原则：若一个人类工程师都说不清某情境该调哪个工具，Agent 更不可能选对
     → 倾向「单个综合工具」覆盖整条工作流，而非多个窄工具让 Agent 自己串
     反例: list_users + list_events + create_event
     正例: schedule_event（内部找空闲并排期，一次调用完成）
   - 不该合并的情形: 行为根本不同 / 使用语境不同 / 会被独立调用的工具，保持分开
   - 经验规模: 多数应用 10~20 个工具；更多则用命名空间(namespace)分组

2. 评估是否做「架构精简」(把专用工具换成通用原语)
   - 适合: 数据层文档良好且结构一致 / 模型推理力足够 / 现有专用工具在「束缚」而非「赋能」模型 / 维护脚手架的时间多于改进结果
   - 不适合: 底层数据脏乱/无文档 / 领域需模型不具备的专门知识 / 有安全约束须限制能力 / 操作确实复杂需结构化工作流
   - 典型模式: 与其为数据探索/查 schema/校验各建专用工具，不如给一个命令执行工具，让 Agent 用 grep/cat/find/ls 等标准 Unix 原语自由组合
   - 反模式: 为「保护」模型而预过滤上下文、限制选项、层层包校验——这些护栏随模型变强会变成负债
   - 拷问每个工具: 它是在「赋能新能力」还是在「束缚模型本可自理的推理」？为「未来更强的模型」留最小架构

3. 写工具描述（描述即提示词，会被载入 Agent 上下文共同引导行为）
   每个描述回答 4 问:
   - What  做什么: 具体、可证伪；禁用「helps with / can be used for」这类空话
   - When  何时用: 直接触发(「用户问定价」)+ 间接信号(「需要当前市场价」)
   - Input 收什么: 每个参数的类型/约束/默认值，说明它控制什么
   - Return 返回什么: 输出结构 + 成功示例 + 错误情形

4. 设默认值 + 选响应格式
   - 默认值反映最常见用法，减少 Agent 必填项、防漏参出错
   - 提供 format 选项: concise(仅关键字段, 省 token) / detailed(完整对象, 决策需要时)
     并在描述里告诉 Agent 何时选哪种

5. 设计可恢复的错误信息（面向两类读者: 调试的人 + 自我恢复的 Agent）
   - 可重试错误 → 给重试指引
   - 入参错误   → 给正确格式
   - 缺数据     → 说明缺什么
   错误必须告诉 Agent「哪错了 + 怎么改」，而非一句通用报错

6. 统一 schema 与命名
   - 工具名用 动词-名词 (verb-noun)
   - 跨工具参数名一致、返回字段名一致 (别一处 id 一处 identifier 一处 customer_id)

7. 用测试集评估并迭代
   - 判据: 无歧义 / 完整 / 可恢复 / 高效 / 一致
   - 拿代表性的 Agent 请求跑，看生成的调用对不对；按观察到的失败模式迭代

MCP 工具命名（硬约束）：引用 MCP 工具一律用全限定名 ServerName:tool_name，否则多服务器时会「tool not found」。

# 正确
"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
"Use the GitHub:create_issue tool to create issues."
# 错误（多服务器时可能失败）
"Use the bigquery_schema tool..."

用 Agent 优化工具（反馈闭环）：把工具规格 + 观察到的失败喂给模型，让它诊断并改进描述。生产实测可把任务完成时间降约 40%。

def optimize_tool_description(tool_spec, failure_examples):
    """1. Agent 跨多任务试用工具  2. 收集失败模式与摩擦点
       3. Agent 分析失败、提改进  4. 用同任务回测新描述"""
    prompt = f"""分析以下工具规格与观察到的失败。
    Tool: {tool_spec}
    Failures observed: {failure_examples}
    识别: 1) 为何失败 2) 描述缺什么信息 3) 哪些歧义导致误用
    给出修复这些问题的改进版工具描述。"""
    return get_agent_response(prompt)

示例

好工具（描述回答 what/when/input/return/errors，参数带格式，错误可恢复）：

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
    """

坏工具（集多个反模式）：

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

问题：名字含糊（搜什么、为何搜）；缺参数（哪个库、query 何格式）；无返回说明；无使用语境（何时用它而非别的工具）；无错误处理。 失败模式：该用更专的工具时也调它；猜不出 query 格式；解读不了结果；失败无法恢复。

注意事项

• 描述即提示词：所有工具描述共同占用上下文预算、共同引导选择。每多一个重叠工具 = 多一份描述 token + 多一处「该选哪个」的歧义。
• 合并 ≠ 万能：行为根本不同、语境不同、会被独立调用的工具别硬绑。
• 别用工具去「束缚」模型：预过滤/限制选项/层层校验这类护栏，随模型变强会变成负债；反复问「赋能还是束缚」。
• 架构精简有前提：数据脏乱、领域需专门知识、有安全约束、操作确实复杂时，精简会失败，仍需结构化工作流。
• 命名一致性是降低认知负荷的关键；MCP 引用必须全限定。
• 错误面向 Agent 恢复，不是只给人看的 stack trace。
• 投资文档质量优先于工具复杂度；研究表明工具描述重叠会让模型混乱，「工具更多」不等于「结果更好」。

互见

• requires：first-principles-thinking —— 划分工作流、判定工具粒度前，先用它把「Agent 到底要完成哪些独立任务」拆清楚，否则会把错误的边界固化进工具集。
• related：prompt-template-designer —— 工具描述本质是提示工程，模板设计的「角色/约束/示例/格式」思路同样适用于写工具描述。
• combines_with：rag-pipeline-builder —— 当 Agent 需要外部知识时，检索管道与工具集协同：检索取上下文、工具执行动作。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。