# Tool Annotations

Per the [MCP tool annotations spec](https://modelcontextprotocol.io/specification/draft/basic/lifecycle), every tool advertises hints to the client about its behavior. Clients use these hints to:

- Decide whether to auto-approve or prompt for confirmation
- Color-code or group tools in the UI
- Make orchestration decisions (e.g., retry-safe vs. not)


## Annotation Values

| Hint | Meaning |
|  --- | --- |
| `readOnlyHint: true` | Tool only reads data; safe to auto-approve |
| `destructiveHint: true` | Tool may modify or destroy data; client should prompt |
| `idempotentHint: true` | Repeated calls with same args have no additional effect |
| `openWorldHint: true` | Tool reaches external systems beyond the MCP server |


All Outreach MCP tools have `openWorldHint: true` because they reach Outreach's backend. None operate in a closed local environment.

## How Annotations Affect Client Behavior

**Read-only tools** (`readOnlyHint: true`): Most MCP clients auto-approve these calls without user interaction. All [Read & Discovery tools](/mcp-server/tool-catalog#-read--discovery-21-tools) carry this annotation.

**Destructive tools** (`destructiveHint: true`): Most MCP clients prompt the user for confirmation before executing. This includes delete operations and sequence removal. Build your agent flows to expect this UX.

**Idempotent tools** (`idempotentHint: true`): Safe to retry on transient failures. Clients may implement automatic retry logic for these tools.

**Non-idempotent tools** (`idempotentHint: false`): Create operations and LLM-based tools (like `prepare_for_meeting`) are not idempotent — repeated calls produce new results each time.