Skip to content
IsoKron

readOnlyHint, destructiveHint and openWorldHint are explicit booleans

OpenAI requires readOnlyHint, destructiveHint and openWorldHint as explicit true or false booleans in every tool’s annotations, even where the MCP specification has a default; the submission form will not continue until they are set.

Check openai-hints-explicit · OpenAI plugin directory · default severity: blocking · rubric 2.1.0

Error message you’ll see

Error
Each MCP tool must set readOnlyHint, openWorldHint, and destructiveHint to true or false.

ChatGPT app submission form (blocks Continue until every tool has all three). Where this was reported

What fails

OpenAI requires all three hints on every tool, even where the specification has a default.

The rule

Set readOnlyHint, destructiveHint, and openWorldHint to the appropriate explicit boolean values (true or false) in each tool’s annotations object.

Source: OpenAI plugin guidelines, section 6.3

How to fix it

Add every missing hint with an explicit true or false.

  1. On every tool, set all three hints explicitly.
  2. readOnlyHint: true only for retrieval, computation or previews; destructiveHint: true for deletes, overwrites, cancellations, revocations and irreversible sends.
  3. openWorldHint: true when the tool reaches outside your own system (public web, third-party services, other users), false for a closed system.
Before
"annotations": { "readOnlyHint": true }
After
"annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false }

TypeScript SDK

TypeScript
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'search_issues',
  {
    title: 'Search issues',
    description: 'Search issues in the user’s workspace by text. Use when the user describes an issue but has no ID.',
    inputSchema: z.strictObject({
      query: z.string().describe('Words to search for'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ query }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);

Python SDK

Python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="Search issues",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def search_issues(
    query: Annotated[str, Field(description="Words to search for")],
) -> str:
    """Search issues in the user’s workspace by text. Use when the user describes an issue but has no ID."""
    return "Done"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

Questions

What does openWorldHint mean?

Whether the tool interacts with an open world of external entities (the web, third-party services, other people’s data) rather than a closed domain the server controls. A web search tool is open-world; a lookup in your own database is not.

I set all three and the form still complains. Why?

Check that the values are JSON booleans, not strings, on every tool including later pages of tools/list, and that the submitted URL serves the updated server. A platform-side bug causing this was reported and fixed in the OpenAI developer forum.

Does FastMCP set these?

Only if you pass them: @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "openWorldHint": False}).

How this check is graded

It counts toward: OpenAI plugin directory. See the rubric.

Last verified against OpenAI plugin guidelines, section 6.3 on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere