用途：为 Apify MCP 服务器的单个工具族（tasks、storage、runs 等）建立小型、经过校准的 Langfuse 评测套件，并利用失败结果修复工具。核心原则是评测从用户意图出发设计，绝不从工具描述推导；评测先定义“应该能做什么”，随后再修复描述让朴素智能体通过。
流程：先清点工具，每个工具和每个参数分组至少有一个用例（覆盖矩阵最终证明这点）。写任何依赖 API 行为的用例前，先用一次性的 tsx 脚本对真实 API 探测（必填字段、唯一性规则、限制、错误消息），不要基于假定的契约编写用例。使用两个数据集对应两个 CI 闸门：mcp-server-evals-pr（--dataset 默认）存放 kind: "tool-call" 条目并拦截 PR，mcp-server-evals-merge 存放 kind: "agent" 条目并在 master 推送时运行。每条条目声明 metadata.kind：tool-call 为单轮、只断言首次工具调用、无评判、不执行；agent 为多轮、跑到完成并由 LLM 评判打分。tool-call 用例设置 expectedTools（必需），可用 expectedArgs（扁平对象，所列键需深度等于捕获调用同名键）固定参数，需隔离 MCP 与内置工具选择时加 mcpToolsOnly: true。故意触发错误的 agent 用例设置 metadata.expectedErrors 为允许失败的工具名，零工具错误闸门仅豁免这些。条目 id 使用数据集前缀格式：pr/<tool>/<slug> 与 merge/<family>/<slug>。
写法：分波编写，2–3 个简单（单工具、显式输入）→1–2 个中等（跨工具链、运行选项）→2–3 个困难（模糊用户语言、错误恢复、冲突），每波运行并审查后再写下一波。先在最强模型（Opus）上校准，其失败属于用例缺陷或产品缺口；再逐级下探 Sonnet、Haiku，Opus 通过而 Haiku 失败即说明工具描述或输出不足以支撑朴素智能体。修复优先改工具输出（响应摘要/nextStep 中的引导句），其次改描述。
诊断顺序：用例本身（查询不可获得上下文、输入违反 schema、强模型的“错误”其实可辩护）；评判/参考（代理做对了但参考要求不可观测内容，评判只看工具调用、参数和最终文本）；产品（按设计无法满足自然请求）；描述/输出；外部世界（目标页面宕机或为空）；模型（策略性拒答或顽固习惯）。始终先读完整记录再归因，评判的一句话只是提示。
防返工规则：参考是可评判的契约（“仅当调用 <tool> 且最终答案陈述 <fact> 时 PASS”）；查询用用户语言，困难用例不得点名工具；遥测不得造假，预期错误写入 expectedErrors；写评判盲区条款；判定虚假声明而非静默成功；tool-call 用例的 expectedTools 是列表，接受任何可辩护答案；既探测机制也探测目标；状态是账户级的，使用 eval- 前缀固定资源名加 fixture 种子/清理脚本；数据集条目 id 项目内永久唯一，不可迁移或复用。
明显红旗：看着工具描述写用例（在测鹦鹉学舌）；故意报错的 agent 用例缺 expectedErrors；未诊断就靠重跑“修好”失败；因单次失败就改工具；查询中出现明显假 URL；要求逐字复制数百词以上；副作用偏离被测轴。常见错误包括缺 expectedErrors、在廉价模型上校准、链式用例 maxTurns 过低、固定名未清理、跳过分波审查。命令、条目结构、探测模式与 sweep 查询见 reference.md。