Declare every tool's side effects before it is called

Tell the client up front whether each tool reads or writes, whether a write can destroy something, whether a retry is safe, and whether the tool reaches outside your system, so it can decide when to stop and ask the user.

Why

An agent's client has to decide, before every call, whether to run a tool silently or put a confirmation in front of the user. It can only make that call well if the tool says what it does. MCP gives servers four flags for this in ToolAnnotations: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. The defaults are the cautious ones: a tool with no annotations is assumed to write (readOnlyHint false), to be destructive (destructiveHint true), not to be idempotent and to reach an open world. Leaving them unset therefore buries harmless reads under confirmation prompts, and a wrong false lets a delete through without one. OpenAI's app submission guidelines require explicit booleans on every tool and spell out what counts as destructive: deletion, overwriting, cancellation, access revocation, irreversible sends or transactions. Anthropic's guidance for MCP server authors makes the same point: annotations disclose which tools need open-world access or make destructive changes. The flags are hints, not guarantees. The MCP schema tells clients never to base tool use decisions on annotations from untrusted servers, and OpenAI notes that annotations do not replace authorization, input validation or human confirmation. Declare them honestly and still enforce the real checks on the server.

Do

Set all four annotations explicitly on every tool, using the cautious value when in doubt.

Don't

Mark a tool read-only or non-destructive to avoid confirmation prompts, or treat the flags as your only safeguard.

Artifact

{
  "name": "cancel_subscription",
  "description": "Cancel a customer's subscription at the end of the current billing period.",
  "inputSchema": {
    "type": "object",
    "properties": { "subscription_id": { "type": "string" } },
    "required": ["subscription_id"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}