Tool Annotations

MCPGate populates the standard MCP annotations field on every tool it exposes. Annotations are hints — not enforced guarantees — that tell your client how risky a tool is so it can decide how much confirmation to require.

Spec-compliant

These annotations follow the MCP specification exactly. No custom fields are used at this layer. If your client already handles MCP annotations, it will work with MCPGate without any changes.

Annotation fields#

Field	Type	Meaning
`title`	string	Human-readable tool title for display in UIs
`readOnly`	boolean	Tool only reads data, never modifies external state
`destructive`	boolean	Tool may permanently delete or irreversibly modify data
`idempotent`	boolean	Calling the tool multiple times with the same input produces the same result
`openWorldHint`	boolean	Tool interacts with external services beyond MCPGate itself

Category-to-annotation mapping#

MCPGate assigns annotations based on the tool category. Every tool gets openWorldHint: true because all tools call external APIs.

Category	readOnly	destructive	idempotent	openWorldHint
read — list, search, get	true	false	true	true
write — create, send, update	false	false	false	true
delete — delete, archive, remove	false	true	false	true

Example payloads#

Read tool#

gmail_read_email — annotations

json

{
  "name": "gmail_read_email",
  "description": "Fetch a Gmail message by ID and return its headers and body.",
  "annotations": {
    "title": "Read Email",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "openWorldHint": true
  }
}

Write tool#

gmail_send_email — annotations

json

{
  "name": "gmail_send_email",
  "description": "Compose and send an email via Gmail.",
  "annotations": {
    "title": "Send Email",
    "readOnly": false,
    "idempotent": false,
    "destructive": false,
    "openWorldHint": true
  }
}

Delete tool#

gmail_delete_email — annotations

json

{
  "name": "gmail_delete_email",
  "description": "Permanently delete a Gmail message by ID.",
  "annotations": {
    "title": "Delete Email",
    "readOnly": false,
    "idempotent": false,
    "destructive": true,
    "openWorldHint": true
  }
}

How clients should use annotations#

Annotations are hints for your UI, not security controls. Use them to decide how much friction to present:

readOnly: true — safe to auto-approve without user confirmation. The tool cannot change any state outside MCPGate.
destructive: true — always require explicit user confirmation before invoking. Show the tool name and parameters clearly.
idempotent: true — safe to retry on failure. Your client can implement automatic retry logic.
openWorldHint: true — the tool reaches external services. This is true for all MCPGate tools.

Hints, not enforcement

Annotations are informational. The actual safety boundary is enforced by MCPGate's Guardrails engine, which runs server-side on every tool call regardless of what your client does with the annotations.

For richer per-tool data beyond the spec annotations — including numeric risk levels, human-readable category labels, and action templates for activity feeds — see Extended Metadata.