Anthropic发布《为智能体编写工具》官方教程

工具到底是个啥？

在计算领域，确定性系统同样的输入每次都给同样的输出；非确定性系统正相反——智能体哪怕起始条件一样，也可能给出不同的响应。

我们传统地写软件，其实是在给确定性系统之间立契约。比如 getWeather("NYC") 这样一个函数调用，每次被调起，都一模一样地去取纽约市的天气。

工具是新型软件，它反映的是确定性系统与非确定性智能体之间的契约。用户问一句”我今天应该带伞吗？”，智能体可能会调天气工具，可能凭一般知识直接答，还可能先反问你在哪儿。智能体也会出幻觉，也可能摸不透工具该怎么用。

所以给智能体写软件，思路得从根本上转过来：工具和MCP服务器得面向智能体来设计，而不是像给别的开发者或系统写函数、写API那样随手写。

目标只有一个：借工具让智能体摸索出各种成功路径，把它能有效搞定任务的范围尽量撑大。

工具应该怎么写

这一节讲怎么跟智能体协作，把它用的工具写出来、改得好。流程是这样：先快速搭个工具原型，在本地测起来；再跑全面评估，给后续改动留个度量基准；然后和智能体一起干——反复评估、反复改进，直到智能体在现实任务里跑出扎实的表现。

构建原型

不上手永远猜不准：哪些工具对智能体来说顺手、哪些不顺手。所以先把原型快速搭起来。要是用Claude Code写工具（大概率一口气就能写完），最好把工具依赖的软件库、API或SDK（包括MCP SDK）的文档说明备好。官方文档站上一般有适合LLM的扁平化llms.txt文件（这是我们的API文档）。

把工具装进本地MCP服务器或桌面扩展里，就能在Claude Code或Claude桌面应用中连接、测试工具了。

要把本地MCP服务器连到Claude Code，跑这条命令： claude mcp add <名称> <命令> [参数…]。

要把本地MCP服务器或DXT连到Claude桌面应用，分别去 设置 > 开发者 或 设置 > 扩展。

工具还能直接塞进Anthropic API调用里，做程序化测试。

亲自把工具用一遍，短板自己心里就有数了。再收集用户反馈，把工具该支持哪些用例、哪些提示，摸出一个直观的判断。

跑评估

接下来得靠评估来量一量Claude用工具用得怎么样。基于真实使用场景生成大批评估任务，改进方向也可以拉着智能体一起分析着定。这套端到端的流程，在我们的工具评估指南里有完整说明。

1.生成评估任务

拿早期原型，Claude Code能快速翻一遍工具、一口气造出几十对提示和响应。提示要从实际使用场景里找灵感，挂在真实的数据源和服务上（比如内部知识库和微服务）。建议别用那种过于简单、浮于表面的”沙盒”环境——那种环境给不了足够的复杂度，压不出工具的上限。够硬的评估任务，往往要多次工具调用，甚至能到数十次。

下面先看几个强任务的例子：

• 与Jane安排下周会议讨论我们最新的Acme Corp项目。附上我们上次项目规划会议的记录、预订会议室。
• 客户ID 9182报告称他们在一次购买尝试中被收取了三次费用。查找所有相关日志条目并确定是否有其他客户受到同一问题影响。
• 客户Sarah Chen刚刚提交了取消请求。准备保留优惠。确定：(1)他们离开的原因，(2)哪种保留优惠最具吸引力，以及(3)在提供优惠前我们应该注意的任何风险因素。

再对比几个弱任务的例子：

• 与jane@acme.corp安排下周会议。
• 在支付日志中搜索purchase_complete和customer_id=9182。
• 查找客户ID 45892的取消请求。

每个评估提示都得配一个可验证的响应或结果。验证器可以很简单——拿标准答案和抽样响应做精确字符串比较；也可以复杂点——请Claude来判分。别把验证器写得太严：格式、标点、换成另一种说法但同样正确的响应，不该被这些虚假差异一票否决。

对每个提示-响应对，再指定一份期望智能体解题时调用的工具清单，用它来衡量智能体在评估中是否真正搞懂了每个工具的用途。注意解题的有效路径往往不止一条，尽量别把策略指定得太死、拟合得太狠。

2.运行评估

评估建议用直接的LLM API调用以编程方式跑。套一个朴素的智能体循环就行（把交替出现的LLM API调用和工具调用包在一个while循环里）：一个评估任务一个循环，每个评估智能体领一个任务提示和一组工具。

评估智能体的系统提示里，建议要求智能体输出结构化响应块（方便验证），同时输出推理和反馈块。让这些内容排在工具调用和响应块之前输出——这会触发思维链（CoT）行为，把LLM的有效智能拉高一档。

如果用Claude跑评估，把交错思考打开，就有类似的”开箱即用”效果。它能帮你探究智能体为什么调或不调某些工具，工具描述和规范里哪些地方要改进，也会被它高亮出来。

除了看顶层准确率，建议再多收几个指标：单次工具调用和整个任务的运行时长、工具调用总数、总令牌消耗、工具错误数。跟踪工具调用能暴露智能体常走的工作流，哪里该把工具合并，机会点就在这。

3.分析结果

智能体本身就是个不错的反馈搭子：从互相矛盾的工具描述，到低效的工具实现、看得人迷惑的工具模式，它都能给你指出来。而且它在反馈和响应里省略了什么，往往比写了什么更值得琢磨——LLM不一定总把真实意思说明白。

盯着智能体在哪儿卡住、在哪儿犯迷糊。把评估智能体的推理和反馈（也就是思维链）通读一遍，短板自然浮现。原始记录（工具调用和工具响应都算）也要翻，思维链里没写明的行为全靠它兜住。读的时候要会读弦外之音——别忘了，评估智能体手里并没有正确答案和策略。

工具调用指标也值得细看。大量冗余调用，多半在提示你分页或令牌限制参数该调了；大量因为无效参数报的错，多半说明工具描述要写得更清楚、示例要补得更好。我们推出Claude的网络搜索工具时就有过这么一档子事：Claude老是往工具查询参数后面画蛇添足地加上2025，搜索结果被带偏、性能往下掉。后来把工具描述改了改，Claude才走上正轨。

4.与智能体协作

你甚至能让智能体自己分析结果、自己改工具：把评估智能体的记录串起来，直接粘进Claude Code。Claude是分析记录、一次重构一大批工具的行家——比如做新改动时，让工具实现和描述保持一致，它顺手就办了。

说白了，本文大部分建议，都是我们拿Claude Code反复打磨内部工具时攒出来的。我们的评估建在内部工作空间上，项目、文档、消息都是真实的，内部工作流有多复杂，评估就有多复杂。

为了不过度拟合”训练”评估，我们靠保留的测试集把门。测试集证明：哪怕工具已经好过”专家”级实现的性能，改进还是能再往外掏——不管这工具是研究员手写的，还是Claude自己生成的。

下一节，我们把这一路学到的经验摊开讲讲。

编写高效工具的原则

这一节把学到的东西熬成几条写高效工具的指导原则。

替智能体挑对工具

工具越多不等于结果越好。我们见的最多的一种错误，是把现有软件功能或API端点随手包成工具就完事，根本不管这工具合不适合智能体。根子在于：智能体和传统软件的”功能可见性”不是一回事——它们感知和使用工具的方式，跟传统软件截然不同。

LLM智能体的”上下文”有限（一次能处理的信息量就那么多），计算机的内存反倒又便宜又管够。拿在地址簿里找联系人这件事举例：传统软件程序能把联系人列表一个个存下、挨个处理，每看一个再往下走一个。

LLM智能体要是用一个返回所有联系人的工具，就得逐令牌把每个联系人读一遍——有限的上下文空间全耗在无关信息上（就像在地址簿里从上到下把每一页都读一遍来找人——纯暴力搜索）。更聪明也更自然的做法（智能体和人通用）是先翻到相关的那一页（比如按字母顺序直接定位）。

我们建议先构建少量经过深思熟虑的工具，对准高价值工作流，工具得和评估任务咬合，之后再往上扩。还是地址簿这个例子：与其给一个朴素的list_contacts，不如实现search_contacts或message_contact这类工具。

工具还可以有整合能力，在底层把多个离散操作（或API调用）揽下来。比如用相关元数据把工具响应做丰富，或者把经常连着走的多步任务塞进单次工具调用里。

举几个例子：

• 与其做 list_users、list_events、create_event 三个工具，不如上一个 schedule_event：找空闲、订日程，一站办完。
• 与其做 read_logs，不如做 search_logs，只返回相关的日志行外加一点上下文。
• 与其做 get_customer_by_id、list_transactions、list_notes 三个工具，不如做一个 get_customer_context，把客户近期所有相关信息一次编译好。

保证每个造出来的工具都有明确且独特的用途。工具应该让智能体能像人类拿到同样的底层资源时那样，把任务拆解、逐步解决，同时把本来会被中间输出吃掉的上下文省下来。

工具太多、功能互相打架，也会把智能体从高效策略上带跑偏。在”造哪些工具、不造哪些工具”上精打细算，回报是实打实的。

给工具划好命名空间

AI智能体可能一口气接入几十个MCP服务器、几百种工具——里面还有别的开发者提供的。功能重叠、用途暧昧的工具摆在一起，智能体真会犯选择困难。

命名空间（把相关工具挂到共同前缀下）能在一大堆工具之间划清界限；MCP客户端有时默认就这么干。按服务分（asana_search、jira_search），再按资源分（asana_projects_search、asana_users_search），智能体挑工具时就能挑对。

我们发现，前缀式还是后缀式的命名空间选择，在工具使用评估里影响不小。效果因LLM而异，建议拿自己的评估来定命名方案。

智能体可能调错工具、参数给错、调用不够、把工具响应处理砸——这些都会发生。挑那些名字就反映任务自然划分的工具来做，能同时把塞进智能体上下文的工具和工具描述数量压下来，把计算从上下文里搬回工具调用本身。智能体整体犯错的概率也就跟着降了。

让工具返回有意义的上下文

同样的道理，工具实现要留意：只往智能体面前递高价值信息。上下文相关性优先于灵活性，uuid、256px_image_url、mime_type这类低级技术标识符能避就避。name、image_url、file_type这样的字段，才更可能直接指导智能体接下来的行动和响应。

处理自然语言名称、术语或标识符，智能体的成功率明显高于处理晦涩标识符。我们就试出来：光是把一串随机的字母数字UUID换成更有语义、更好解释的说法（哪怕是0索引的ID方案），Claude在检索任务上的精确度就靠少出幻觉往上蹿了一截。

有些场合，智能体确实需要自然语言和技术标识符两头都能拿，哪怕只是为了触发下游工具调用（例如 search_user(name=’jane’) → send_message(id=12345)）。办法是工具里暴露一个简单的response_format枚举参数，让智能体自己挑要”简洁”还是”详细”的响应（下图）。

格式还可以继续加，灵活性更大，风格类似GraphQL，想要哪块信息片段就选哪块。下面是一个控制工具响应详细程度的ResponseFormat枚举示例：

enum ResponseFormat {
   DETAILED = "detailed",
   CONCISE = "concise"
}

详细工具响应长这样（206 个 token）：