Seven Mental · 心智七篇
中 EN
← Knowledge Atlas · Concept

Tool Design（工具设计）

工具设计：格式选择、文档质量、防误设计（poka-yoke）
念
CONCEPT · TOOL DESIGN · ACI IN PRACTICE · POKA-YOKE · MINIMAL TOOLSET · DUAL-MODE

Tool Design

Tool Design — the engineering practice of designing tool interfaces for LLM agents, on par with prompt engineering

Tool definitions and specs deserve the same prompt engineering effort as the overall prompt. The most common agent failure mode: a bloated toolset — overlapping coverage or ambiguous decision points. Golden rule: if a human engineer cannot determine with certainty which tool to use in a given situation, neither can the agent.

Core design principles
Format choicePick the format the model can most easily produce — close to formats naturally present in training data, give the model enough tokens to “think”, and avoid format overhead (exact line counts, string escaping)
Poka-yokeMake mistakes hard via parameter design, not prompt nagging — mistake-proof design beats warning text
Minimal toolsetSecond-order benefits of a lean toolset: less choice ambiguity, and more reliable context maintenance and pruning
CLI-Anything dual-mode dual-output
Dual interaction modes
Same binary: no-arg enters REPL (multi-step iteration) / with args acts as one-shot call — serves humans and agents at once
Dual output formats
Built-in —json flag toggles machine-readable structure vs human-readable tables — no extra SDK needed
Return-value efficiency
Verbose tool output directly consumes the model’s attention budget — keep returns compact
→ ACI · Context Engineering · REPL for AgentsAnthropic / CLI-Anything

Tool Design（工具设计）

定义

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

核心要点

  1. 格式选择：同一个操作可以有多种表示方式（diff vs 重写文件、markdown code block vs JSON）。选择 LLM 最容易正确生成的格式：

    • 给模型足够的 token 来”思考”，避免一开始就把自己写进死角
    • 格式接近模型在训练数据中自然见过的
    • 没有格式开销（如维护精确行数、对代码做字符串转义）

  2. 文档质量：好的工具定义应包含使用示例、边界情况、输入格式要求、与其他工具的清晰边界。

  3. 防误设计（Poka-yoke）：通过改变参数设计让犯错更难，而不是靠提示词约束。

Token 效率与 Context Engineering

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

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

双模式 + 双输出：CLI-Anything 的具体模式

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

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

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

相关概念

References

  • sources/anthropic_official/building-effective-agents.md
  • sources/anthropic_official/effective-context-engineering-for-ai-agents.md