Tool annotations

Why annotations matter

An LLM-driven agent can call tools without your supervision. Without metadata, it cannot tell “list customers” (safe to spam) apart from “delete customer” (definitely not). Tool annotations are how MCP tells your client which is which — so a well-built client can apply policy automatically.

The four flags

Every EPD tool declares four boolean hints:

Flag	Meaning	Example tools
readOnlyHint	Tool only reads data; does not change anything.	get_customer, list_orders, get_revenue_summary
destructiveHint	Tool deletes, cancels, refunds, or otherwise changes things in a way that is hard to reverse.	delete_customer, cancel_subscription, refund_order
idempotentHint	Tool can be called multiple times with the same arguments and produce the same result.	Most CRUD tools, all read tools.
openWorldHint	Tool reaches outside EPD (e.g. webhooks delivering to your URL, third-party gateway).	None today — kept for future tools.

Multiple flags can apply to the same tool. cancel_subscription is both destructive and idempotent (canceling an already-canceled subscription is harmless).

How to use them in a client

Example — what an agent sees

{
  "name": "cancel_subscription",
  "description": "Cancel an existing subscription. Cancelling at period end keeps access until the period closes.",
  "inputSchema": { "/* ... */" },
  "annotations": {
    "title": "Cancel subscription",
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

A well-behaved agent reads destructiveHint: true and asks the user before calling.

Browse all tools by safety