如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

定义工具

根据插件用例设计一组职责明确的 MCP 工具。

插件的 MCP 服务器通过工具向 ChatGPT 和 Codex 提供可执行的操作和可访问的数据。请在构思用例之后、实现服务器之前定义工具。

每个工具都应帮助用户达成目标。设计工具时,请先考虑用户会怎样提出请求、怎样使用这项功能,避免直接照搬内部 API。

将用例映射到工具

对于每个受支持的用例:

  1. 写明用户期望的结果。
  2. 列出获得该结果所需的信息。
  3. 确定服务器必须执行哪些读取、写入或外部操作。
  4. 将共同完成一个动作的操作归为一组。
  5. 如果各项操作在权限要求、安全风险或确认要求上有所不同,请将其拆开。

例如,项目插件可以提供以下工具:

  • list_projects 用于查找项目。
  • get_project 用于查看单个项目。
  • create_project 用于创建项目。
  • update_project 用于修改项目详情。
  • archive_project 用于归档项目,这会对项目状态产生重要影响。

将读取和写入操作分开,以便模型和用户区分哪些操作用于检索信息,哪些会改变状态。

定义每个工具的契约

对于每个拟提供的工具,请记录以下内容:

字段 需要定义的内容
名称 稳定且能体现操作的标识符。
标题 简短易懂的操作名称。
描述 工具帮助用户达成的目标,以及应调用该工具的条件。
输入模式 必填和可选参数,以及参数的类型、允许值和限制。
输出模式 模型可以查看和复用的结构化字段。
授权 服务器必须核验的账户、角色或资源访问权限。
副作用 工具可能更改的数据或外部状态。
失败时的行为 模型能够解释哪些错误,遇到哪些错误后能够恢复。

明确指定输入。对于标识符、账户范围或其他确保操作正确执行所必需的值,请勿依赖模型猜测。

返回稳定的标识符和足够的结构化信息,以支持后续调用。结果中不得包含密钥、访问令牌、内部诊断信息或不必要的个人数据。

编写描述,帮助模型选择工具

模型根据工具描述判断工具是否适合处理某个请求。描述应说明用户想做什么,无需介绍实现细节。

好的工具描述应做到以下几点:

  • 说明工具能做什么。
  • 解释何时应使用该工具。
  • 说明它与类似工具的区别。
  • 指出重要限制或前提条件。

避免仅仅重复工具名称,也不要使用用户不熟悉的内部服务术语。

规划安全注解

根据工具的实际行为设置注解。有关以下提示的规范定义、默认值以及它们之间的相互作用,请参阅 MCP 的 ToolAnnotations 模式。

  • readOnlyHint 仅在工具无法改变状态时才为 true。
  • destructiveHint 在工具可能造成不可逆或难以逆转的后果时为 true。
  • openWorldHint 在工具访问公共互联网或访问范围不固定的外部实体时为 true,其中也包括网页搜索等只读操作。访问范围明确的私有账户或工作空间不会仅因托管在外部就被视为开放环境。

注解不能替代服务器端授权、输入验证,也不能替代对可能产生重大影响的操作的确认。

检查覆盖范围和边界

将拟提供的工具与完整的用例清单逐一对照:

  1. 确认每个受支持的用例都能通过这些工具得到有用的结果。
  2. 找出未服务于清单中任何用例的工具。
  3. 检查用户在执行写入操作前是否还需要尚未提供的读取操作。
  4. 确认遇到不支持的请求时,系统能清楚说明限制,避免采用不安全的近似方案。
  5. 测试两个类似工具的描述是否存在重叠,以至于模型难以判断该选哪一个。

保留最终的工具方案,作为实现和评估时的检查清单。然后构建 MCP 服务器,使用有代表性的输入、无效输入和未经授权的输入测试每个工具的契约。