工具接口与描述设计（考点 2.1）· CCAF 备考

本页目录5

这个考点是什么

这个考点考查在 Claude Messages API 的 tools 数组里定义自定义（client-side）工具时，name、description、input_schema 这三件套如何共同决定模型「会不会选中这个工具、能不能填对参数」。

工具本身是由你的应用执行的：Claude 只是根据这三个字段判断要不要在某一轮调用它、调用哪一个、传什么参数，返回 stop_reason: "tool_use" 和结构化的 tool_use 块，再由应用把结果通过 tool_result 传回去。

这个考点的核心提法是「描述即路由」：description 不是写给人看的注释，而是运行时唯一用来做工具选择和参数填充判断的自然语言信号。官方文档明确把它称为「迄今为止影响 tool 表现最重要的因素」，一句话式的描述和讲清楚做什么、何时用、参数含义的描述，在效果上有本质差别。

除了单个工具怎么写，这个考点也覆盖工具集层面的设计：相关操作要不要合并成一个工具、多个服务的工具要不要加前缀命名、执行结果该以什么形式喂回给模型。这些都属于「接口设计如何影响模型行为」这一条主线，而不是接口本身的语法细节。

为什么考

典型出题角度集中在几处容易混淆的边界：

一是必需字段的形状——用 OpenAI 风格的 parameters/handler/type/function，或 MCP 连接器风格的 authorization_token/server_name 做干扰项，考是否能认准 Anthropic 自定义工具就是 name+description+input_schema；
二是 name 的正则约束，常用「合法 Python 标识符」「小写 128 字符」等近似规则来试探记忆是否精确；
三是围绕 description 最佳实践、工具粒度（合并 vs 拆分）、namespacing、响应设计这几条最佳实践清单，考察能否分清「推荐做法」与其对应的反模式。

另一类常见考法是把 strict、tool_choice 这类调用控制机制包装成「能保证模型选对工具」的选项，借此检验对 description 与这些机制分工的理解是否清晰。

核心辨析

1
必需字段边界
Anthropic 自定义工具的核心是 name、description、input_schema 三个字段；不存在 output_schema（工具由客户端执行，结果靠 tool_result 回传，API 本身不需要输出 schema），parameters/handler、type/function/arguments 是 OpenAI function-calling 的形状，authorization_token/server_name 属于 MCP 连接器服务器定义，都不是同一件事。
2
name 的正则约束
必须匹配 ^[a-zA-Z0-9_-]{1,64}$，即 1–64 位 ASCII 字母、数字、下划线、连字符。这个范围比「合法 Python 标识符」更宽（允许连字符、允许数字开头）也更窄（不允许非 ASCII 字符），不能用后者替代记忆。
3
description 是最重要因素，而不是可选装饰
要写清楚工具做什么、什么时候该用/不该用、每个参数的含义与影响、有哪些限制，官方建议至少 3–4 句起；一句话式描述（如「Gets the stock price for a ticker.」）即使 input_schema 写得再规范，也无法弥补描述缺失带来的选错/用错。
4
工具粒度不是越细越好
把相关操作拆成 create_pr/review_pr/merge_pr 等近似同名工具，反而增加模型在多个相似选项间做选择的难度；推荐做法是合并成一个工具、用 action 参数区分，把决策点从「选哪个工具」下沉到「填哪个参数值」。
5
namespacing 用于消歧，不是审美偏好
工具集跨越多个服务/资源时按服务前缀命名（如 github_list_prs、slack_send_message），工具数量越多、尤其配合 tool search 一类机制时，名字本身也在承担一部分路由职责。
6
响应设计同样属于接口设计
工具执行完返回给模型的内容应只保留高信号字段，用稳定的语义化标识符（slug/UUID）代替不透明的内部引用，而不是把完整原始 payload 塞回去——冗余信息浪费上下文，也让模型更难抓住下一步真正需要的数据。

反模式对照

常见做法

把 description 写成一句话概括，例如「Gets the stock price for a ticker.」

正确做法

写 3–4 句以上，覆盖工具做什么、何时该用/不该用、每个参数的含义与影响、任何限制或 caveat

官方文档把详细描述称为「迄今为止最重要的因素」，并直接给出好/差两版同一工具的描述对照，差版本正是这种一句话写法。

常见做法

为每个动作单独建一个近似同名的工具，如 create_pr、review_pr、merge_pr 各一个

正确做法

合并为一个工具，用 action 参数区分不同操作

选哪个工具本身就是一次决策，近似同名的工具越多，这次决策越容易出错；把差异放进参数，决策只需要发生一次。

常见做法

工具返回值原样塞入完整 API 响应或内部技术性 ID，指望模型自己从中挑出有用信息

正确做法

只返回高信号字段，并用稳定的语义化标识符（slug/UUID）代替不透明的内部引用

冗余字段消耗上下文，也让模型在后续推理里更难定位真正需要的数据。

常见做法

以为设置 strict: true，或把 tool_choice 设为 any/tool，就能保证模型选对、用好这个工具

正确做法

strict 只保证工具输入严格符合 input_schema,tool_choice 只控制是否调用/调用哪一个；能否选对合适的工具，本质上仍取决于 description 的质量

这是两个不同维度的机制——一个管输入格式，一个管调用与否——都替代不了把描述写清楚这件事。

练这个考点

练习模式支持按考点专练（需 Google 登录，不占用正式考机会）。

专练考点 2.1

该考点的公开题（免登录，含完整解析）：