# Delete tools take a confirm or dry-run argument

**Give delete tools a dry_run (default true) or confirm argument, so the model can show what will be removed before the irreversible call; OpenAI notes annotations do not replace human confirmation for irreversible operations.**

Check `surface-delete-guard` · Write-surface design · default severity: advice · rubric 2.1.0. Last verified against OpenAI plugin guidelines, section 6.3 on 2026-11-18.

## What fails

A dry_run or confirm argument lets the model preview what a delete will remove before it is irreversible. This is a design prompt from the tool list, not a test.

## The rule

> Annotations inform client safeguards; they do not grant permission or replace authentication, authorization and scope checks, input validation, or human confirmation for irreversible operations.

Source: [OpenAI plugin guidelines, section 6.3](https://developers.openai.com/plugins/plugin-guidelines)

## How to fix it

Add "dry_run": { "type": "boolean", "default": true } and return what would be deleted.

1. Add dry_run: boolean, default true, and return what would be deleted.
2. Delete only when dry_run is false (or confirm is true).
3. Keep destructiveHint: true; the argument adds a preview, not a permission.

### 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(
  'delete_project',
  {
    title: 'Delete project',
    description: 'Delete one project and its issues. With dry_run true (the default) returns what would be deleted and deletes nothing. Use only when the user asks to delete a project.',
    inputSchema: z.strictObject({
      project_id: z.string().describe('Project ID, for example PRJ-7'),
      dry_run: z.boolean().default(true).describe('true: preview only; false: delete'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
  },
  async ({ project_id, dry_run }) => ({ 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="Delete project",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=False),
)
def delete_project(
    project_id: Annotated[str, Field(description="Project ID, for example PRJ-7")],
    dry_run: Annotated[bool, Field(description="true: preview only; false: delete")] = True,
) -> str:
    """Delete one project and its issues. With dry_run true (the default) returns what would be deleted and deletes nothing. Use only when the user asks to delete a project."""
    return "Done"
```

## Questions

### Does the client not already confirm destructive tools?

It asks whether to run the call, usually showing only the arguments. A dry run shows what the call will actually remove, which is what the user needs to decide.

### Should the default be true?

Yes: the safe default means a model that omits the argument previews instead of deleting.

## Related checks

- [Bulk deletes have a guard](https://isokron.ai/mcp-check/checks/surface-bulk-delete)
- [Deleting tools are not marked non-destructive](https://isokron.ai/mcp-check/checks/annot-delete-marked-safe)
- [Update and delete tools take a version or precondition](https://isokron.ai/mcp-check/checks/surface-version-guard)
- [Write-surface design for MCP tools](https://isokron.ai/mcp-check/checks/write-safety)

## Further reading

- [MCP write safety](https://isokron.ai/write-safety)

Counts toward: Write-surface design.

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

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