// 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.

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.

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

Enforce policies on every tool call

Intercept is the open-source MCP proxy that enforces YAML policies on AI agent tool calls. No code changes needed.

npx -y @policylayer/intercept
github.com/policylayer/intercept →
// GET IN TOUCH

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

Message sent.

We'll get back to you soon.