Tool Discovery 与动态注册

• 掌握 tools/list 的发现机制与 JSON-RPC 交互时序
• 理解工具数量过多时模型注意力/上下文稀释导致的准确率下降
• 掌握分层暴露、分组、语义检索等缓解策略

MCP Client 在 initialize 握手完成后，向 Server 发送 tools/list 请求，Server 返回一组 Tool 定义（name、description、inputSchema、annotations 等）。Client 拿到后把这些工具注入到模型上下文，供模型在推理时通过 tools/call 选择调用。当工具总数超过 50 个时，工具描述会占用大量上下文 token，同时模型在庞大工具列表上的注意力被稀释，容易"幻觉式"选错工具或忽略关键工具，选择准确率明显下降。缓解做法是分层暴露：把最常用的工具作为"常驻"列表，低频工具分组或按场景（domain）组织；更进一步是通过工具描述向量化做语义检索，只把与当前用户意图最相关的 Top-K 工具注入上下文；还可以用"工具分组"（一个粗粒度入口，内部再分发）来减少顶层选择数量。对工具功能做明确分类并让模型先选类别再选工具，也能显著降低选择面。

核心矛盾是"能力丰富"与"上下文有限、选择精度"之间的折中。工具列表不是越多越好，模型在多选场景下的准确率会随候选数上升而下降，因此工程上要主动控制每轮注入的工具数量，用语义检索与分层把"选择空间"压缩到模型可以稳定处理的规模。

• 理解 MCP 中工具名的全局唯一性约束与冲突场景
• 掌握 namespace 前缀、Server 标签、优先级等消解策略
• 理解在 Host/Client 层做隔离而非要求 Server 改名

MCP 规范要求工具名在单个 Server 内唯一，但跨 Server 时不同 Server 可能暴露同名工具（例如多个 Server 都有 search，语义却不同）。冲突必须由 Host 层解决，不能指望 Server 自行改名。常用做法是 namespace 前缀：在 Client 暴露给模型的工具名上加上 Server 标识，如 github_search、jira_search，把模型调用名与 Server 内部名解耦（Client 在转发 tools/call 前移除前缀）。也可以用 Server 标签（如连接时设定的 server 名称）在工具描述里标注来源，或定义优先级规则，当多个工具语义相近时决定优先暴露哪个。对于确实同名且语义冲突的，Host 应保留命名空间隔离，避免模型把 A 的工具当作 B 的调用。

命名空间隔离是 Host 层的职责，因为 Server 无法感知其他 Server 的存在。通过前缀/标签在 Client 层建立"全局唯一工具名"，既满足协议约束，又让模型面对的名字自带语义区分，从而降低误用风险。

• 掌握 notifications/tools/list_changed 通知机制
• 理解 Host 如何重新拉取并维护工具列表
• 理解在途调用（in-flight）的取消与结果处理策略

当 MCP Server 新增或移除工具时，它通过 notifications/tools/list_changed 通知 Host。Host 收到后重新调用 tools/list 刷新本地缓存，并更新注入给模型的工具集合。由于已是"进行中"的会话，Host 通常不会强行打断当前正在推理的模型，而是在当前回合结束后、下一轮请求时用新列表重新注入。对于正在执行的 tools/call（Server 已开始处理但尚未返回），Host 的处理策略包括：1) 若工具已注销，立刻通过 notifications/cancelled 取消该调用并释放资源；2) 若工具仍存在但签名已变，按新 Schema 校验或降级；3) 若调用已返回结果，则正常结算这段结果，但把"工具已注销/变更"作为上下文提示告知模型，避免模型继续引用。热插拔的关键是"列表刷新与在途调用解耦"，保证不因列表变化而崩溃或产生不一致。

list_changed 通知让"发现"是动态的，而不是一次性快照。但在途调用属于"已经达成的契约"，Host 要区分"未来工具集合"与"当前在途调用"两个时间维度，对在途调用做取消或结算处理，而不是让列表变化直接破坏正在进行的逻辑。

• 理解 description 作为模型选择依据的核心作用
• 掌握描述长度、清晰度与歧义对准确率的影响
• 掌握描述优化方法（精炼、示例、结构化、测试）

description 是模型在工具选择阶段最重要的信号之一——模型主要靠它判断"这个工具是否解决当前问题"。描述过长会占用上下文、稀释关键信息，且模型可能被非关键细节带偏；描述过短则信息不足，模型无法判断工具用途，容易误选或漏选；描述歧义（如多个工具描述相近、用词模糊）会让模型难以区分。优化方向：描述要"精炼且具体"，用一句话说明工具的用途和适用时机，接着列出关键参数语义与典型使用场景；对易混淆的工具给出"何时用它、何时不用它"的区分提示；必要时给出一个简短示例；描述要避免堆砌与模型决策无关的营销性文字。还应在 CI 中对各工具描述做脚本化检查（长度、关键词、与兄弟工具的重合度），并周期性用真实用户请求做工具选择评测，回归描述改动对准确率的影响。

工具描述本质是"给模型看的开发者文档"，其质量直接影响决策质量。好描述是"面向决策"的：用最少的 token 让模型能明确地选对工具、避开相似工具。因此描述优化要围绕"可区分性"与"信息密度"两个指标展开。

• 理解静态注册（编译期/配置期）与动态发现（运行时 tools/list）的区别
• 掌握动态发现对热插拔、版本演进与多 Server 场景的价值
• 理解二者各自的适用场景与取舍

静态注册指在代码或配置中预先声明工具集合（如直接调用 tool(name, fn) 注册），工具在应用启动时固定，无法运行时变更。动态发现（MCP 的 tools/list）指 Client 在运行时向 Server 查询能力列表，工具集合可以随 Server 状态变化（新增/删除/更新），并通过 list_changed 通知同步。动态发现的优势：支持热插拔、多 Server 并存、Server 自治演进（Server 新增工具无需 Client 重新编译）、以及按用户/权限动态过滤工具。静态注册的优势是简单、类型安全、无运行时协商开销，适合工具集合固定、单进程、无跨进程边界的场景。工程上二者常结合：本地确定性工具用静态注册，跨进程/远程的工具用 MCP 动态发现。

选型的本质是"能力集合的稳定性"与"运行时灵活性"的权衡。MCP 的价值恰恰在于把"工具是什么"从编译期解耦到运行期，让不同团队、不同语言、不同生命周期的服务能通过协议互操作，而不必共享代码与构建。

• 理解 Registry 的准入流程（提交、审核、签名、发布）
• 掌握版本管理与语义化版本、兼容性声明
• 掌握安全扫描（依赖、行为、静态分析）与信誉体系

一个可信的 MCP Registry 需要多层防线。准入审核方面：提交者需提供身份与用途说明，维护者人工/自动化审核工具描述、Schema 与代码来源，并通过签名机制（如私钥签名 manifest）保证工具清单未被篡改，发布即绑定可信签名。版本管理方面：采用语义化版本（SemVer），对 Schema 变更做兼容性声明（breaking vs non-breaking），并保留每个版本的 hash 与审计记录，支持回滚到已验证版本。安全扫描方面：对 Server 代码做依赖漏洞扫描（SCA）、静态分析（SAST）、行为沙箱运行（观察是否访问异常路径、网络出口、执行 shell），检查是否过度索取权限；对工具描述做 prompt-injection 检测，防止描述内嵌恶意指令。企业级 Registry 还应加信誉体系、评分与举报机制，把高风险或低活跃 Tool 标记或降权，甚至拦截其进入发现列表。

Registry 的价值在于"信任的集中化"——把逐工具的信任决策集中到一个可审核、可追溯、可签名的机制里。恶意 Tool 的威胁不只来自代码，还来自描述注入与过度权限，因此安全扫描必须覆盖代码、行为与描述三个维度。

• 理解 MCP Tool annotations 的语义
• 掌握如何基于 annotations 做风险分级
• 理解审批路由与 Human-in-the-Loop 的触发策略

MCP Tool 的 annotations 是 Server 对工具行为的声明性描述：readOnlyHint 表示该工具只读、无副作用；destructiveHint 表示该工具可能破坏数据或不可逆；openWorldHint 表示该工具会与外部世界交互（如发邮件、下单、访问外部 API）。Host 可用这些声明做风险分级：readOnly 归为低风险，通常无需审批；destructive 归为高风险，需用户确认或二次审批；openWorld 归为外部副作用，需按影响面（如金额、不可逆性）路由到审批。风险分级直接驱动审批路由策略——低风险自动放行，高风险弹窗确认，极高风险需管理员审批或白名单。这比"所有工具都确认"或"都不确认"更符合工程可用性与安全平衡。

annotations 是"声明式安全契约"，让 Host 不必猜测工具行为。尽管声明可被 Server 误导，Host 仍应把 annotations 作为分级依据，同时对高风险工具做行为兜底（如审计、告警、隔离），而不是完全信任声明。

• 理解向后兼容的 Schema 变更规则
• 掌握旧 Client 面对未知 Tool 的容错策略
• 理解运行时的能力协商与降级

版本兼容的核心是"向后兼容"：新增 Tool 是兼容的（旧 Client 忽略即可）；修改 Schema 时只能做"放宽"（新增可选参数、扩大枚举），不能删除参数或收紧约束，否则旧 Client 的调用会失败；删除 Tool 属于破坏性变更，应走版本/灰度并保留一段弃用期。旧 Client 遇到新 Tool 时不应崩溃，机制包括：Client 用 JSON Schema 校验工具名，调用前先确认目标工具在本地列表中存在；若工具已删除或未知，则返回"工具不存在"的明确错误而非抛异常；若 Schema 多出未知参数，Client 应忽略或按默认值处理而不是报错。严格来讲，Client 应在能力协商阶段声明支持的协议版本，Server 据此提供兼容的 Tool 集合，从而在源头避免旧 Client 遇到不兼容的新工具。

"不崩溃"依赖"宽松处理未知"的哲学：Client 对未知工具、未知参数、未知字段采取忽略与降级，而不是严格失败。配合 Schema 的向后兼容约束与版本协商，才能让新旧 Client 与 Server 长期共存。

• 理解权限与工具暴露的映射关系
• 掌握基于用户上下文动态过滤 tools/list 返回
• 理解"隐藏"与"拒绝"双层防护

动态过滤的正面做法是：在 Server 侧的 tools/list 处理中，根据请求携带的用户身份与权限（从认证上下文、OAuth scope 或租户上下文获取）返回过滤后的工具集合，低权限用户根本看不到高权限工具。这样既防止"看到"，也减少误选。但"隐藏"不能作为唯一防线，因为攻击者可能绕过发现直接调用 tools/call，因此 tools/call 也必须做同样的权限校验，实现"隐藏 + 拒绝"双层防护：列表按权限过滤，调用时按权限鉴权，二者一致。多租户场景下，还要把用户身份绑定到工具的数据访问范围（如只读工具、限定表），保证即使调用也被限制在授权域内。

更安全的设计是"默认拒绝 + 服务端强制鉴权"，而非只依赖客户端隐藏。工具列表过滤能改善体验与减少错误暴露，但真正的安全边界必须落在每次 tools/call 的服务端鉴权上。

• 理解输入 Schema 与语义描述的配合
• 掌握 JSON Schema 的约束表达与描述质量
• 理解 Schema 如何服务模型调用与 UI 渲染

工具描述由两部分构成：机器可读的 inputSchema（JSON Schema）与人类可读的语义描述（description）。Schema 表达参数的类型、必填性、枚举、默认值、约束与格式，是模型正确构造参数与 Host 校验参数的依据；语义描述则解释工具用途、参数含义与适用场景，是模型做选择决策的依据。生成两者要保证"语义描述与 Schema 一致"：描述里提到的每个参数在 Schema 中都有定义，Schema 的枚举与默认值要在描述中说明含义，避免描述与 Schema 矛盾导致模型构造错误参数。清晰度上，参数名要自解释，description 用一句话说明参数含义，复杂的参数要给出示例与取值约束。Schema 质量直接影响模型调用准确率——Schema 表达得越清楚，模型越不容易传错参数。

Schema 是"能力契约"，描述是"决策依据"，二者必须对齐。工程上应把 Schema 视为受版本控制的契约，在 CI 中校验其合法性与描述一致性，避免"能用但描述含糊"导致模型传错参。

• 理解工具冲突（同名/重叠能力）的消解
• 掌握优先级规则与场景化路由
• 理解无匹配时的兜底策略

工具路由设计有三层。冲突消解：同名工具通过 namespace 前缀或 Server 标签区分，能力重叠的工具用更精确的语义描述或优先级规则决定优先暴露哪个。优先级规则：按来源（企业内自研工具优先于第三方）、按场景（当前用户/租户/任务类型命中特定工具）、按权限（高权限用户才可见高优先级工具）等维度为工具打分，路由时选择得分最高者。兜底选择：当没有工具匹配或模型无法确定时，提供明确的兜底——要么返回"无可用工具"并让模型说明，要么调用一个通用 fallback 工具（如查询帮助），要么触发用户在交互中澄清。兜底的关键是不能让模型"瞎猜"并调用错误工具，而应进入显式的降级路径。

路由的本质是把"模型的选择"与"工程的控制"结合：模型负责表达意图，路由层负责把意图映射到正确的工具，并对模糊情况做兜底。清晰的优先级与兜底让路由可预测、可审计，避免模型行为不可控。

• 理解工具结果对上下文窗口的占用
• 掌握截断、摘要、分页三种策略
• 理解如何按需返回以控制预算

工具结果可能远大于所需信息，直接全文注入会撑爆上下文。三种策略各有取舍：截断（truncate）最简单，只保留前 N 字符，但会丢失尾部信息，适合结果有序且关键信息靠前的场景；摘要化（summarize）用 LLM 或规则把结果压缩成要点，保留信息密度但增加延迟与成本；分页返回（paginate）让模型按需取后续页，只返回第一页，模型需要时再请求下一页，最省上下文但增加往返。工程上要组合使用：设定结果 token 预算上限，超限先截断；对关键字段做摘要；对大型结果提供分页/懒加载。同时把"结果已截断/摘要"的提示一并注入，让模型知道信息可能不完整，从而触发按需获取。

上下文预算管理是"信息完整性"与"token 成本"的权衡。好的设计是"按需、渐进、可感知"：默认只给最小够用的信息，模型需要更多时再获取，且模型始终知道当前信息是否完整，避免基于不完整数据做错误结论。

• 理解语义搜索在工具选择中的作用
• 掌握描述向量化与 Top-K 检索
• 理解与全量暴露的对比

当工具数量很大时，全量暴露所有工具会给模型带来过重上下文与选择噪声。语义搜索的做法是：先把每个 Tool 的 description 与 Schema 向量化建索引，在每次请求时用用户意图/对话上下文做向量检索，召回与当前任务最相关的 Top-K 个工具，只把这 K 个注入模型上下文。这样一方面压缩了上下文，另一方面通过"先检索后选择"提高了模型选对工具的概率。语义搜索可作为"全量暴露前的一层筛选"，也可与全量暴露结合（高置信度直接选，低置信度回退全量）。工程上需维护工具描述索引的更新：工具变更时同步重建向量，并保证检索结果覆盖模型真正需要的工具（避免漏召回）。

语义搜索把"模型自己从几百个工具里选"变成"检索层先筛到几十个，模型再从中选"，把选择空间从"模型能力难以覆盖"降到"模型稳定覆盖"。漏召回风险仍存在，因此要配合召回评估与必要时回退全量。

• 理解工具注册的权限控制（RBAC/审批流）
• 掌握变更留痕与审计（谁、何时、改了什么）
• 理解企业环境下工具生命周期治理

工具注册应有明确的权限分层与审批流：普通开发者可提交工具注册申请，但需经过审核（Schema 检查、安全扫描、描述合规）后由管理员或维护者批准才生效；修改同一工具需作者或负责人权限；下架（注销）需走审批并可设弃用期，避免静默下线影响在用流程。所有变更都要留痕审计：记录操作者身份、时间、变更前后内容（diff）、审批人、审批时间与原因，形成不可篡改的审计日志。企业场景下，工具注册应纳入配置即代码（infrastructure as code）或版本化仓库，让工具清单可追溯、可回滚、可 diff review。变更留痕还要与工具版本的语义化版本绑定，便于回退到已知可用版本。

工具是"可执行的能力"，其注册权限决定了谁能把能力暴露给模型，因此必须像代码合并一样有权限、审批与审计。审计不仅为合规，也为排障——当模型因某工具变更而行为异常时，能定位到具体变更。

• 理解重试策略（幂等性、退避、次数）
• 掌握降级到备用工具或路径
• 理解把失败原因反馈给模型用于纠错

工具调用失败处理应分层：1) 重试层——对瞬时故障（网络、超时、5xx）做有限次重试，配合指数退避与抖动；前提是工具幂等（可重放），否则需幂等键防止重复副作用。2) 降级层——当主工具持续失败时，切换到备用工具或简化路径（如从完整查询降级为缓存查询、从写操作降级为只读提示）。3) 回灌层——重试与降级都失败后，把结构化的失败原因（错误类型、错误码、可恢复性）以"工具错误结果"形式回传给模型，让模型基于错误信息自行纠错（如修正参数、换工具、向用户说明），而不是模型盲目重试。三层要配合：重试解决瞬时故障，降级解决能力不可用，回灌解决"模型可以修正"的失败。失败原因应结构化，字段对模型可读，同时保留调试细节供日志。

失败处理的关键是把"自动化恢复"与"模型感知"解耦。前两层是工程自动化，第三层是把不可自动恢复的失败交给模型决策，避免模型在错误的参数上反复折腾。分层让系统既稳又灵活。

• 掌握 tools/list 的调用时序与缓存策略
• 理解 list_changed 通知与缓存失效
• 理解缓存 TTL 与刷新时机

MCP 的 listTools 时序是：initialize 握手完成后，Client 调用 tools/list 获取工具列表；此后可缓存列表避免重复请求。缓存刷新由两种机制触发：1) 主动通知——Server 在工具变更时发送 notifications/tools/list_changed，Client 收到后立即失效缓存并重新调用 tools/list；2) 被动刷新——Client 设置 TTL，到期后重新拉取，或用"带缓存标记的 list"（如 cache-control）判断是否需刷新。时序上，Client 应在每次"需要把工具注入模型"前确认缓存有效，工具列表变化时及时更新注入集合。缓存与刷新要处理竞态：若 list_changed 与正在进行的 list 请求并发，以最新一次返回为准，避免旧数据覆盖新数据。

listTools 是"发现"而非"每次调用都查"，因此缓存是合理优化。但缓存必须与变更通知联动，否则会用到过期工具列表。工程上把"缓存 + 通知失效 + TTL 兜底"三者结合，保证列表新鲜度与性能平衡。

• 理解只读与写入工具在副作用上的差异
• 掌握幂等键与重放的机制
• 理解幂等与重试策略的配合

只读工具（readOnly）无副作用，可安全重试；写入工具（create/update/delete）有副作用，重试可能造成重复操作。设计上：1) 在工具定义上明确区分只读/写入（annotations 的 readOnlyHint），Host 据此决定是否需要幂等保护与人工确认。2) 对写入工具引入幂等键（idempotency key）——Client 生成唯一键，Server 记录已处理过的键，重复请求返回相同结果而非重复执行。3) 重试策略要区分：只读工具可无脑重试；写入工具重试必须携带同一幂等键，且 Server 在键冲突时返回"已处理"而不是再次执行。4) 副作用还应记录审计日志，便于追踪重复/异常副作用。幂等与重试配合的关键是：重试不是"重放副作用"，而是"重放请求"，副作用由幂等键去重。

幂等是分布式系统处理"重试安全"的基石。对于工具调用，幂等键把"重试"与"副作用"解耦，让重试成为安全操作。区分只读/写入则决定了保护策略的强度——只读免保护，写入需幂等+确认+审计。