Tool annotations
How EPD tells your agent which tools are safe, which mutate, and which need explicit approval.
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 may interact with external systems beyond EPD’s own data model. | test_webhook_endpoint, replay_webhook_event |
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
Let the agent freely call any tool with readOnlyHint: true. Listing, getting, summarizing — no human approval needed.
Pause and ask for human confirmation before calling any tool with destructiveHint: true. Especially in live mode.
On 5xx or transient failure, retry tools with idempotentHint: true without escalating.
Log every openWorldHint: true call separately so you can see when the agent is configuring or triggering calls to external systems.
Example — what an agent sees
{
"name": "cancel_subscription",
"description": "Cancel an existing subscription immediately.",
"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
All list_*, get_*, preview_*, compare_*, plus ping, get_account, get_revenue_summary, get_customer_financial_summary, list_past_due_subscriptions.
delete_*, cancel_subscription, refund_order, refund_transaction, retry_order, retry_failed_charge, refund_and_cancel, cancel_subscription_and_report, upgrade_account_api_version, upgrade_webhook_version, downgrade_webhook_version.
Webhook tools that configure or trigger delivery to your URL, including create_webhook_endpoint, update_webhook_endpoint, test_webhook_endpoint, replay_webhook_event, and setup_webhook_monitoring.