别再像写代码一样给AI造工具了，Anthropic内部5条心法让模型变超人

摘要

你给AI的工具越强大，它可能反而越笨。这是因为我们一直在用确定性思维设计工具，喂给不确定的模型。本文揭示Anthropic内部优化AI工具的完整流程与5条核心原则，帮你彻底扭转智能体“不好用”的局面。

我们给AI智能体（Agent）打造工具的方式，从根上就错了。

这是大多数开发者在实践中碰壁后，才不情愿承认的残酷现实。我们以为给AI的工具越多、越像标准的API，它的能力就越强。

然而现实恰恰相反——你给AI一把功能齐全的瑞士军刀，它却反复用开瓶器去拧螺丝，甚至干脆对着木头瞎比划。它会犯错、会困惑、会陷入低效的循环，最终让你感叹：“这AI怎么这么笨？”

问题不在AI，而在我们。我们习惯了为确定性系统编写软件，每一行代码都追求精确、无歧义的输入输出。但AI智能体，本质上是一个非确定性系统。用程序员的旧地图，永远找不到AI新大陆。

这篇文章，不是又一篇教你写提示词的技巧帖。它是一份来自Anthropic内部的实践复盘，一套完整的、用AI优化AI工具的思维框架和工作流程。它将帮你理解并掌握那5条能让你的AI智能体脱胎换骨的核心心法。

真正释放AI潜力的关键，在于从“程序员”思维，转变为“AI教练”思维。

以下是实现这一转变的5个本质洞察：

1. 思维重置AI不是机器，而是“实习生”。停止用机器指令喂养它，要用它能理解的工作流去引导它。
2. 流程再造建立“原型-评估-AI协同优化”的闭环，让数据而非直觉，驱动工具的每一次迭代。
3. 设计升维工具的价值核心是“赋能一个工作流”，而不是“简单封装一个API”。
4. 沟通校准工具的描述和返回信息，就是你与AI的沟通界面，每一个词都可能决定成败。
5. 情境为王AI的“上下文窗口”是它最宝贵的认知资源，一切设计都应以节省和优化这份“预算”为中心。

一、忘掉API，拥抱工作流

一个常见的错误，是把现有的软件功能或API端点，一对一地封装成工具丢给AI。

这为什么是错的？

因为AI和传统软件看待世界的方式完全不同。传统软件可以不知疲倦地处理海量信息，内存廉价又充足。而AI的“上下文”——也就是它能同时处理的信息量——是极其有限且昂贵的。

想象一下，你要在一个通讯录里找人。传统程序会加载整个列表，然后逐一比对，高效无误。

但如果让AI用一个返回所有联系人的 ​​list_contacts​​ 工具，就等于逼它把整本电话本从头到尾读一遍。这不仅浪费了宝贵的上下文空间，还极易出错。

对AI（以及人类）来说，更自然的方式是直接翻到对应的字母索引页。

所以，正确的做法是打造面向工作流的工具。

• 错误示范提供​​list_users​​​、​​list_events​​​、​​create_event​​ 三个独立工具。
• 正确示范实现一个​​schedule_event​​ 工具，它在内部处理查找参会者、检查日历、最终创建事件的全部逻辑。
• 错误示范提供一个​​read_logs​​ 工具，让AI自己去大海捞针。
• 正确示范实现一个​​search_logs​​ 工具，只返回最相关的几行日志和前后文。

你的每一个工具，都应该让AI能够像人类专家一样，大刀阔斧地切分和解决问题，而不是陷入琐碎的操作细节。

Anthropic在对其内部的Slack和Asana工具进行优化时发现¹，整合后的工作流工具，相较于零散的API封装工具，在复杂任务上的成功率实现了大幅跃升。

二、用AI来打磨AI的“武器库”

如何知道你的工具设计得好不好？答案是：建立一个严格的评估体系，然后让AI帮你找到答案。

这个过程分为三步：构建原型、运行评估、协同优化。

首先，快速构建工具原型。然后，让Claude这样的代码智能体帮你生成大量的评估任务。这些任务必须源于真实世界，足够复杂，可能需要调用数十次工具才能完成。

例如，一个强评估任务是：“帮我和Jane约个会，讨论Acme项目。附上上次会议的纪要，并预定一间会议室。”

而一个弱评估任务是：“给jane@acme.corp发邮件。”

接下来，通过API调用，让评估智能体在循环中自动执行这些任务。在这个过程中，除了验证结果是否正确，更要让智能体输出它的“思考过程”和“反馈”。你会惊讶地发现，AI能告诉你很多你没想到的问题——比如某个工具描述有歧义，某个参数名让它困惑，或者两个工具功能重叠。

最后，把所有失败的案例、AI的思考过程和反馈，一股脑丢给Claude Code，让它来分析和重构你的工具代码。

这个闭环，就是用魔法打败魔法。

三、你的返回，决定AI的下一步

工具返回给AI的信息，不是越多越好，而是越“有信号”越好。

AI对充满技术术语的返回内容感到“消化不良”。诸如 ​​uuid​​​、​​256px_image_url​​​、​​mime_type​​​ 这样的字段，远不如 ​​name​​​、​​image_url​​​、​​file_type​​ 来得直接。

一个惊人的发现是，仅仅是将一串无意义的字母数字ID，替换成有语义的、人类可读的名称（甚至是简单的0、1、2索引），就能显著降低AI在检索任务中的幻觉率。

更进一步，你可以提供一个 ​​response_format​​ 参数，让AI自己决定需要“简洁”还是“详细”的返回。一个详细返回可能消耗200个token，而一个简洁版可能只需要70个。这在长对话中能省出巨大的上下文预算。

如果返回内容过长，必须进行截断。但不要粗暴地切掉，而要友好地提示，并引导AI调整策略——比如，“结果超过100条，已截断。请尝试使用更精确的搜索条件。”

错误信息也是一样。返回一个冰冷的 ​​InvalidParameter​​​ 错误码，不如告诉它：“参数 ​​user_id​​ 不能为空，请输入有效的用户ID。”

每一次返回，都是一次与AI的对话，一次塑造其后续行为的机会。

四、像新人入职一样，写工具说明

工具描述和参数说明，是整个系统中杠杆效应最高的地方。它被加载到AI的上下文中，直接决定了AI如何理解和使用你的工具。

你应该像给一位新入职的同事讲解内部系统一样，来写这份文档。

把所有你认为理所当然的“常识”都明确写出来：

• 这个工具的核心目的是什么？
• 某个专有术语代表什么？
• 各个资源之间有什么隐藏的关联？
• 参数的格式要求是什么？

一个典型的优化案例：参数名 ​​user​​​ 就存在歧义，它到底是指用户名、用户ID还是邮箱？改成 ​​user_id​​，就能消除所有困惑。

Anthropic在冲击SWE-bench软件工程基准测试时，正是通过对工具描述进行了一系列精密的微调，才最终让Claude Sonnet 3.5取得了当时最好的成绩²，大幅降低了错误率。

五、为工具建立清晰的“势力范围”

当AI拥有的工具越来越多时，它会开始犯“选择困难症”。特别是当多个工具功能相似时。

使用命名空间是解决这个问题的有效手段。通过清晰的前缀或后缀，为工具划分好“势力范围”。

例如，​​asana_search​​​ 和 ​​jira_search​​​ 就比两个都叫 ​​search​​​ 的工具要清晰得多。更进一步，​​asana_projects_search​​​ 和 ​​asana_users_search​​ 则能让AI的定位更加精准。

这种命名方式，不仅帮助AI做选择，更重要的是，它将任务的“计算”从AI昂贵的上下文空间，转移到了更便宜的工具调用本身。AI不再需要思考“我要在Asana里搜什么”，而是直接思考“我需要搜索Asana里的项目”。

这细微的差别，正是从业余到专业的体现。

为AI智能体构建工具，是一门正在兴起的新学科。它要求我们放下过去确定性的编程范式，转而拥抱与非确定性智能体共舞的艺术。

这个过程的核心，不再是追求代码的逻辑完美，而是追求人机交互的“体感舒适”（Ergonomics）。

今天分享的这套流程和五条心法，是我们（Anthropic）从无数次失败和成功中提炼出的经验。它们不是终点，而是你踏上这条新道路的起点。

原文链接：​​https://www.anthropic.com/engineering/writing-tools-for-agents​​

本文转载自​​草台AI​​，作者：RangerEX