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
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.
How to fix it
Add "dry_run": { "type": "boolean", "default": true } and return what would be deleted.
- Add dry_run: boolean, default true, and return what would be deleted.
- Delete only when dry_run is false (or confirm is true).
- Keep destructiveHint: true; the argument adds a preview, not a permission.
TypeScript SDK
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
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"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
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
- Deleting tools are not marked non-destructive
- Update and delete tools take a version or precondition
- All checks in Write-surface design for MCP tools
Further reading
How this check is graded
It counts toward: Write-surface design. See the rubric.
Last verified against OpenAI plugin guidelines, section 6.3 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