Tool 发现与选择

选择不变量未授权、环境不匹配或不可用的 Tool 必须在模型看到前被确定性排除；模型不应承担访问控制。

Tool 越多，描述竞争越严重

近义描述会争夺同一意图，长 Schema 消耗 Context，废弃或故障能力让选择结果失真，未授权定义还会暴露攻击面。固定“最多 N 个 Tool”不是普遍规律；真正要控制的是候选区分度、定义 Token、误选代价和动态可用性。

先定位失败层：正确能力未进入候选是召回问题；已经进入却没选是决策问题；选对但参数错是契约问题；执行被拒是权限/状态问题。把所有失败归因于模型，会导致无效调 Prompt。

Registry 不只存 name/description/schema，还需要能力域、动作、资源、版本、Owner、租户/角色/环境/地域可见性、副作用、风险、成本、延迟、健康和废弃状态。描述用于语义匹配，结构字段用于硬过滤和治理；两者不能互相替代。

能力快照一次 Run 应记录候选集版本和最终注入定义的摘要。Registry 后续变化时，仍能解释当时模型为何看见或没看见某个 Tool。

先做不可争辩的过滤，再做有误差的排序

Hard filter权限、租户、环境、状态

Retrieve词法 + 语义召回

Rerank条件、风险、成本、多样性

Present只注入当前步骤所需定义

根据认证后的主体、租户、数据域、部署环境、政策和健康状态过滤。不要把“你无权使用 X”写进 Prompt 后仍把 X 暴露给模型。

查询由用户目标、当前计划步骤、资源类型和领域上下文组成。词法检索擅长精确名词，Embedding 处理表达差异；两者融合比单一向量相似度更稳。召回目标是保住正确能力，而非立即做最终选择。

重排加入适用/禁用条件、副作用、延迟、成本和历史可靠性，避免近义 Tool 占满 Top-K。高风险动作可施加确定性优先级或只在计划明确进入执行阶段时出现。

最终定义按需延迟加载。OpenAI Agents SDK 当前支持 Tool Search 和 deferred loading，说明“发现候选”和“展开完整 Schema”可以分离；采用具体 SDK 前仍需按版本验证行为。

若缺少决定性字段，优先澄清；若需要识别资源，先调用只读发现 Tool；涉及资金、删除或发布时使用确定性路由和审批。候选分数接近不是自动澄清的唯一条件，还要结合误选代价和可逆性。

每次决策记录查询特征、候选及分数、过滤原因、最终选择和“不调用”。日志只留必要特征与引用，避免复制敏感正文。

远端发现结果必须绑定可信来源、签名或受控连接；Schema 不是可信代码。缓存键包含租户、身份、环境和 Registry 版本，使用 TTL 或变更通知失效。正在运行的 Run 固定能力快照，或只允许兼容更新，防止恢复后同名 Tool 语义漂移。

健康失败应由系统摘除或降权，并给出可解释降级，不能让模型通过真实副作用“试一下是否可用”。跨协议发现还要限制命名冲突、来源优先级和供应链风险。

数据集必须包含近义干扰、无合适 Tool、无权限、Tool 下线和多步骤只需当前能力的样本。线上以 Shadow 候选比较新旧管道，再逐步放量；只看最终任务成功会掩盖召回下降被人工兜底的事实。

正确 Tool 没有被调用，第一步查什么？

先确认它是否经过权限/状态过滤并进入候选，再区分召回、重排、模型选择与参数生成；不要直接改描述。

为什么把禁用 Tool 留在列表并提示模型别用不是安全控制？

提示词是不可信决策，注入和模型错误都可能绕过；访问控制应在候选前过滤和执行前授权。

以下以官方文档、标准、论文和原始工程资料为主。厂商 API、价格、限额与模型能力会变化，落地时仍需按目标版本做能力探测和回归。