# 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. Last verified against OpenAI plugin guidelines, section 6.3 on 2026-11-18.

## 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](https://developers.openai.com/plugins/plugin-guidelines)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/annot-write-marked-readonly)
- [readOnlyHint, destructiveHint and openWorldHint are explicit booleans](https://isokron.ai/mcp-check/checks/openai-hints-explicit)
- [No tool-level execution field from 2025-11-25](https://isokron.ai/mcp-check/checks/spec-execution-legacy)
- [MCP tool annotations](https://isokron.ai/mcp-check/checks/annotations)

Counts toward: OpenAI plugin directory.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
