Skip to content
IsoKron

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.

Source: OpenAI plugin guidelines, section 6.3

How to fix it

Set "readOnlyHint": false and choose destructiveHint for what the job does.

  1. Set readOnlyHint: false on run_, start_, schedule_, export_ and queue_ tools.
  2. Choose destructiveHint for what the job does: false for an export, true if it overwrites or sends.
  3. Say in the description that the tool starts work and how to check its result.

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(
  '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

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="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.

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