Skip to content
IsoKron

Write tools say whether a retry repeats the effect

OpenAI asks that tools be safe to retry where possible, or say when a retry repeats the effect; mark naturally repeatable writes with idempotentHint: true, and say so in the description of writes that are not.

Check openai-retry · OpenAI plugin directory · default severity: attention · rubric 2.1.0

What fails

The write tool neither declares idempotentHint: true nor mentions retries, duplicates or idempotency in its description. A model that loses the answer will often call again.

The rule

Tools should be safe to retry where possible, or explicitly indicate when retries may cause repeated effects.

Source: OpenAI plugin guidelines, section 1.2

How to fix it

Make the tool safe to repeat (for example with an idempotency key) and say so, or state in the description that a repeated call repeats the effect.

  1. Decide per write tool: does a second identical call change anything more?
  2. If not (set state, delete by ID), set idempotentHint: true.
  3. If yes (create, send, charge), add an idempotency key, or state in the description that a repeat call repeats the effect.

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(
  'close_issue',
  {
    title: 'Close issue',
    description: 'Close one issue. Use when the user says an issue is done. Safe to retry: closing a closed issue changes nothing.',
    inputSchema: z.strictObject({
      issue_id: z.string().describe('Issue ID, for example ISS-42'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
  },
  async ({ issue_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="Close issue",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False),
)
def close_issue(
    issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
    """Close one issue. Use when the user says an issue is done. Safe to retry: closing a closed issue changes nothing."""
    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 idempotentHint mean exactly?

That calling the tool again with the same arguments has no additional effect. It is only meaningful on tools that are not read-only.

Why do models retry?

When a response is lost to a timeout or a dropped connection, the model cannot tell whether the call happened and often calls again.

Further reading

How this check is graded

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

Last verified against OpenAI plugin guidelines, section 1.2 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