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

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

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

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

## 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](https://isokron.ai/mcp-check/checks/surface-retry-key)
- [Every tool has a non-empty description](https://isokron.ai/mcp-check/checks/openai-description)
- [Every tool carries the applicable hint](https://isokron.ai/mcp-check/checks/anthropic-hint)
- [Write-surface design for MCP tools](https://isokron.ai/mcp-check/checks/write-safety)

## Further reading

- [MWS-RETRY: retry requirements](https://isokron.ai/mws#mws-retry-1)
- [Do popular packaged MCP servers say whether a write happened?](https://isokron.ai/research/mcp-write-results-100-servers)

Counts toward: OpenAI plugin directory.

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

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