SEP: Add tool annotation descriptors in-code

[matteo8p]

Preface

This issue is related to tool annotations and is currently only relevant to ChatGPT apps SDK. This is because MCP apps doesn't use tool annotations yet. I added it as a SEP here because I anticipate that MCP apps will also utilize annotations in a similar way. There's currently also isn't anywhere good to put this SEP but here.

Whether or not we want annotations in MCP apps is a separate discussion.

Context

ChatGPT apps SDK requires every tool to define annotations in the tool descriptor. These annotations tell ChatGPT if the tool is read only or dangerous (enforced guardrails w/ explicit approval). See their reference docs for details.

OpenAI app submission form requires developers to write justifications for these annotations.

Issue

We're noticing a lot of developers miss the importance of setting annotations in ChatGPT apps. They only realize they have to set it in the app submission form.

I think it's important for developers to think about these annotations early on in their tool design process, not at the submission stage. Instead of writing down the annotation justifications in the submission form, developers should write them down in-code. This is similar to how we write tool descriptions.

Proposed solution

I propose that developers define the annotation descriptions in code. This provides several benefits:

• Enforces users thinking about annotations intentionally at the early stages of tool design, not at the submission phase.
• Auto updates on app submission. Users don't have to fill out the annotations on the submission form.
• It's an extension of a tool description. Gives the developer further clarity on what the tool does and its consequences.

The primary drawback I can think of is that now tools code is slightly longer.

My proposed solution that can be implemented today would be to have these justifications be baked into tool _meta as openai/annotations/readOnlyHint, etc. It follows existing OpenAI patterns and is simple.

What annotation descriptions might look like in a tool

  server.registerTool(
    "echo_test",
    {
      title: "Echo Test",
      description:
        "Echo's back a message.",
      _meta: {
        "openai/widgetAccessible": true,
        "openai/annotations/readOnlyHint": "It only echos an input message, does not mutate anything", 
        "openai/annotations/destructiveHint": "[justification here]", 
       "openai/annotations/openWorldHint": "[justification here]",
      },
      inputSchema: {
        ...
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        openWorldHint: false,        
      }
    },
    async ({ }) => {
      ...
    },
  );

The above solution is most simple to implement, but I think a more robust solution is to bake it within annotations itself. This would require a change in ModelContextProtocol spec and approval would take longer.

This is what it would look like:

  server.registerTool(
    "echo_test",
    {
      title: "Echo Test",
      description:
        "Echo's back a message.",
      _meta: {
        "openai/widgetAccessible": true,
        "openai/annotations/readOnlyHint": "It only echos an input message, does not mutate anything", 
        "openai/annotations/destructiveHint": "[justification here]", 
       "openai/annotations/openWorldHint": "[justification here]",
      },
      inputSchema: {
        ...
      },
      annotations: {
        readOnlyHint: {
            value: true, 
            description: "This only echos an input string."
        }
        ...    
      }
    },
    async ({ }) => {
      ...
    },
  );

[liady]

@matteo8p thanks for proposing this.
I see your point, however it seems very coupled to ChatGPT Apps submission requirements, as well as to the specific ChatGPT Apps annotations.
I'm not sure the generic MCP Apps SEP should include these justification primitives at this point, as it focuses on defining the rendering and communication layers.

However imo we can definitely keep this issue here, as a reference for a future phase, perhaps with a more generic approach?

I also agree that technically altering the annotations field can (/should) be proposed at the general MCP level. This might provide the generic solution for this problem.

[matteo8p]

@liady Gotcha, yeah I agree that the main focus at the moment should be rendering and communication, before we even think about annotations.

Wanted to put this here, because I don't know anywhere else to put this kind of proposal. Let me know if you'd like me to take this down and I can try moving this somewhere else!

[olaservo]

Hi @matteo8p if you want to carry this forward, I would open this SEP as a PR in the spec repo: https://github.com/modelcontextprotocol/modelcontextprotocol

Agree with Liad though that this seems closely coupled to a specific platform's requirements. Something more generic might be an evolving 'best practices' proposal for documenting the rationale behind the tools' annotations, perhaps even as part of the 'server card' format thats being proposed? It could also include notes on special privacy considerations when integrating these apps as part of external platforms (which is currently the default in the Chat GPT scenario) vs internal-only apps (which I expect more of in the future).