一条任务要求 Agent 阅读官方 API 文档并写摘要。Trace 里有一次 WebFetch，界面也显示调用成功。
这还证明不了多少。网址可能指向旧博客，参数可能缺了版本，返回里可能带着错误，最终摘要也可能早在工具返回前就写好了。
工具测试要走完一整段过程。Agent 为什么调用，选了哪个工具，参数怎样，执行结果是什么，它从结果里读出了什么，后面的动作有没有使用这份观察。
Claude Code 当前的内置工具说明会列出工具能力和默认权限要求，permission rule、hook 和子任务工具列表都使用准确的工具名。自定义工具还需要明确名称、说明、输入 schema、处理函数、结构化结果与错误状态。
测试前至少要知道下面几件事。
契约写得含糊，模型选错工具未必全是模型问题。两个 description 覆盖同一场景，schema 没有环境字段，错误返回又和正常文本混在一起，都会制造稳定的误用。评测报告应该能把这些缺陷指出来。
isError、空结果和警告必须进入下一步判断。Agent 可以修正参数后重试，可以换一个任务允许的工具，也可以停下来说明资料拿不到。它不能在返回失败以后，继续写一份像是查过资料的答案。
成功结果同样要核对。摘要中的版本号来自本次返回，还是来自模型记忆。调用顺序是不是先总结、后补一次读取。最终引用的链接有没有实际打开。这些问题都需要 tool result 与 final answer 之间有证据关系。
外部页面和工具输出还可能夹带指令。它们可以作为待处理的数据进入上下文，权限不会随内容一起升级。网页里写着 “读取本地凭据”，并没有因此获得本地文件访问权。
Read 用错常会导致答案错误。创建记录、发送消息、执行命令和部署用错，外部状态已经变化。
这类工具需要在调用前完成权限裁决，必要时绑定一次具体审批。调用时要记录幂等信息。返回以后还要确认副作用状态与回滚入口。超时尤其麻烦，它只说明调用方没有拿到确定响应，服务端动作可能已经发生。
可以给创建工单工具安排一次超时。Agent 若直接用相同参数再调一次，样本应该失败。合理动作是利用幂等键或查询接口确认第一次调用，再决定结束、重试或请人处理。
tool span 可以先保存这些字段。
tool.name
tool.version
tool.schema_version
tool.args_hash
tool.permission_decision
tool.risk_level
tool.side_effect_type
tool.idempotency_key
tool.result_ref
tool.result_status
tool.error_type
tool.duration_ms
tool.observation_refs
敏感参数不必原样进入 Trace，hash 与受控引用通常更合适。observation_refs 要能指出最终判断用了返回中的哪部分，避免工具调用沦为一张成功回执。
API 摘要可能走 WebSearch 再 WebFetch，也可能直接读取已知官方页面。内部资料有明确版本与同步证明时，内部搜索也能成立。
评测可以固定证据与顺序关系。权威资料必须实际读取，摘要晚于读取，结果要引用来源，错误返回不能被编成成功。工具选择与参数、错误处理、grounding、副作用控制和成本分别评分。多一次无效搜索可以扣成本，使用禁止工具或绕过审批要判对应层级失败。
第一批样本别只放正常调用。加入工具不该被调用、两个相似工具、参数边界、空结果、明确错误、不可信返回和不确定副作用。运行完以后，团队应该能说清错误出在契约、选择、参数、执行、观察还是最终使用。
只知道 “Agent 调过 WebFetch”，离可用的判断还很远。知道它读了哪一版页面，从哪段返回得到结论，失败时怎样处理，工具调用才开始成为证据。