---
title: "Label every tool with hints that match · Agent Wranglers"
url: https://agentwranglers.se/playbook/agents-as-users/safe-actions/honest-tool-annotations
id: AGT-36
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 987
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Label every tool with hints that match what it does

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Safe actions](https://agentwranglers.se/playbook/agents-as-users/safe-actions.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: AGT-36
- Level: Recommended
- Chapter: [Safe actions](https://agentwranglers.se/playbook/agents-as-users/safe-actions.md)
- Rule: Set `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint` on every tool. A test proves each value against what the tool does to a test account.
- Check: A test calls every tool marked `readOnlyHint: true` on a test account and compares a snapshot of the account before and after, with no difference. Every tool marked `idempotentHint: true` runs twice with the same arguments and makes one change. Every tool that deletes or overwrites data has `destructiveHint: true`.
- Spec version: MCP 2026-07-28
- Review by: 2027-04-30
- How: Clients use these hints to decide which calls run without asking and which need the person's approval. A missing hint falls back to the default, which marks a tool as writing, destructive and open to the outside world. So a lookup without hints gets confirmed like a delete, and people learn to click yes. A wrong hint is worse, because it lets a delete run unasked. Clients must treat hints from servers they do not trust as untrusted. Your own checks still protect the account, as [Confirm risky actions with a token bound to the exact request](https://agentwranglers.se/playbook/agents-as-users/safe-actions/confirmation-token.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JSON example

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

### JavaScript example

```js
test('read-only tools change nothing', async () => {
  for (const tool of tools.filter(t => t.annotations.readOnlyHint)) {
    const before = await snapshotAccount(TEST_ACCOUNT);
    await callTool(tool.name, sampleArguments(tool));
    expect(await snapshotAccount(TEST_ACCOUNT)).toEqual(before);
  }
});
```

### Python example

```python
def test_read_only_tools_change_nothing():
    for tool in [t for t in TOOLS if t.annotations.read_only_hint]:
        before = snapshot_account(TEST_ACCOUNT)
        call_tool(tool.name, sample_arguments(tool))
        assert snapshot_account(TEST_ACCOUNT) == before
```

## Sources

- [MCP schema, ToolAnnotations](https://modelcontextprotocol.io/specification/2026-07-28/schema)
- [MCP tools, security considerations](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)

## Related rules

- AGT-21 [Confirm risky actions with a token bound to the exact request](https://agentwranglers.se/playbook/agents-as-users/safe-actions/confirmation-token.md) in Agents as users
- AGT-61 [Publish a server card for your MCP server](https://agentwranglers.se/playbook/agents-as-users/ready-for-ai-agents/mcp-and-tool-discovery.md) in Agents as users

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/agents-as-users/safe-actions/honest-tool-annotations">Agent Wranglers agents as users playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Run agent calls through the same business rules as the app](https://agentwranglers.se/playbook/agents-as-users/safe-actions/same-rules-for-agents.md)
- [Safe actions](https://agentwranglers.se/playbook/agents-as-users/safe-actions.md)