Appearance
定义工具
为你的助手规划和定义工具。
工具优先思维
在 Apps SDK 中,工具是你的 MCP 服务器和模型之间的契约。它们描述了连接器可以做什么、如何调用它以及返回什么数据。良好的工具设计使发现准确、调用可靠以及下游用户体验可预测。
在接触 SDK 之前,使用下面的检查清单将你的用例转化为范围明确的工具。
起草工具表面区域
从你在用例研究中定义的用户旅程开始:
- 每个工具一项工作 – 保持每个工具专注于单个读取或写入操作("fetch_board"、"create_ticket"),而不是一个大杂烩端点。这有助于模型在备选方案之间做出决定。
- 明确的输入 – 现在定义
inputSchema的形状,包括参数名称、数据类型和枚举。记录默认值和可空字段,以便模型知道什么是可选的。 - 可预测的输出 – 枚举你将返回的结构化字段,包括模型可以在后续调用中重用的机器可读标识符。
如果你需要读取和写入行为,请创建单独的工具,以便 ChatGPT 可以遵守写入操作的确认流程。
捕获用于发现的元数据
发现几乎完全由元数据驱动。对于每个工具,起草:
- 名称 – 面向操作且在连接器内唯一(
kanban.move_task)。 - 描述 – 一两句话,以"在...时使用此工具"开头,以便模型确切知道何时选择该工具。
- 参数注释 – 描述每个参数并指出安全范围或枚举。当用户提示词含糊不清时,此上下文可防止格式错误的调用。
- 全局元数据 – 确认你已为目录和启动器准备好应用级别的名称、图标和描述。
稍后,将这些插入你的 MCP 服务器,并使用优化元数据工作流进行迭代。
模型端防护栏
思考一旦工具被链接,模型应该如何行为:
- 预链接与需要链接 – 如果你的应用可以匿名工作,将工具标记为无需身份验证即可使用。否则,确保你的连接器通过认证中描述的入门流程强制执行链接。
- 只读提示 – 为不能改变状态的工具设置
readOnlyHint注释,以便 ChatGPT 可以在可能的情况下跳过确认提示。 - 结果 component – 决定每个工具应该渲染一个 component、仅返回 JSON,还是两者都有。在工具描述符上设置
_meta["openai/outputTemplate"]会向 ChatGPT 通告 HTML 模板。
黄金提示词排练
在实施之前,根据你之前捕获的提示词列表对工具集进行合理性检查:
- 对于每个直接提示词,确认你恰好有一个工具明确解决该请求。
- 对于间接提示词,确保工具描述为模型提供足够的上下文,以选择你的连接器而不是内置替代方案。
- 对于负面提示词,验证你的元数据将保持工具隐藏,除非用户明确选择加入(例如,通过命名你的产品)。
现在捕获任何差距或歧义并调整计划——在启动前更改元数据比稍后重构代码要便宜得多。
移交给实施
当你准备好实施时,将以下内容编译成移交文档:
- 工具名称、描述、输入模式和预期输出模式。
- 工具是否应该返回一个 component,如果是,应该由哪个 UI component 渲染它。
- 认证要求、速率限制和错误处理期望。
- 应该成功的测试提示词(以及应该失败的提示词)。
将此计划带入设置你的服务器指南,使用你选择的 MCP SDK 将其转化为代码。