夜雨聆风基于 Anthropic 官方文章《Writing Tools for Agents》的解读与实战笔记
Part 1：先搞懂一个核心认知
工具是一种“新物种”
weather = getWeather("NYC")程序员写死了调用时机、调用次数、参数内容，一切都是可控的。
AI 自己决定要不要调用AI 自己决定传什么参数AI 自己决定调用几次
这就是“工具是一种新型软件”的真正含义。
三个核心挑战
挑战 | 具体含义 |
|---|---|
描述要写得让 AI 看得懂 | AI 靠描述决定“什么时候用、怎么用”，描述模糊 → AI 用错 |
返回结果要让 AI 用得好 | 信息量、格式、长度都要考虑，否则 AI 要么被淹没，要么用不上 |
错误信息要让 AI 能恢复 | 不是给程序员看的 stack trace，而是告诉 AI “下一步该做什么” |
Part 2：五个典型场景，看懂工具设计的坑
场景 1：工具描述写得太随意
名称：search描述：搜索参数：q（字符串）
名称：search_customer_orders描述：根据客户邮箱搜索其历史订单。返回订单 ID、下单时间、金额、状态。仅返回最近 90 天内的订单。参数：- customer_email（字符串，必填，客户的邮箱地址）- status（可选，过滤订单状态: 'pending' / 'shipped' / 'delivered' / 'cancelled'）
记住：工具参数要做到“AI 看完不用猜”。
场景 2：返回结果设计不当
“省 context”不是唯一目标，“让 AI 高效完成任务”才是。
好工具返回的内容，要让 AI “看完就能决策”——既不淹没它，也不让它再绕一圈。
场景 3：错误信息要写给程序员
Error: ValidationError at line 47 in transfer.py:account_lookup() returned None. Stack trace: ...
Error: Account 'ACC_99999' not found.Please verify the account number.You can use list_accounts() to see all available accounts.
工具的错误信息不是“事故报告”，是“恢复指南”。
口诀：人话 + 具体 + 出路。
场景 4：综合设计不够专业
工具名：get_order_status参数：订单 id 或订单 id 列表返回：订单状态（如 New, Cancel, Success）
支持批量的工具，参数永远是 list；单个调用就传只有一个元素的列表。
{"results": [{"order_id": "ORD_001","found": true,"status": "cancelled","status_updated_at": "2026-05-10","amount": 299.00,"cancel_reason": "客户主动取消"},{"order_id": "ORD_999","found": false,"error": "Order ID not found. Please verify the order number."}]}
每条都带 order_id，AI 能对应回复用户的输入 found 字段区分订单是否可以查到 失败的也返回，AI 知道哪个 order_id 错了 状态码附带辅助信息（时间、金额、原因）
默认只返回最近 10 单 limit 最大不超过 50 支持分页查更多 支持按状态过滤
分页、排序、过滤这些事，工具自己要做，别直接推给 AI。
场景 5：选择了错误的工具
LLM Agent 的上下文是有限且昂贵的，而计算机内存是廉价且充足的。
搜索工具返回结果时，附带相关元数据 处理经常链式调用的多步任务 一次工具调用完成人类通常需要多步的操作
每个工具都应该有清晰、独特的目的 让 Agent 能像人类一样细分和解决任务 减少中间输出消耗的上下文
更多工具 ≠ 更好的结果。太多工具或重叠的工具会分散 Agent 的注意力。
Part 3:上述的总结
传统软件是程序员对程序员的契约；工具是程序员对 AI 的契约。 好的工具描述要回答三个问题：能做什么、返回什么、不能做什么。 工具参数要做到 AI 看完不用猜——名字、类型、含义、可选值、必填性要全明示。 好工具返回的内容，要让 AI 看完就能决策——既不淹没它，也不让它再绕一圈。 分页、排序、过滤这些事，工具自己要做，别推给 AI。 工具错误信息不是事故报告，是恢复指南——人话 + 具体 + 出路。 支持批量的工具，参数永远是 list；单个调用就传只有一个元素的列表。
展望未来
有效的工具是有意图且清晰定义的，明智地使用 Agent 上下文，可以在多样化的工作流中组合使用，并使 Agent 能够直观地解决真实世界的任务。
