# Writing Effective Tools for AI Agents

> 原文链接：https://www.anthropic.com/engineering/writing-tools-for-agents
> 作者/来源：Anthropic Engineering
> 阅读日期：2026-04-02

## 一句话总结
为 AI agent 设计工具需要从根本上转变软件设计思维——从确定性模式转向非确定性模式，遵循"选择正确工具、清晰命名空间、有意义的返回、token 效率优化、精炼工具描述"五大原则。

## 核心论点

文章的基础洞察是区分 **Tools 与传统 API** 的本质差异。传统函数如 `getWeather("NYC")` 产生确定性输出，而 tool 连接的是确定性系统和非确定性 agent。当用户提问时，agent"可能调用天气工具、从通用知识回答、或先询问位置"——这种不确定性要求完全重新思考软件设计哲学。

Anthropic 提出了三阶段开发工作流：**原型构建**（用 Claude Code 和 llms.txt 文件快速实现初版）→ **全面评估**（生成基于真实工作流的评估任务，而非简单沙箱场景）→ **迭代改进**（分析 agent transcript 找到困惑点，用 held-out test set 防止过拟合）。

五大设计原则构成了文章的核心框架：

**选择正确的工具**：更多工具不一定带来更好性能。不应简单包装现有 API 端点——agent 面临 context constraints，不像计算机有充裕内存。应该用 `search_contacts` 替代 `list_contacts`，用单个 `schedule_event` 整合 `list_users` + `list_events` + `create_event`。

**命名空间清晰化**：使用统一前缀（如 `asana_search`, `asana_projects_search`）帮助 agent 在数百个工具中导航。Agent 可能"调用错误的工具、用错误参数调用正确的工具、调用太少工具、或错误处理工具响应"。

**有意义的返回值**：优先返回语义信息（`name` 而非 `uuid`），自然语言标识符能显著减少 hallucination。创新技巧：暴露 `response_format` 枚举参数，让 agent 按需选择 `"concise"`（72 token）或 `"detailed"`（206 token）返回。

**Token 效率优化**：实现分页、范围选择、过滤和截断，设置合理默认值。错误消息应引导 agent 采用更好的策略。

**精炼工具描述**：如同向新团队成员解释工具，将隐含 context 显式化，使用无歧义的参数名（`user_id` 而非 `user`）。

## 关键概念
- **确定性 vs 非确定性设计**：传统 API 为确定性调用者设计，tool 需要为非确定性的 LLM agent 设计
- **Context Constraints**：agent 的信息处理容量是有限的，不同于计算机的充裕内存，工具设计必须考虑这一限制
- **Tool Consolidation（工具整合）**：将多步骤工作流整合为单个工具，减少 agent 的决策负担
- **Response Format 枚举**：让 agent 自主选择返回详细程度的创新机制，兼顾灵活性和 context 效率
- **工具描述即 Prompt Engineering**：tool description 的精炼能带来戏剧性的性能提升，Claude Sonnet 3.5 通过精炼工具描述达到了 SWE-bench SOTA

## 实践建议
1. 不要简单包装现有 API——重新设计面向 agent 的工具接口，整合多步骤操作
2. 使用统一的命名前缀组织相关工具，降低 agent 的工具选择认知负担
3. 工具返回值优先使用自然语言标识符而非技术 ID，减少 hallucination
4. 实现 `response_format` 参数让 agent 控制返回的详细程度
5. 错误消息要有指导性——告诉 agent "应该怎么做"而非只报错误代码
6. 基于真实工作流创建评估任务，分析 agent transcript 中的困惑点进行迭代优化
7. 使用 held-out test set 防止工具设计过拟合到特定测试场景
8. 关注 agent 推理中**没有提到**的信息——沉默往往暗示着工具设计问题

## 独到观点
最独到的贡献是 `response_format` 枚举参数的设计——让 agent 自适应地选择信息粒度，这比固定返回格式或让 agent 事后过滤都更优雅。此外，"关注 agent 推理中没有提到的信息"这一调试技巧极具实践价值。文章还分享了一个有趣的真实案例：Claude 在 web search 时自动在查询中附加"2025"年份，导致结果偏差——通过改进工具描述就解决了问题，无需修改底层功能。

## 与其他文章的关联
- 与 **Code Execution with MCP**（#17）直接互补：工具设计原则决定了 Code APIs 方案中工具文件的质量
- 与 **HumanLayer Backpressure**（#13）理念一致：`response_format` 参数是工具层面的 backpressure 机制，控制返回信息量
- 与 **Writing a Good CLAUDE.md**（#15）相关：工具的使用说明需要在配置文件中高效传达
- 与 **Claude Code Best Practices**（#23）关联：工具设计是 Claude Code 生态的重要组成部分
- 与 **Fowler SDD Tools**（#24）互补：两者都关注工具设计，但侧重点不同——Anthropic 侧重 MCP 工具设计原则，Fowler 侧重开发流程中的工具链
- 与 **OpenHands Context Condensation**（#14）相关：token 效率优化是两篇文章的共同主题