工具返回值要按「给人看」设计：结构化、摘要与溯源

工具返回一大坨 JSON，模型抓不到重点。本文给出结构化字段规范、人类可读摘要的做法与校验、溯源三要素（trace/版本/来源）、工具描述该写什么，以及三个反模式与一条判据。

工具返回的东西，模型往往"读不懂"

工具调用常见问题是：接口返回**一大坨 JSON** ✗，模型抓不到重点 ✔，

于是要么漏用结果 ✗、要么把无关字段当结论 ✗。

**工具返回值要按"给人看"的标准设计** ✔：结构化 + 摘要 + 溯源 ✔。

**稳定字段**（`status` / `data` / `error` / `trace_id` ✔）比"每次不一样的结构"好得多 ✔；

**状态要显式**（成功/部分成功/失败 ✔），不要用"有没有字段"暗示结果 ✗；

**数值带单位**（`{"amount": 1280, "currency": "CNY"}` ✔ 而不是 `"1280元"` ✗）；

**时间用 ISO 8601** ✔（见多语言坑那篇 ✔）。

除了原始数据，额外给一段**人类可读摘要** ✔：

```

{ "status": "ok",

"summary": "查到 3 条订单：最近一单 2024-05-12，金额 1280 CNY，状态已发货",

"data": [ ... ],

"trace_id": "..." }

```

**摘要要包含"决策需要的最小信息"** ✔（数量、最相关的一条、异常 ✔），

但**不能替代 data** ✗（模型需要细节时还能查 ✔）。

⚠️ **摘要也要可核对** ✔：摘要里的数字必须能在 data 里找到（程序做子串/数值校验 ✔）。

否则摘要会变成第二处编造源 ✗。

**`trace_id`**（把这次工具调用与上游请求串起来 ✔）；

**数据版本/时间**（"截至 2024-05-12 的数据" ✔ —— 让模型能说实话 ✔）；

**来源**（哪个系统、哪张表/接口 ✔）。

这个工具**适合什么、不适合什么** ✔；

**关键字段的含义**与**常见陷阱**（例如"金额已含税" ✔）；

**失败时返回什么**（含错误码含义 ✔），便于模型决定是否重试 ✔。

**返回整表**（几百行 ✗）→ 模型读不完，也容易误用 ✔；

**返回空对象**（`{}` ✔）→ 无法区分"没有数据"与"调用失败" ✗；

**字段名用缩写**（`amt`/`st` ✔）→ 模型猜错 ✗（见工具设计那篇：命名要直白 ✔）。

> 把工具返回值**单独贴给一个不熟悉该系统的人** ✔，他能否在 30 秒内说出"发生了什么、关键数字是多少" ✔？

> 不能，说明返回值还没按"给人看"设计 ✗。