Tool Use 与工具契约

工具不是给人看的 API 文档，而是给模型看的能力契约。同一段业务逻辑，描述写法不同，工具调用成功率可以差出一倍。这一章讲四件事：描述怎么写、参数怎么约束、错误怎么分类回喂、以及什么时候该上 MCP。

编辑部注 · 这一章的内容可以直接拿去改你手上的 Harness —— 它是投入产出比最高的一层。

先纠正一个常见误解：工具调用的失败，多数不是模型「不会用」，而是模型「不知道该怎么用」。你要给它的不是接口签名，而是判断依据——什么时候用这个工具、参数填什么范围、返回的结构长什么样、出错时代表什么。

一、工具是契约，不是接口

一个完整的工具契约包含七个要素。少任何一个都会以某种方式转化为线上问题——其中 工具描述（Tool Description） 与 参数 schema（Parameter Schema） 直接决定模型「会不会用、用得对不对」：

二、错误分类：决定重试有没有意义

这是本章最有工程价值的部分，核心是 错误分类（Error Taxonomy）。工具执行失败时，Harness 只有两种选择：抛出异常终止，或者把错误回喂让模型换策略。而回喂的内容决定了第二次尝试有没有意义——尤其要注意 空结果（Empty Result）：查询成功但无数据，必须和「失败」区分开，否则模型会陷入换关键词空转。

三、让调用不可能出错：三层约束

按「结构的强制程度」从弱到强排列：

第一层，描述约束。 在描述里写清取值范围与范例。靠模型自觉，最弱但成本最低。

第二层，schema 约束。 用 JSON Schema 的 enum、minimum、maximum、pattern、required 把非法输入堵死，这本质上是在强制 结构化输出（Structured Output）。多数模型 API 在结构化输出模式下会直接保证符合 schema。

第三层，执行前校验（Pre-execution Validation）。 无论前面怎么写，Handler 入口必须再校验一遍——因为模型可能根本不走结构化输出通道，或者你做了参数转换。而「校验」的前提是「先解析出来」：模型常返回带 markdown 代码块包裹、尾随逗号甚至注释的 JSON，严格解析会直接抛异常，所以入口处常用宽容解析（Lenient Parsing）先把结构抽出来，再对内容做严格校验——「宽容解析 + 严格校验」的组合，比「严格解析 + 宽容校验」有效得多（后者在解析阶段就已崩，校验根本没机会跑）。对有副作用的工具，还要配合 幂等键（Idempotency Key） 在重试时去重。

from dataclasses import dataclass
from typing import Any, Callable
import json
@dataclass
class ToolResult:
    """统一返回协议：状态是显式的，绝不靠异常或空值暗示"""
    status: str            # ok | empty | bad_args | forbidden | not_found | timeout | upstream
    data: Any = None
    message: str = ""      # 给模型看的一句话说明
    retryable: bool = False
    side_effect_done: bool = False   # 副作用是否已经发生（决定能否安全重试）
    cost: float = 0.0
    def to_observation(self) -> str:
        """回喂给模型的字符串：状态 + 说明 + 精简数据"""
        head = f"[{self.status.upper()}] {self.message}"
        if self.data is None:
            return head
        body = json.dumps(self.data, ensure_ascii=False)
        return f"{head}\n{body[:1800]}"
def search_articles(q: str, limit: int = 10) -> ToolResult:
    # --- 第三层：执行前校验（不信任任何上游） ---
    if not isinstance(q, str) or not q.strip():
        return ToolResult("bad_args", message="参数 q 不能为空，请给出中文关键词。")
    if not (1 <= limit <= 20):
        return ToolResult("bad_args",
                          message=f"limit 必须在 1-20 之间，当前为 {limit}。",
                          data={"allowed": [1, 20]})
    try:
        rows = db_search(q, limit)                     # 真实查询
    except TimeoutError:
        return ToolResult("timeout", message="查询超时，这是瞬时问题，可原样重试。",
                          retryable=True)
    except PermissionError:
        return ToolResult("forbidden", message="当前身份无权访问该数据源，重试无用。")
    # --- 空结果不是错误 ---
    if not rows:
        return ToolResult("empty",
                          message=f"查询成功，但没有匹配「{q}」的文章。"
                                  f"建议换更宽的关键词，或确认该主题确实没有内容。",
                          data={"items": [], "hint": "可尝试同义词或去掉限定词"})
    return ToolResult("ok", data={"items": rows[:limit], "total": len(rows)},
                      message=f"命中 {len(rows)} 条。",
                      cost=0.001)
# ---------------------------------------------------------------
# 有副作用的工具必须带幂等键
# ---------------------------------------------------------------
IDEMPOTENCY_STORE: dict[str, ToolResult] = {}
def send_notification(user_id: str, text: str, idempotency_key: str) -> ToolResult:
    """
    不可逆操作的正确姿势：
      1. 要求调用方提供幂等键
      2. 同一个键重复调用直接返回上次结果，不重复执行
      3. 返回值必须说明「副作用是否已经发生」
    """
    if idempotency_key in IDEMPOTENCY_STORE:
        prev = IDEMPOTENCY_STORE[idempotency_key]
        return ToolResult("ok", data=prev.data,
                          message="该请求此前已成功执行过，本次未重复发送（幂等命中）。",
                          side_effect_done=True)
    if not text.strip():
        return ToolResult("bad_args", message="通知内容不能为空。")
    resp = api_send(user_id, text)                     # 真实发送
    res = ToolResult("ok", data={"message_id": resp["id"]},
                     message="已发送。", side_effect_done=True, cost=0.01)
    IDEMPOTENCY_STORE[idempotency_key] = res
    return res
def db_search(q, limit): raise NotImplementedError
def api_send(user_id, text): raise NotImplementedError

四、什么时候该用 MCP

MCP（Model Context Protocol）（Model Context Protocol）解决的是工具供给的标准化问题，不是工具设计的质量问题。用不用的判据很清楚——有 副作用等级（Side-effect Level） 的工具在调用前必须确认，而 调用成本提示（Cost Hint） 能阻止模型反复敲昂贵接口：

但要记住：MCP 不解决工具描述写得差的问题。 一个描述糟糕的 MCP 工具，接入之后依然会被误用。协议标准化与契约质量是两件事。

把工具当接口写，模型会当接口用——参数填得对，语义完全错。把工具当契约写，模型才知道你的系统期望它做什么。本刊编辑部

五、常见误区与追问

5.1 误区：工具描述是「文档」，写短一点省 token

错在哪：把描述当成占 token 的成本项，而不是决定成功率的输入。为什么自然：描述越长，每轮请求的常驻前缀越大，看着确实是在烧钱。判据：先算账再决定删不删——描述属于常驻前缀，前缀稳定时它被缓存复用，边际成本接近零；而描述含糊带来的每一次误调用，都要额外一轮「失败→回喂→重试」，那一轮的输入是完整上下文。所以「描述多写 300 token」和「多跑一轮 4k token」不是一个量级的取舍。要压就压真正冗余的部分，例如重复的业务背景、与调用无关的实现细节。

5.2 误区：把该写在 schema 里的约束写进系统提示词

错在哪：用概率性手段去实现确定性约束。为什么自然：改提示词看起来更快。判据：凡是能用 enum、minimum、maximum、required 表达的限制，都不该写进提示词——schema 约束下非法输入在结构上不可能出现，提示词约束下它只是变得不太可能。检查方法：把提示词里带数字或范围的句子抄出来，逐条问「这条能不能写成 schema 字段」；能改而没改的，就是留给线上事故的口子。提示词该留的是 schema 表达不了的东西：什么时候用、什么时候换别的。

5.3 误区：错误回喂就是把异常信息打印给模型

错在哪：把「让模型看到错误」当成「让模型能修正错误」。为什么自然：try/except 里直接拼一句 str(e) 只需要一行。判据：回喂内容必须回答三个问题——哪个字段错了、合法取值是什么、这次该不该重试。原始堆栈只能回答第一个，而且往往答不清：invalid literal 不会告诉模型 limit 应该落在 1–20。只回喂堆栈时，模型通常会原样重试 2–3 次才想到换参数，那是 2–3 轮完整上下文的成本；说清合法区间，第一次改参数就能过。

5.4 误区：有了重试就不需要幂等

错在哪：把「重试」和「重复执行」当成两件事，而不是同一件事的两种叫法。为什么自然：重试看起来只是再发一次请求，没人觉得危险。判据：最容易出事的是超时——服务端可能已经执行完、只是响应在路上丢了，此时重试就是第二次执行。挡住它的唯一办法是幂等键，而键必须由调用方按「操作意图」生成（任务 ID + 步骤序号），绝不能是时间戳或随机 UUID，否则每次重试都是新键，去重表永远命中不了。检查动作：把服务端的去重记录捞出来，看同一个业务对象有没有两条来自同一任务的记录。

5.5 误区：上了 MCP 就解决了工具接入的乱象

错在哪：把「供给标准化」当成「质量提升」。为什么自然：MCP 确实让同一份能力可以跨产品复用，看起来是全面的进步。判据：它解决的是「一次实现、N 处接入」的成本问题，一个字都没规定工具该怎样命名、描述怎么写、错误怎么分类。描述含糊的 MCP 工具接进来照样被误用，七要素一条都不能省。反过来也成立：如果这份能力只服务一个产品、调用链又极短，引入 MCP 只会多一层进程与协议开销，收益为负。所以判据是「它需不需要被第二个产品复用」，而不是「MCP 是不是更先进」。

六、自测

七、小结

• 工具是契约：名称、用途、参数、返回、幂等性、副作用等级、成本提示，七项齐全。
• 描述要回答四个问题：做什么 / 何时用 / 参数怎么填 / 返回什么。
• 错误要分类：可重试、必须改参数、重试无用，三类处理方式完全不同。
• 空结果不是错误，必须在协议层与失败区分。
• 有副作用的操作要有幂等键，且键必须来自调用方。
• MCP 解决工具供给标准化，不解决工具设计质量。

下一章处理那个决定效果上限的层：模型到底能看到什么。

八、参考与延伸

工具这一层的理论文献很薄，但官方文档质量极高——因为各家模型厂都在教人怎么写工具。下面按「先看怎么写、再看协议、最后看怎么量」排好。全站不做原文转载，这里只登记链接与「为什么值得读」。

先看怎么写（契约的四个层次）

• Anthropic · Writing Tools for Agents —— 目前最接近「工具描述实操手册」的一篇：命名怎么起、描述该写哪几段、返回结构怎么设计、错误怎么回喂，都给了改前改后的对照。把它和本章第一节的七要素表并排放着看，重合的部分可以直接照抄着改你自己的工具——这是本章所有延伸材料里唯一「当天就能用」的一份。
• Anthropic · Prompt Engineering Overview —— 标题像讲措辞，但有大半篇幅在讲工具定义、结构化输出这类确定性通道的正确用法。想彻底弄清「哪些约束该交给 schema、哪些只能靠提示词」，这一页把边界划得最清楚；本章第三层约束的设计标准就是从这里来的。

再看协议（工具怎么供给）

• Model Context Protocol 官方站 —— 规范、各语言 SDK、示例 server 都在这一站，读 Getting Started 一页足够建立全貌。本章第四节说「MCP 解决供给标准化、不解决设计质量」，读完规范你会确认这一点：它定义的是传输与方法，一个字都没规定描述该怎么写。
• OpenAI Cookbook —— 函数调用、结构化输出、并行工具调用都有可直接跑的 notebook。想验证「schema 约束到底能拦住多少错参数」，照它的结构化输出示例改一版你自己的工具，一个下午就能拿到自己的数据，而不必相信任何人的说法。

最后看怎么量（调用得对不对）

• τ-bench（sierra-research/tau-bench） —— 它的评分同时看「参数是否准确」和「是否在正确的时机调用了正确的工具」。这正好对应本章强调的那条区别：参数填对但语义用错，是最难被单测发现的失败形态；只统计工具调用成功率是看不出来的。