Agent 工具设计最佳实践：面向 LLM 的接口契约、描述工程与工具集合收敛-开发者社区

Agent 工具设计最佳实践：面向 LLM 的接口契约、描述工程与工具集合收敛

【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering

本篇技术指南以 Agent-Skills-for-Context-Engineering 仓库中 tool-design 技能及其最佳实践参考为核心，系统讲解如何为 Agent 系统设计可靠的工具接口：从工具哲学、描述工程三原则、命名与枚举规范，到错误消息设计、响应格式优化、工具集合收敛与测试评估。读者学完后，将掌握一套可直接套用的工具设计检查清单、可落地的错误消息 JSON 结构与响应格式模式，并能结合仓库中的源码工具（schema 构建器、描述生成器、质量评估器）对现有工具集进行审计与迭代。

工具哲学：工具是 Agent 与世界的接口契约

工具是 Agent 与外部世界之间的主要接口。与传统面向开发者的 API 不同，工具的使用者不是"能读懂底层系统文档"的程序员，而是"从描述中推断意图、从自然语言请求生成调用"的语言模型。这一根本差异要求我们重新思考工具接口的设计与文档方式：

传统 API：调用方是人类开发者，会阅读文档、理解约定、构造合理请求；
Agent 工具：调用方是语言模型，必须仅凭一段描述块推断出完整契约，且在调用前无法提出澄清问题。

本仓库 tool-design 技能将这一思想概括为：把每个工具都设计成"确定性系统与非确定性 Agent"之间的契约。描述中任何歧义都会成为潜在故障模式，且这种歧义无法通过提示工程修复。

设计的最终目标是让 Agent 能够无需大量试错即可发现、理解并正确使用工具：工具定义中的每一处歧义都是潜在的失败点，每个含义不清的参数名都会迫使 Agent 猜测，每个缺失的示例都会让 Agent 在边界情况下失去指引。

在仓库的研究基础设施中，该机制被登记为 tool-contract-description：工具描述必须像"可执行契约"一样说明用途、激活条件、参数、返回结构与可操作的恢复错误，其失败模式包括工具选择错误、格式错误的调用与不可恢复的错误。

描述工程三原则

原则一：回答四个基本问题

每个工具描述都应清晰回答四个问题：

工具做什么：用具体术语精确说明工具达成的效果，避免 "helps with""can be used for" 这类含糊语言；
何时使用：给出具体触发条件与上下文，既包括直接触发信号，也包括表明工具适用性的间接信号；
接受什么输入：用类型、约束、默认值说明每个参数及其控制的内容；
返回什么：描述输出格式与结构，包括成功响应与错误条件的示例。

仓库中的 ToolDescriptionEvaluator 将上述要求转化为了可自动打分的质量判据——clarity（清晰度）、completeness（完整性）、accuracy（准确性）、actionability（可操作性）、consistency（一致性）五个维度各输出 0.0~1.0 的得分。其中_check_clarity会扫描描述中是否出现help、assist、thing、stuff、handle等模糊词，以及it、this、that等指代不清的词；_check_completeness则校验描述是否包含工具名、Parameters、Returns、Errors四个必需区块。这意味着"回答四个基本问题"在仓库中是可被机器验证的硬性标准。

原则二：保持一致结构

同一代码库内所有工具描述应保持结构一致。当 Agent 遇到新工具时，它能依据从其他工具学到的模式预测特定信息的位置，从而降低认知开销、避免格式不一致引发的错误。

推荐的结构包括：首句简要描述、带使用上下文的详细说明、带清晰类型信息的参数区、描述输出结构的返回区，以及列出可能失败模式并给出恢复指引的错误区。该结构在仓库中被固化为 TOOL_DESCRIPTION_TEMPLATE 模板——## {tool_name}、### When to Use、### Parameters、### Returns、### Errors五个区块，由 generate_tool_description 统一渲染，从工具规格对象直接生成可注入 Agent 上下文的 Markdown 描述。

原则三：包含具体示例

示例弥合了抽象描述与实际使用之间的鸿沟，应包含：

展示常见参数组合的典型调用示例；
边界情况及其处理方式的示例；
错误响应及相应恢复动作的示例。

好示例要具体而非泛泛。不要写 "Use an ID like '123'"，而要写 "Use format: 'CUST-######' (e.g., 'CUST-000001')"；不要写 "Provide a date"，而要写 "Format: 'YYYY-MM-DD' (e.g., '2024-01-15')"。

仓库中的 ToolSchemaBuilder 通过add_trigger与add_example方法把"何时使用"与"示例"结构化：触发词渲染为 "When ..." 列表，示例则以Input / Output键值对形式进入描述，最终由generate_usage_context组装成使用场景区。

命名规范

参数命名

参数名应做到"自解释"——无需额外说明即可表明用途：

好：customer_id、search_query、output_format、max_results、include_details；
差：x、val、param1、info。

偏好完整单词而非缩写，但id、url等广泛理解的缩写除外；同类概念在不同工具间应使用一致的命名。

枚举值

当参数接受枚举值时，所有工具应使用一致的命名。对于布尔风格选项：

肯定选项使用include_前缀模式：include_history、include_metadata；
否定选项使用exclude_前缀模式：exclude_archived、exclude_inactive。

对于类别型取值，使用一致的术语体系，例如统一采用"format": "concise" | "detailed"，避免有的工具用"short" | "long"、有的工具用"brief" | "complete"造成混乱。

一致性同样体现在整体 schema 层面：SKILL.md 要求工具名遵循动词-名词模式（get_customer、create_order），参数名跨工具保持统一（始终是customer_id，绝不一会儿id一会儿identifier），返回字段名保持一致——一致性降低 Agent 的认知负担，提升跨工具泛化能力。

错误消息设计

双重受众

错误消息服务两类需求不同的受众：

调试问题的开发者：需要堆栈追踪、内部状态等详细技术信息；
从失败中恢复的 Agent：需要可操作的指引，说明出了什么问题以及如何纠正。

设计时应以 Agent 恢复为主要考量：用清晰的语言说明具体哪里出错了，提供描述 Agent 下一步应做什么的解决指引，为输入错误提供修正后的格式，并给出有效输入的示例。

错误消息结构

仓库给出的推荐错误结构如下，包含错误码、类别、消息、期望格式、解决方案与是否可重试六个字段：

{ "error": { "code": "INVALID_CUSTOMER_ID", "category": "validation", "message": "Customer ID 'CUST-123' does not match required format", "expected_format": { "description": "Customer ID must be 9 characters", "pattern": "CUST-######", "example": "CUST-000001" }, "resolution": "Provide a customer ID matching pattern CUST-######", "retryable": true } }

这一结构在仓库源码中已模板化。ErrorMessageGenerator 内置了三种错误模板：NOT_FOUND（含 resolution 与 example）、INVALID_INPUT（明确报出具体字段Invalid {field}: {received_value}与期望格式）、RATE_LIMITED（给出retry_after秒数与等待重试指引），并支持传入上下文变量渲染出结构化 JSON 错误。仅返回 "failed" 的错误消息对 Agent 而言是零恢复信号。

常见错误模式

校验错误：指明收到了什么、期望什么格式、如何纠正；
限流错误：指明等待时间与重试指引；
未找到错误：建议替代方法或验证步骤；
系统错误：说明是否适合重试，并建议替代方案。

响应格式优化

Token 与准确率的权衡

冗长的响应信息全面但消耗大量上下文 Token；简洁的响应占用最少 Token 却可能缺少必要细节。最优方案是提供格式选项，让 Agent 按需请求合适的详细程度。

格式选项模式

def get_customer_response(format: str = "concise"): """ Retrieve customer information. Args: format: Response format - 'concise' for key fields only, 'detailed' for complete customer record """ if format == "concise": return { "id": customer.id, "name": customer.name, "status": customer.status } else: # detailed return { "id": customer.id, "name": customer.name, "email": customer.email, "phone": customer.phone, "address": customer.address, "status": customer.status, "created_at": customer.created_at, "history": customer.history, "preferences": customer.preferences }

何时使用每种格式

concise 格式：用于快速验证或简单查询、只需确认的场景，以及首次检索之后的后续工具调用；
detailed 格式：当基于客户数据做决策时、当输出将成为其他处理的输入时、当完整性上下文对正确性必不可少时。

仓库中的 SKILL.md 进一步补充：应在工具描述中明确文档化两种格式各自的使用时机，让 Agent 学会自行选择；同时指出，"轨迹层面的大规模响应格式选择与观察掩码"这类问题属于 context-optimization 技能的职责边界——工具设计关注的是单个工具层面的格式选项，而不是跨调用累积的 Token 权重问题。

工具集合设计

管理工具蔓延

随着 Agent 系统成长，工具集合趋于膨胀。更多工具带来更多能力，但也制造选择难题。研究表明工具描述重叠会导致模型混淆。核心洞见是：如果一个人类工程师都无法明确说出"这种情况下该用哪个工具"，那么 Agent 更不可能做得更好——这正是 SKILL.md 中"合并原则（consolidation principle）"的表述：把工具集缩减到每个工具只有一个无歧义用途为止，因为 Agent 通过比较描述来选择工具，任何重叠都会引入选择错误。

合并指南

合并工作流中的顺序步骤：把单一工作流中代表顺序步骤的工具合并为一个处理完整工作流的工具。例如不要分别实现list_users、list_events、create_event，而是实现一个在单次调用中查找可用时间并完成排期的schedule_event；
保留行为根本不同的工具：即使共享部分功能，在不同上下文中使用的工具也应保持分离，以防混淆；
保持工具间边界清晰：即使工具处于相似领域，也应通过精心设计将功能重叠降到最低。

工具选择指引

设计工具集合时，要考虑 Agent 做出正确选择需要哪些信息。若多个工具都可能适用于某场景，应在描述中澄清区别；使用命名空间创建逻辑分组，帮助 Agent 在工具空间中导航。仓库中给出的分组示例：数据库操作路由到db_*命名空间，网络交互路由到web_*；没有命名空间时，Agent 必须在扁平列表中逐个评估每个工具，随着数量增长选择准确率会下降。

对于 MCP（Model Context Protocol）多服务器环境，SKILL.md 有专门要求：始终使用全限定工具名ServerName:tool_name，否则多服务器注册同名工具（如两个服务器都暴露search）时 Agent 可能报 "tool not found" 或无法消歧：

# Correct: Fully qualified names "Use the BigQuery:bigquery_schema tool to retrieve table schemas." "Use the GitHub:create_issue tool to create issues." # Incorrect: Unqualified names "Use the bigquery_schema tool..." # May fail with multiple servers

从"合并"到"架构化约减"

将合并原则推到极致，就是移除大多数专用工具、改用少数原语级通用能力——仓库以 Architectural Reduction Case Study 记录了生产环境的证据（该案例的原始素材归档于 docs/vercel_tool.md，并被研究管线登记为 claim-tool-design-vercel-d0-reduction）：

一个生产环境 text-to-SQL Agent 原本使用 17 个专用工具（GetEntityJoins、LoadCatalog、SearchSchema、SyntaxValidator、ExecuteSQL、FormatResults等），假设模型会在复杂 schema 中迷失、做出错误 join 或臆造表名；
缩减后仅保留两个原语工具：ExecuteCommand（在沙箱中执行任意 bash 命令）与ExecuteSQL，Agent 用grep、cat、find、ls直接导航 YAML/Markdown/JSON 语义层文件；
对比结果为：平均执行时间从 274.8s 降至 77.4s（快 3.5 倍）、成功率从 80% 提升到 100%、平均 Token 用量减少约 37%、平均步数减少约 42%。旧架构最差案例为 724 秒、100 步、145,463 Token 且失败；新架构完成同一查询仅用 141 秒、19 步、67,483 Token 且成功。

该案例揭示的机理（architectural_reduction.md）：文件系统是经过 50 多年打磨的强抽象，标准 Unix 工具文档完善、行为可预测、模型理解深刻；专用工具当时在解决模型本可自行处理的问题——预过滤上下文、约束可评估的选项、包裹模型并不需要的校验逻辑，每个"护栏"都成了维护负担。但约减并非普遍适用：当底层数据杂乱无文档、领域需要模型不具备的专业知识、安全约束必须限制 Agent 动作、或流程确实受益于结构化编排时，不应约减。该参考文档还给出了"文件系统 Agent"的完整实现模式（沙箱创建、execute_command工具描述、ToolLoopAgent最小装配）以及五维评估框架（维护开销、失败分析、文档质量、约束必要性、模型能力）。

测试工具设计

评估标准

工具设计应围绕五个标准评估（SKILL.md 的表述为 unambiguity、completeness、recoverability、efficiency、consistency）：

清晰度（Clarity/Unambiguity）：Agent 能否确定何时使用该工具；
完整性（Completeness）：描述是否包含所有必要信息；
可恢复性（Recoverability）：Agent 能否从错误中恢复；
效率（Efficiency）：工具是否支持合适的响应格式；
一致性（Consistency）：工具是否遵循命名与 schema 约定。

Agent 测试模式

通过向 Agent 呈现代表性请求并评估其产生的工具调用来测试工具：

准备覆盖多样化 Agent 请求的测试用例；
让 Agent 为每个请求构造工具调用；
对照预期模式评估调用正确性；
识别常见失败模式；
依据发现优化工具定义。

仓库还提供了一种用 Agent 优化工具的闭环模式（SKILL.md）：把观察到的工具失败反馈给另一个 Agent 诊断并改进描述。optimize_tool_description模式的提示词要求分析失败原因、缺失信息与歧义，并输出改进后的描述——Agent 使用工具产生失败数据，Agent 再用这些数据改进描述，从而持续降低未来失败率。

反模式清单

反模式	坏示例	好做法
含糊描述	"Search the database for customer information."（什么库？有什么信息？查询格式？）	"Retrieve customer information by ID or email. Use when user asks about specific customer details, history, or status. Returns customer object with id, name, email, account_status, and optional order history."
隐晦参数名	`x`、`val`、`param1`	`customer_id`、`max_results`、`include_history`
缺失错误处理	通用错误或无错误处理	提供具体错误类型、消息与解决指引
命名不一致	同类概念一会儿`id`、一会儿`identifier`、一会儿`customer_id`	跨工具对相似概念保持统一命名

SKILL.md 的 Gotchas 还补充了几类高频陷阱：MCP 命名空间冲突、描述腐化（底层 API 演进后描述过期——应把描述当代码管理：版本化、API 变更时审查、对照当前行为测试）、过度合并（单个工具超过 8-10 个参数或服务根本不同的用例时应拆分）、参数爆炸（过多可选参数淹没 Agent 决策，应提供合理默认值、把相关选项分组为格式预设、把少用参数移入options对象）、以及缺失错误上下文（每个错误响应都应包含非法值、期望格式与具体示例）。

部署前检查清单

在部署新工具前逐项核验（对应 SKILL.md 的八项审计清单）：

Name：动词-名词命名；目录含多领域时加命名空间前缀；
Description：说明工具做什么、何时使用、返回什么；
Schema：每个参数都有类型、约束、默认值与示例值；
Return shape：成功与错误载荷均已文档化且机器可读；
Recovery：每个错误都告诉 Agent 重试前应修改什么；
Overlap：没有其他工具具有相同的激活场景；
Consolidation decision：相邻的窄工具已合并，除非确需独立调用；
Token impact：大响应支持 concise 模式或文件引用模式。

原文档的核验要点同样保留：描述是否清楚说明工具做什么与何时使用；参数是否有描述性名称与清晰的类型信息；返回值是否文档化结构并给出示例；错误情况是否覆盖可操作消息；工具是否遵循既有命名约定；示例是否演示常见用法；响应体量差异大时是否提供格式选项。

从原则到代码：仓库内的可执行落地

上述所有原则在仓库中并非停留在文档层面，而是有完整的可运行实现可供直接调用（skills/tool-design/scripts/description_generator.py）：

ToolSchemaBuilder：流式构建器，set_description设置简短与详细描述，add_parameter声明参数（类型、必填、默认值、枚举），set_returns定义返回 schema，add_error登记带恢复指引的错误条件，add_trigger/add_example补充激活场景与输入输出示例，build()返回满足ToolSpec协议的结构化规格；
generate_tool_description：将规格渲染为"工具名 / 何时使用 / 参数 / 返回 / 错误"五段式 Markdown 描述，可直接注入 Agent 上下文；
ToolDescriptionEvaluator：对描述在清晰度、完整性、准确性、可操作性、一致性五个维度自动打分——模糊词检测、必需区块校验、描述与规格的"腐化"检测（工具名或参数名缺失即扣分）、可操作信号扫描、命名风格一致性检查；
ErrorMessageGenerator：按NOT_FOUND、INVALID_INPUT、RATE_LIMITED模板生成结构化、可解析、可执行的可恢复错误消息。

推荐的典型工作流：用ToolSchemaBuilder定义工具规格 →generate_tool_description生成渲染描述 →ToolDescriptionEvaluator.evaluate打分审计 →ErrorMessageGenerator.generate产出错误模板。这使得"描述工程四问、一致性结构、具体示例、可恢复错误"等原则可以零成本地在每次迭代中被机器校验，而不是靠人工凭感觉审查。

总结

工具设计本质上是面向语言模型的接口工程：描述是注入 Agent 上下文、直接引导其推理的提示工程，错误消息是 Agent 自我纠错的恢复信号，而工具集合的整体形态（合并、命名空间、乃至原语化约减）决定了模型能否做出正确选择。仓库中的最佳实践参考、技能定义、生产案例与可执行工具共同构成了一个完整闭环——设计、生成、评估、测试、迭代——帮助你在"更多工具"与"更少工具"之间找到经得起验证的平衡点：从最简单架构出发，只在被证明必要时增加复杂度，并持续追问每个工具是在赋能模型还是在约束模型。

Agent 工具设计最佳实践：面向 LLM 的接口契约、描述工程与工具集合收敛