tool-design

Tool Design - AI 智能体工具设计指南

技能概述

Tool Design 是一套专为 AI 智能体开发者的工具设计方法学，帮助您构建智能体可高效使用的工具 API，涵盖从整合原则到架构简化的完整设计模式。

适用场景

1. 创建智能体工具系统

当您需要为 Claude、GPT 等 AI 智能体设计可调用工具时，本技能提供完整的设计框架。与传统面向开发者的 API 不同，智能体工具需要考虑语言模型如何理解意图、推断参数值并生成调用。通过本技能的设计原则，您可以避免常见的工具设计陷阱，确保智能体能够正确理解和使用您的工具。

2. 优化现有工具集

如果您发现智能体频繁调用错误的工具、无法正确理解工具描述，或者工具调用成功率低，本技能可以帮助您诊断问题并提供优化方案。包括工具描述重写、参数命名优化、错误信息改进等具体方法，实测可将任务完成时间减少 40%。

3. MCP 工具集成开发

使用 Model Context Protocol (MCP) 开发工具时，必须遵循特定的命名规范（如 ServerName:tool_name 格式）。本技能详细说明 MCP 工具的命名要求、描述编写标准，以及如何避免多服务器环境下的工具定位问题。

核心功能

1. 整合原则与架构简化

整合原则指出：如果人类工程师都无法确定在某种情况下应该使用哪个工具，那么智能体也不太可能做得更好。本技能教会您如何将多个狭窄工具整合为单一综合工具，减少智能体的选择负担。

架构简化将这一原则推向极致：用原始通用能力替代大多数专用工具。例如，不构建数据探索、模式查找、查询验证等多个专用工具，而是提供单一命令执行工具，让智能体使用标准 Unix 工具（grep、cat、find、ls）自由探索。生产证据显示，这种极简架构可以胜过复杂的多工具设计。

2. 工具描述工程

工具描述本质上是一种提示工程，直接影响智能体的行为。本技能提供描述结构模板，确保回答四个关键问题：

同时涵盖响应格式优化（简洁/详细模式）、错误消息设计（让智能体能够恢复）、默认参数选择等实用技巧。

3. 工具集合组织与测试

当工具数量增长时，组织方式变得至关重要。本技能指导您：

还提供了智能体驱动的工具优化方法：让智能体尝试使用工具，收集失败模式，然后分析并改进描述。这种反馈循环可以持续提升工具可用性。

常见问题

智能体工具和传统 API 有什么区别？

传统 API 面向人类开发者，开发者阅读文档后理解契约并正确调用。智能体工具面向语言模型，模型必须从描述中推断契约并生成匹配格式的调用。这个根本差异意味着工具设计需要重新思考：契约必须无歧义、描述必须包含使用上下文、错误信息必须引导修正。每个工具定义中的歧义都可能成为智能体的失败模式。

如何编写有效的工具描述？

有效的工具描述应该回答四个问题：工具做什么、何时使用、接受什么输入、返回什么。避免使用"帮助"、"可用于"等模糊语言，要精确说明工具的功能。包含具体的使用触发条件（如"用户询问定价时"）和参数约束（如格式"xxxx-xxxx"）。更重要的是，描述是提示工程的一部分，会直接影响智能体的行为选择。

什么是工具整合原则，什么时候应该使用？

整合原则指出：当多个工具功能重叠或必须配合使用时，应该将它们整合为一个综合工具。例如，不要分别实现 list_users、list_events、create_event，而是实现一个 schedule_event 工具，它内部处理查找可用性和安排事件的整个流程。整合可以减少 token 消耗、消除歧义、降低选择复杂度。但整合并非万能：行为根本不同的工具应该分开，在不同上下文中使用的工具也应该分开。

MCP 工具命名有什么要求？

使用 MCP（Model Context Protocol）工具时，必须始终使用完全限定名称 ServerName:tool_name 来避免"工具未找到"错误。例如："Use the BigQuery:bigquery_schema tool" 是正确的，而 "Use the bigquery_schema tool" 在多服务器环境下可能失败。在所有工具引用中建立包含服务器上下文的命名约定。

架构简化模式适用于什么场景？

架构简化（移除大多数专用工具，改用原始通用能力）在以下情况下效果最佳：数据层文档完善且结构一致、模型具备足够的推理能力、专用工具实际上在约束而非赋能模型、您在维护脚手架上花费的时间比改进结果还多。它在以下情况下会失败：底层数据混乱或不一致、领域需要模型缺乏的专业知识、安全约束需要限制智能体操作、操作确实复杂且受益于结构化工作流。

如何测试智能体工具设计是否有效？

通过向智能体呈现代表性的请求并评估生成的工具调用来测试。评估标准包括：无歧义性（智能体是否选择正确的工具）、完整性（描述是否包含所有必要信息）、可恢复性（错误消息是否指导修正）、效率性（响应格式是否优化 token 使用）、一致性（命名和结构是否统一）。还可以使用智能体自身来优化工具：让它尝试使用工具，收集失败案例，然后分析问题并改进描述。