What Are MCP Tool Annotations?

MCP tool annotations are hints that an MCP server, such as the one DocStar hosts for every docs collection, attaches to each tool to tell AI clients how risky it is: whether it only reads data, whether it can delete or overwrite, whether repeating it is safe, and whether it reaches outside systems. AI clients such as Claude, ChatGPT and Cursor can use these hints to decide when to ask the user before running a tool. In DocStar, every collection's hosted MCP server ships with these hints already set, and your AI agent can tune them for your API in one prompt.
This guide explains the four hints in plain English, what they can and can't do, and how we handle them in DocStar so the assistants calling your API know when to stop and ask.
What are MCP tool annotations?
When an MCP server lists its tools, each tool can include an optional annotations object next to its name, description and input schema. The annotations don't change what the tool does. They describe its behaviour so the client can treat it safely: show a clear title, run a harmless lookup without fuss, and put a confirmation prompt in front of anything that could do damage.
As of November 2026, the MCP schema defines a display title plus four boolean hints:
| Hint | The question it answers | Default if left out |
|---|---|---|
readOnlyHint |
Does the tool change anything? | false (assume it changes things) |
destructiveHint |
Can a change delete or overwrite data, rather than only add? | true (assume it can) |
idempotentHint |
Is calling it again with the same input harmless? | false (assume it isn't) |
openWorldHint |
Does it reach systems outside the server, such as a live API? | true (assume it does) |
The defaults are deliberately pessimistic. A tool with no annotations is treated as a write tool that might be destructive, might not be safe to repeat, and talks to the outside world. That is the safe assumption, but it also means clients may ask for confirmation on every call, including harmless reads. Good annotations remove that friction for safe tools and keep it for dangerous ones.
What annotations can and can't do
Annotations are hints, not enforcement. The MCP specification says clients "MUST consider tool annotations to be untrusted unless they come from trusted servers", and it recommends that there should always be a human in the loop with the ability to deny tool calls. The MCP team's own post on the topic (March 2026) makes the same point: a server can label a tool read-only and still delete data, so hints mainly drive confirmation prompts, not security.
In practice that gives you a simple rule:
Use annotations to shape the experience. Mark lookups read-only so assistants run them freely. Mark deletes destructive so they get a confirmation.
Enforce permissions in your API. Your API still checks who the caller is and what they may do. Annotations never replace that.
Keep a person in charge of risky actions. Destructive tools should always end in a "yes" from a human.
If you want the full security picture (OAuth, API keys and per-user sign-in), read MCP Server Authentication Explained.
How tool annotations work in DocStar
DocStar gives every documentation collection its own hosted MCP server, so you never write or host MCP server code to get annotations right. For an API collection, that server has four built-in tools: docs search, API docs, a read tool that calls any endpoint with GET only, and a call tool that handles POST, PUT, PATCH and DELETE. Splitting reads from writes is the most useful annotation decision you can make, and DocStar makes it for you.
On top of that you control the hints in four places:
| What you control | What it does |
|---|---|
| Endpoint tools | Give up to 20 of your most important published endpoints their own named tool (for example list_invoices or delete_invoice), each with its own safety hints: read-only, destructive, idempotent or open-world. |
| Built-in tool hints | DocStar generates a title and hints for the built-in tools. You can replace the description and annotations with your own, or reset to the generated ones at any time. |
| Turn off the call tools | Switch off the general read tool, the write tool or both, so assistants reach your API only through the endpoint tools you chose and annotated. |
| Skill and instructions | The skill says which endpoints are safe to call freely and which to confirm first; instructions (under 2,000 characters) add rules such as "Always confirm before deleting anything." |
Because hints are only hints, DocStar pairs them with real controls. With sign-in turned on, every API call runs as the signed-in user, with that user's own permissions, and the OAuth client secret is stored only on the MCP server. Only published endpoints can become tools, and drafts never reach your MCP server.
[Screenshot: DocStar MCP tab listing endpoint tools with their safety hints]
Let your AI agent set the hints
You don't need to work out the hints for every endpoint by hand. DocStar is built to be set up by your AI agent.
1. Connect your agent to DocStar. In Claude Code, Cursor, Codex or another assistant, add DocStar from the connector directory or as a custom MCP server with https://mcp.docstar.io/mcp. You sign in through the browser; no API key to paste. See Connect your AI assistant.
2. Give it one prompt. Run it from your API's repo so the agent can read the code:
Use the DocStar MCP. Read the API in this repo and check our "Payments API" collection in DocStar. Pick the 10 endpoints our users need most and make each one an endpoint tool with accurate safety hints: read-only for lookups, destructive for anything that deletes or overwrites, idempotent where repeating a call is harmless. Update the skill so it says which calls need confirmation, and add an instruction to always confirm before deleting or refunding. Show me the plan before you change anything.
3. The agent does the work. It reads your routes, matches them to the published endpoints in the collection, proposes a name, description and hints for each tool, and drafts the skill and instructions. It shows you what it will create or change and waits for your OK. Your DocStar permissions apply: if you can only read the collection, so can your agent.
4. You make the judgment calls. This is the part only a person should do:
Decide which endpoints become tools at all, and which stay behind the general call tool (or off entirely).
Check every
destructiveHint: falseclaim. If a "refund" or "archive" endpoint can't be undone, it is destructive.Decide whether to turn off the general write tool so assistants can only use the actions you named.
5. Test with a real assistant. Add your collection's MCP URL to Claude or Cursor and try a few tasks. Reads should run straight through; deletes should stop and ask. Then open Logs in the MCP tab to see every call the assistant made: the input, the request sent to your API and your API's response. A 404 usually means a wrong path or id; a 400 or 422 means a bad request body. Secrets are masked, and calls are kept for two weeks.
New to building these servers? Start with How to Turn Your API into an MCP Server Without Writing Server Code.
Keep the hints current
Annotations go stale the same way docs do. Yesterday's harmless "update" endpoint gains a hard-delete option, and the tool still says it isn't destructive. Make reviewing hints part of the code change:
Add a rule to AGENTS.md or CLAUDE.md: when an API changes, the agent updates that endpoint in DocStar with the DocStar MCP, re-checks the tool's safety hints, saves as draft, and publishes only when asked.
Ask after each release:
Use the DocStar MCP. We just shipped the changes in CHANGELOG.md. For every endpoint tool on our Payments API MCP server that these changes affect, check whether its description and safety hints are still accurate, and propose updates. Don't publish anything.
- Read the logs. If assistants keep calling the wrong tool, or users keep getting confirmations for harmless reads, the description or hints need work.
This only works when the agent actually runs it. DocStar doesn't watch your repo or flag outdated hints by itself, so keep the rule in your agent instructions and the review in your pull requests.
Annotations vs descriptions vs instructions
Annotations are one of three ways to steer an assistant on your MCP server. Each has a job:
| Tells the assistant | Best for | |
|---|---|---|
| Annotations | How risky a tool is | Confirmation prompts, auto-approving safe reads |
| Tool descriptions | What a tool does and when to use it | Picking the right tool for the task |
| Skill and instructions | How your API works as a whole | Call order, required ids, house rules |
Weak descriptions cause more failed calls than missing hints. For that side, read How to Write MCP Tool Descriptions That AI Agents Actually Understand.
Prefer to set it yourself?
You can manage everything through the DocStar API as well. Upsert Endpoint Tool creates or updates an endpoint tool with its annotations, Update Built-in Tool Description sets your own description and hints for a built-in tool, and Set Built-in Tool Enabled turns the read or call tool off. Get MCP Tools shows the hints each tool has now. Full reference: developers.docstar.io. For the settings themselves, see Build an MCP Server for Your App.
Why teams choose DocStar for MCP servers
Safe defaults with no server code. Reads and writes are separate tools from day one, with generated hints.
Fine control where it matters. Up to 20 endpoint tools with their own hints, plus the option to switch off the general call tools.
Hints backed by real permissions. Per-user sign-in means every call runs with the user's own access.
Agent-first setup. Your coding agent reads the code, proposes tools and hints, and waits for your OK.
One source of truth. The same docs power your docs site, llms.txt, the MCP server and the CLI.
FAQ
Are MCP tool annotations required?
No. They are optional. But a tool without them is treated as potentially destructive, so clients may ask for confirmation on every call. In DocStar, the built-in tools come with generated hints, and you set hints on your endpoint tools.
Do annotations stop an AI assistant from deleting data?
No. They are hints that clients use to decide when to ask the user. Your API still has to enforce permissions. In DocStar, sign-in makes each call run as the signed-in user, so the assistant can only do what that user is allowed to do.
Which hints should a DELETE endpoint have?
Usually readOnlyHint: false and destructiveHint: true. Many deletes are also idempotent (deleting the same record twice has no further effect), so idempotentHint: true can be accurate. Check how your API actually behaves.
Can I change the hints DocStar generated?
Yes. You can set your own description and annotations for the built-in tools, and reset them to the generated ones at any time. Your AI agent can do this for you through the DocStar MCP.
Get started free
Give the assistants calling your API clear safety hints from day one, without writing MCP server code. Connect your AI agent to DocStar, point it at your API, and review the tools it proposes. Get started free.
Keep reading

Agent Skills vs MCP: What's the Difference?
Agent skills give AI agents know-how; MCP lets them act. Learn the difference and how one DocStar collection gives you MCP tools and a skill.

How to Create Interactive API Documentation
Create interactive API docs with a Try It button, code snippets and reader variables. Let your AI agent draft each endpoint, then review and publish in DocStar.