// GLOSSARY -- MCP & TOOL INFRASTRUCTURE

What are MCP Tool Annotations?

1 min read Updated

Server-declared metadata hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) that describe a tool's behavioural properties, introduced in the March 2025 MCP spec revision.

WHY IT MATTERS

Tool annotations let MCP servers self-report what their tools do. A server can declare that delete_file is destructive, or that get_user is read-only. Clients can use these hints to show confirmation dialogs or apply different trust levels.

The problem: annotations are self-reported and unverified. A malicious server can mark a destructive tool as read-only. The spec explicitly states these are 'hints' with no enforcement guarantee. Independent classification is needed to verify what tools actually do, not just what they claim.

See mcp tool annotations working in your own stack — route your MCP servers through PolicyLayer and every tool call is checked against policy before it runs.

GOVERN YOUR MCP SERVERS →

Enforced before the call runs. Nothing to install.

HOW POLICYLAYER USES THIS

PolicyLayer's catalogue independently classifies 18k+ MCP tools by analysing their names, descriptions, and input schemas — providing verification that goes beyond self-reported annotations.

Browse the MCP server catalogue →

FREQUENTLY ASKED QUESTIONS

Are annotations mandatory?
No. They're optional hints. Many servers don't include them, and those that do may be inaccurate.
What annotations exist?
readOnlyHint (no state changes), destructiveHint (irreversible), idempotentHint (safe to retry), and openWorldHint (interacts with external systems).

FURTHER READING

Take your agents live. Without losing control.

Route your MCP traffic through PolicyLayer. Every tool call is checked against your policy before it runs: allow, deny, or require approval. Per-identity grants. Full audit log. Live in minutes.

GOVERN YOUR MCP SERVERS →

Instant setup, no code required.

46,500+ MCP servers and 515,000+ tools scanned and risk-classified.

// GET IN TOUCH

Have a question or want to learn more? Send us a message.

Message sent.

We'll get back to you soon.