Tool Design（工具设计）

工具设计：格式选择、文档质量、防误设计（poka-yoke）

念

概念 · TOOL DESIGN · ACI 实践 · Poka-yoke · 最小可行工具集 · 双模式

工具设计

Tool Design — 为 LLM agent 设计工具接口的工程实践，与 prompt 工程同等重要

工具定义和规格需要与整体 prompt 同等程度的 prompt engineering。最常见的 agent 失败模式：膨胀的工具集——覆盖太多功能或导致歧义决策点。黄金原则：如果人类工程师无法确定性地说出在某情境下该用哪个工具，agent 也做不到。

核心设计原则

格式选择选择模型最容易正确生成的格式——接近训练数据中自然出现的格式，给模型足够 token 来「思考」，避免格式开销（精确行数、字符串转义）

Poka-yoke通过改变参数设计让犯错更难，而不是靠提示词约束——防误设计优于警告文字

最小工具集精简工具集的二阶收益：减少选择歧义，同时使 context 的维护和修剪更可靠

CLI-Anything 双模式双输出模式

双交互模式

同一二进制：无参进 REPL（多步试错）/ 有参做一次性调用——同时服务人类和 agent

双输出格式

内建 —json flag 切换机器可读结构和人类可读表格——无需额外 SDK

工具返回值效率

冗余的工具输出直接消耗模型的注意力预算——返回值应尽量紧凑

→ ACI · Context Engineering · REPL for AgentsAnthropic / CLI-Anything

为 LLM agent 设计工具接口的工程实践。工具定义和规格需要与整体 prompt 同等程度的 prompt engineering。

格式选择：同一个操作可以有多种表示方式（diff vs 重写文件、markdown code block vs JSON）。选择 LLM 最容易正确生成的格式：
- 给模型足够的 token 来”思考”，避免一开始就把自己写进死角
- 格式接近模型在训练数据中自然见过的
- 没有格式开销（如维护精确行数、对代码做字符串转义）
文档质量：好的工具定义应包含使用示例、边界情况、输入格式要求、与其他工具的清晰边界。
防误设计（Poka-yoke）：通过改变参数设计让犯错更难，而不是靠提示词约束。

Effective Context Engineering 从 context engineering 的角度补充了工具设计的效率维度：

工具返回值的 token 效率：工具定义了 agent 与信息/行动空间的契约，返回值应尽量紧凑——冗余的工具输出直接消耗模型的注意力预算
最小可行工具集：膨胀的工具集覆盖太多功能或导致歧义决策点，是最常见的 agent 失败模式。如果人类工程师无法确定性地说出在某情境下该用哪个工具，agent 也做不到
工具集精简的二阶收益：较少的工具不仅减少选择歧义，还使 context 的维护和修剪更可靠

CLI-Anything 从实践中归纳出两个可直接迁移的工具设计 pattern：

双交互模式：同一个二进制既是 subcommand CLI（scripting/pipeline），也是有状态 REPL（多步试错）——无参进 REPL，有参做一次性调用。详见 repl-for-agents
双输出格式：每个命令内建 --json flag，切换机器可读结构和人类可读表格；agent 通过 --help / which 等 POSIX 原语发现能力，无需额外 SDK

这两个模式合起来让同一个工具同时服务人类和 agent 两种用户类型，是 agent-native-software 原则在工具层的具体实现。