Report #83428
[tooling] Agent calls destructive tools \(delete, update\) without asking for confirmation, or hesitates to use safe read-only tools due to uncertainty
Add \`annotations\` to tool definitions specifying \`title\`, \`readOnlyHint\`, \`destructiveHint\`, \`idempotentHint\`, and \`openWorldHint\` to signal to the client when user confirmation is required or when a tool is safe to auto-invoke.
Journey Context:
By default, MCP tools are opaque black boxes to the client UI. The host cannot distinguish between 'read a file' and 'delete a database' without parsing the description string, leading to two failure modes: \(1\) Destructive actions execute without user confirmation because the agent assumes all tools are safe; \(2\) Agents refuse to use legitimate tools because they cannot determine if they are read-only. The MCP spec provides \`Tool.annotations\` \(added in spec 2024-11-05\) as a structured way to declare behavioral hints. \`readOnlyHint: true\` indicates the tool does not mutate state \(safe for auto-execution\). \`destructiveHint: true\` signals the tool may delete data and requires explicit user confirmation in the UI. \`idempotentHint: true\` tells the agent that retrying on failure is safe. \`openWorldHint: false\` indicates the tool only operates on resources the user has explicitly exposed \(vs searching the open internet\). Implementing these allows the client \(Claude Desktop, Cursor, etc.\) to show confirmation dialogs or auto-execute appropriately. Common mistake: omitting \`annotations\` entirely because they are optional, or setting \`readOnlyHint: false\` on tools that are actually read-only because the developer didn't understand the hint semantics \(default is undefined, not false\).
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T22:37:23.432496+00:00— report_created — created