工具接口合同

向模型说明可调用能力，并向执行器提供可校验参数与结果。

工具接口同时服务两个对象：模型需要理解何时调用，执行器需要验证能否执行。好的名字和说明可以减少选错工具，但真实约束必须存在于服务器。接口应明确输入类型、默认值、资源范围、读写性质、超时、错误及结果语义，避免一个万能execute工具承载所有企业能力。

例如证据检索返回source_version、定位、时效和可回查引用；计算工具返回公式、输入、单位、精度和结果；写工具返回operation_id、状态、receipt与后置条件。HTTP 200与业务成功不是同义词。身份、tenant和ACL由运行时注入，不应让模型填一个任意user_id就可以切换主体。

工具说明要帮助模型选择，又避免职责重叠。可将更新拆成prepare与commit，将SQL限制为获准模板或只读执行环境；复杂候选查询经parser、资源允许列表、行数和时间限制处理。JSON schema只能验证形状，不能证明查询安全或金额正确；业务验证仍在执行器。

工具版本是Agent发布的一部分，改变字段含义会影响旧会话与恢复。错误应结构化区分可修复参数、权限拒绝、配额和结果未知，使loop选择合法策略。契约测试覆盖边界值、非英文参数、空结果、重复调用、超时和流中断。最终要证明模型看到的定义与实际执行版本一致，而不是只证明某次函数调用返回了对象。

工具返回最好使用少量稳定状态，例如accepted、succeeded、failed、unknown，并附可检查字段。错误细节对执行器有价值，但敏感堆栈和凭证不能直接显示给业务用户。模型可见错误应足够帮助修复，又不泄漏内部环境；运维保留受限原始日志供授权人员诊断。

领域工具可以隐藏基础设施细节。例如让模型请求受限的指标计算，而非自行选择数据库凭证与任意SQL；这样更容易验证输入口径和输出含义。

实践重点：职责不重叠；明确读写、边界、schema、错误、receipt与postcondition。

验证抓手：对边界参数、无效值、重复调用和超时做契约测试。

常见误区：把任意shell/SQL开放作为所有业务工具的替代。

Agents SDK：Model接口和call ID约束；Anthropic：Advanced tool use。