The annotations.py module

Summary

Functions

annotations_for

Return the behavior hints for a tool.

Constants

READ_ONLY	Reads state or builds code without changing anything.
ADDITIVE	Adds or attaches state without overwriting anything; safe to repeat.
OVERWRITE	Overwrites values or lifecycle state; repeating with the same arguments is harmless.
DESTRUCTIVE	Arbitrary or irreversible mutation; confirm first and never retry blindly.
LEAF_TOOL_ANNOTATIONS	Hints for every tool the shared leaf base and the solve leaf register.

Description

MCP tool annotations (behavior hints) for the leaf tool surface.

MCP hosts (VS Code Copilot, Claude Desktop, Cursor) read readOnlyHint, destructiveHint and idempotentHint to decide which calls can run without confirmation and which ones must not be retried blindly. Each tool is classified by its worst-case action. Lifecycle tools named manage_ can deactivate a component, so they are destructive. Unclassified tools get no annotations and the host falls back to the protocol default (not read-only, possibly destructive).

Module detail

annotations.annotations_for(tool_name: str | None) → dict[str, bool] | None

Return the behavior hints for a tool.

Parameters:

tool_namestr | None

Registered tool name.

Returns:

dict[str, bool] | None

A copy of the hint profile, or None when the tool is unclassified.

annotations.READ_ONLY: dict[str, bool]

Reads state or builds code without changing anything.

annotations.ADDITIVE: dict[str, bool]

Adds or attaches state without overwriting anything; safe to repeat.

annotations.OVERWRITE: dict[str, bool]

Overwrites values or lifecycle state; repeating with the same arguments is harmless.

annotations.DESTRUCTIVE: dict[str, bool]

Arbitrary or irreversible mutation; confirm first and never retry blindly.

annotations.LEAF_TOOL_ANNOTATIONS: dict[str, dict[str, bool]]

Hints for every tool the shared leaf base and the solve leaf register.