智能体工具设计

问题从哪来

智能体通过工具与外部世界交互，但传统面向开发者的 API 契约在这里往往失效：模型要从自然语言推断意图、填参数、生成调用。描述含糊、工具过多或职责重叠时，失败模式很难靠 prompt 补丁救回来——这是「工具-智能体接口」设计问题，不是模型「不够聪明」。

技能覆盖什么

本 skill 把工具视为确定性系统与非确定性智能体之间的契约，并给出可落地的设计框架：

• 描述即提示：工具说明需明确回答「做什么、何时用、接受什么输入、返回什么」，并配合示例与合理默认值。
• 合并（consolidation）：若人类工程师说不清该用哪个工具，智能体同样会选错；倾向用 schedule_event 这类综合型工具替代一串窄接口，减少选择与 token 开销。
• 架构精简（architectural reduction）：在文档与数据层可靠的前提下，用原语级能力（如统一文件系统访问 + grep/cat）替代大量专用封装，避免护栏式工具限制模型本可完成的推理。
• 可恢复错误与响应格式：错误信息要告诉调用方如何纠正；通过 concise/detailed 等格式选项控制上下文占用。

设计流程上可对照：识别工作流 → 归并为综合工具 → 统一命名 schema → 用真实智能体交互测试 → 按失败模式迭代；MCP 场景需使用 ServerName:tool_name 完全限定名。

边界与反模式

合并并非万能：行为根本不同、可能独立调用的工具应保持分离。架构精简在底层数据混乱、领域强依赖专有知识或安全必须硬隔离时会失效。还应警惕模糊描述、神秘参数名（如 x、param1）以及「为当前弱模型过度封装、阻碍未来模型」的维护陷阱；多数应用宜控制在约 10～20 个工具，超出则用命名空间分组。