Tools that start jobs or queue work are not read-only
A tool that starts a job, queues work, schedules something or persists an artifact changes external state, so OpenAI asks for readOnlyHint: false even if the tool returns only a job ID.
Check openai-readonly-starts-job · OpenAI plugin directory · default severity: attention · rubric 2.1.0
What fails
The name reads as starting, running, scheduling or queueing something, but the tool sets readOnlyHint: true.
The rule
Use false for external-state changes, persisting artifacts, starting stateful jobs or workflows, queuing work, or write-style outbound actions such as posting messages, sending emails, or uploading files.
How to fix it
Set "readOnlyHint": false and choose destructiveHint for what the job does.
- Set readOnlyHint: false on run_, start_, schedule_, export_ and queue_ tools.
- Choose destructiveHint for what the job does: false for an export, true if it overwrites or sends.
- Say in the description that the tool starts work and how to check its result.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'start_export',
{
title: 'Start export',
description: 'Start exporting one report and return a job ID; the file is ready later. Use when the user asks for a downloadable report.',
inputSchema: z.strictObject({
report_id: z.string().describe('Report ID, for example REP-9'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ report_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
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="Start export",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def start_export(
report_id: Annotated[str, Field(description="Report ID, for example REP-9")],
) -> str:
"""Start exporting one report and return a job ID; the file is ready later. Use when the user asks for a downloadable report."""
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
The tool does not change any record. Why is it not read-only?
It creates a job that runs and consumes resources, and may persist a file. OpenAI lists starting stateful jobs and queuing work as non-read-only.
Does a dry-run or preview tool count?
No. A preview that computes and returns without persisting anything is read-only.
Related checks
- Tools named as writes are not marked read-only
- readOnlyHint, destructiveHint and openWorldHint are explicit booleans
- No tool-level execution field from 2025-11-25
- All checks in MCP tool annotations
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