很多 Agent 团队的工具体系，前期看起来很高效：加一个工具就多一种能力。
但只要项目进入多人协作，就会迅速出现这些问题：
- 工具名字相似，但参数风格完全不同
- 老版本 schema 已经废弃，模型还在调用
- 某些工具默认有写权限，没人知道边界在哪
- 同一个业务动作被拆成多个“万能工具”，追责和回放都很难
这时候你需要的就不是“再补文档”，而是一套真正的工具注册表治理。
建议搭配阅读 Function Calling 工程实战、AI Agent 安全与权限控制、AI Agent 状态机设计指南 和 AI Agent 事故响应手册。
一、Tool Registry 应该管理什么
最小工具注册表至少要有这些字段：
| 字段 | 作用 |
|---|---|
tool_name | 唯一标识工具 |
description | 让模型知道适用边界 |
schema_version | 管理参数兼容性 |
permission_scope | 标记读写、敏感级别 |
owner | 明确谁负责维护 |
status | active / deprecated / disabled |
这张表不是给人看着舒服用的，而是给系统和团队建立共同边界。
二、典型失败案例：schema 改了，模型还在调旧版本
某个发票识别工具最初参数是：
{ "invoiceId": "..." }
后来业务升级，改成：
{ "invoice_id": "...", "country": "CN" }
如果你只是更新接口文档，而没有在注册表里标记版本和废弃策略，线上就会出现一种特别隐蔽的问题：
- 少量请求还在用旧 schema
- 模型能调通部分场景，但某些国家配置会直接失败
- 失败率不高，却很难排查
这类问题最难，因为它看起来像“偶发 bug”，本质却是工具治理缺位。
三、工具不该追求“万能”，而该追求边界清晰
一个最危险的反模式，就是万能工具：
- 一个工具能查、能写、能审批、还能发通知
短期看集成更快，长期看问题很大：
- 模型更难准确选择
- 权限边界无法最小化
- 出故障时难以定位哪部分逻辑有错
更稳的做法是按职责拆工具，并在 Tool Registry 里显式标记用途与边界。
四、版本与废弃策略怎么设计
推荐至少做三件事：
- 新版本工具上线时保留旧版本一段观察期
- deprecated 状态工具仍可回放旧 run，但默认不再分配给新请求
- disabled 状态工具禁止模型调用，只允许历史审计读取
这样你既能推进迭代，又不会把线上行为突然打断。
五、工具治理要配合权限策略
注册表里应明确区分：
- 读工具
- 写工具
- 高风险工具
- 内部维护工具
一旦 scope 不清，Tool Registry 就只是“接口目录”，而不是治理系统。
六、AI Agent 工具注册表上线清单
- 每个工具都有唯一 owner 和 schema 版本
- 工具状态能区分 active / deprecated / disabled
- 写工具与读工具在权限上显式分层
- 万能工具被拆成边界清晰的小工具
- 历史 run 能映射到当时的工具版本
