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.
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.
- Decide per write tool: does a second identical call change anything more?
- If not (set state, delete by ID), set idempotentHint: true.
- If yes (create, send, charge), add an idempotency key, or state in the description that a repeat call repeats the effect.
TypeScript SDK
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
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.
Related checks
- Create and send tools take a retry key
- Every tool has a non-empty description
- Every tool carries the applicable hint
- All checks in Write-surface design for MCP tools
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