Agent Wranglers

AGT-36Recommended

Label every tool with hints that match what it does

Set readOnlyHint, destructiveHint, idempotentHint and openWorldHint on every tool. A test proves each value against what the tool does to a test account.

By Agent Wranglers. Updated .

Spec version

MCP 2026-07-28

Review by

2027-04-30

How to do it

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

Examples

JSON example

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

JavaScript example

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

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

How to 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.

Sources

For agents: this playbook is free to use under CC 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.