# MCP Tool Annotations

> Hints on an MCP tool that say if it only reads, or may delete things.

**Field:** Artificial Intelligence  
**Category:** MCP  
**Also known as:** Tool Annotations, readOnlyHint, destructiveHint, idempotentHint, openWorldHint, MCP Tool Hints

## Think of it like

It is like a label on a box that says glass. It helps, but the label could be wrong.

## Definition

MCP tool annotations are hints a server attaches to a tool to say how it acts. readOnlyHint says the tool only reads and changes nothing. destructiveHint says it may delete or overwrite things. idempotentHint says calling it twice does no more than once. openWorldHint says it reaches the outside world, like the web. A client may use them to decide when to ask you first.

## Example

A search tool is marked read only, so the app runs it without asking. A delete tool is marked destructive, so the app asks you first.

## Example code

```json
"annotations": {
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false
}
```

A tool that changes things and may delete them, but stays inside its own system.

## Why it matters

They let an app skip the questions for safe tools and slow down for risky ones. That makes tools both quicker and safer.

## Common mistake

Trusting them from any server. The spec says to treat them as untrusted unless the server is trusted.

## Three principles

- **Hints, not promises.** A server could get them wrong.
- **Safe by default.** No hint means may destroy.
- **Help the ask.** Apps use them to ask or not.

## Related terms

- [MCP Tool](https://learn.benibix.com/term/ai/mcp-tool)
- [MCP Server](https://learn.benibix.com/term/ai/mcp-server)
- [Human-in-the-Loop](https://learn.benibix.com/term/ai/human-in-the-loop)
- [Tool Poisoning](https://learn.benibix.com/term/ai/tool-poisoning)
- [Permission Mode](https://learn.benibix.com/term/ai/permission-mode)

![On the left, a tool's description with annotation hints such as readOnlyHint and an output schema. In the middle, the tool's result holding a text block for the model and a structuredContent block for code. On the right, an MCP App: a small web page from a ui:// resource drawn in a walled box inside the chat.](https://learn.benibix.com/diagrams/ai8-mcp-tool-result.svg)

---

Source: https://learn.benibix.com/term/ai/mcp-tool-annotations
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-18
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
