S21-B03 · Function Calling 与工具设计

适用读者：工具给了模型，但它总调错参数的人。
前置：S21-B01、S20-J03。
覆盖旧文：713(554) + 工具类 2 卡 = 755 点。
覆盖扩展：E-S21-004（schema 设计与参数校验）。
上一篇：S21-B02 · ReAct 与规划：从 CoT 到 Plan-and-Execute
下一篇：S21-B04 · Skills。

1. 一句话结论

工具 schema 是"给模型看的 API 文档"：描述越像"人话"，模型越不会调错。而参数校验必须在你的代码里做——模型只负责提意图。

2. schema 的三个要素（E-S21-004）

{
  "name": "query_order",
  "description": "按订单号查询订单状态。仅在用户提供了订单号时调用。",
  "parameters": {
    "type": "object",
    "properties": {"order_id": {"type": "string", "description": "形如 ORD-2026-0001"}},
    "required": ["order_id"]
  }
}

要素	作用	常见错误
name	模型选哪个工具	名字太抽象（`do`、`handle`）
description	决定调用时机	只写"查询订单"（不说何时用）
parameters	参数结构	缺 `required`、缺示例格式

"description 比 name 更重要"：模型靠描述判断"什么时候该调它"——写清楚"仅在…时调用"能显著减少误调用。

3. 参数校验必须在代码侧

风险	例子
越权	模型生成别人的 `user_id`
注入	参数里带 SQL/命令片段
类型错	该给数组给了字符串

三道校验：

① 结构校验（JSON Schema）
② 业务校验（权限/归属）—— 与 S17-B04 的鉴权同理
③ 副作用校验（写操作的确认/审批，A02）

判据："这个工具改了状态吗？" 改 → 必须有人工确认或审批（A02 §3）。

4. 工具粒度的取舍

粒度	优点	缺点
粗（一个工具做多件事）	工具少、模型好选	参数复杂、易错
细（每个动作一个工具）	参数简单、可审计	工具多、选择困难
组合（Skill 封装）	兼顾	需额外抽象（B04）

判据："这个工具的参数超过 5 个吗？" 超过 → 拆细。

5. 五个误区

误区	真相
"模型会自己校验参数"	不会，必须代码校验
"工具越多越强"	选择困难、误调用上升
"description 随便写"	决定调用时机
"工具能改状态就让它改"	需审批/幂等（S17-J03）
"参数类型错模型会纠正"	不一定

6. 自检

schema 三要素各起什么作用？
description 为什么最重要？
参数校验的三道关？
工具粒度怎么定？
改状态的工具需要什么额外保护？

7. 下一篇

S21-B04 · Skills：工具的组合与复用

工具讲完，下一篇讲"把多个工具打包成一个能力"。

本篇属于系列《S21 · Agent 工程与 MCP》。旧文来源：A-713 + 工具类 2 卡；扩展点 E-S21-004。