工具是插件的 MCP 服务器向 ChatGPT 和 Codex 提供的操作和数据。请在 构思使用场景之后、实现 服务器之前定义工具。
每个工具都应帮助用户达成目标。不要在未考虑用户会如何请求和使用这些功能的情况下，直接照搬内部 API。
将使用场景映射到工具
对于每个受支持的使用场景：
- 写明用户期望的结果。
- 列出产生该结果所需的信息。
- 确定服务器必须执行的读取、写入或外部操作。
- 将共同构成一项完整动作的操作归为一组。
- 如果操作的权限、安全风险或确认要求不同，请将其拆分。
例如，项目插件可以提供以下工具：
list_projects用于查找项目。get_project用于查看单个项目。create_project用于创建项目。update_project用于更改项目详情。archive_project用于执行具有重大影响的状态变更。
将读取和写入行为分开，让模型和用户能够区分信息检索与更改状态的操作。
定义每个工具的契约
为每个拟议工具记录以下内容：
| 字段 | 需要定义的内容 |
|---|---|
| 名称 | 稳定且能体现操作的标识符。 |
| 标题 | 简洁易懂的操作名称。 |
| 描述 | 应触发该工具的用户目标和条件。 |
| 输入模式 | 必需参数和可选参数、类型、允许的值及限制。 |
| 输出模式 | 模型可以查看和复用的结构化字段。 |
| 授权 | 服务器必须验证的账户、角色或资源访问权限。 |
| 副作用 | 工具可以更改的数据或外部状态。 |
| 失败时的行为 | 模型可以解释或从中恢复的错误。 |
使用明确的输入。不要依赖模型猜测标识符、账户范围或其他确保正确性所必需的值。
返回稳定的标识符和足够的结构化信息，以供后续调用使用。结果中不得包含机密信息、访问令牌、内部诊断信息或不必要的个人数据。
编写有助于选择工具的描述
模型通过工具描述判断工具是否适合某个请求。请描述用户意图，而不是实现细节。
好的描述应：
- 说明工具的作用。
- 解释何时使用该工具。
- 明确该工具与类似工具的区别。
- 指出重要限制或前提条件。
避免仅仅重复工具名称，或在描述中使用用户不了解的内部服务术语。
规划安全注解
根据实际行为设置注解。请参阅 MCP
ToolAnnotations
模式，
了解这些提示的标准定义、默认值及相互作用：
- 只有当工具无法更改状态时，
readOnlyHint才为true。 - 当工具可能造成不可逆或难以逆转的结果时，
destructiveHint为true。 - 当工具访问公共互联网或
范围不受限定的外部实体时，
openWorldHint为true，其中也包括通过 网页搜索等只读操作进行访问的情况。范围明确的私有账户或工作空间 不会仅因托管在外部就被视为开放世界。
注解不能替代服务器端授权、输入验证或对具有重大影响的操作进行确认。
检查覆盖范围和边界
将拟议工具与完整的使用场景清单进行对照：
- 确认每个受支持的使用场景都有途径获得有用的结果。
- 找出不服务于任何已记录使用场景的工具。
- 检查是否缺少用户在执行写入操作前所需的读取操作。
- 验证对于不受支持的请求，系统会给出易于理解的限制说明，而不是以不安全的方式勉强处理。
- 测试两个相似工具的描述是否存在重叠，导致选择时发生混淆。
保留最终的工具计划，将其作为实现和评估的检查清单。 然后构建 MCP 服务器，并使用 具有代表性的输入、无效输入和未经授权的输入测试每个契约。