# AX-SYS-23: Declara los efectos de cada herramienta antes de que se llame

> Tools and capabilities · intermediate · AX-SYS-23

Indica al cliente de antemano si cada herramienta lee o escribe, si una escritura puede destruir algo, si un reintento es seguro y si la herramienta sale de tu sistema, para que pueda decidir cuándo detenerse y preguntar al usuario.

## Por qué

El cliente de un agente tiene que decidir, antes de cada llamada, si ejecuta una herramienta en silencio o pone una confirmación delante del usuario. Solo puede decidirlo bien si la herramienta dice lo que hace. MCP da a los servidores cuatro indicadores para esto en `ToolAnnotations`: `readOnlyHint`, `destructiveHint`, `idempotentHint` y `openWorldHint`. Los valores por defecto son los prudentes: una herramienta sin anotaciones se considera de escritura (`readOnlyHint` false), destructiva (`destructiveHint` true), no idempotente y con acceso a un mundo abierto. Dejarlos sin definir llena de confirmaciones las lecturas inofensivas, y un `false` equivocado deja pasar un borrado sin ninguna. Las directrices de publicación de apps de OpenAI exigen valores booleanos explícitos en cada herramienta y detallan qué cuenta como destructivo: borrar, sobrescribir, cancelar, revocar accesos, envíos o transacciones irreversibles. La guía de Anthropic para autores de servidores MCP dice lo mismo: las anotaciones revelan qué herramientas necesitan acceso a un mundo abierto o hacen cambios destructivos. Los indicadores son pistas, no garantías. El esquema de MCP pide a los clientes que nunca decidan el uso de una herramienta a partir de anotaciones de servidores no confiables, y OpenAI aclara que las anotaciones no sustituyen la autorización, la validación de entradas ni la confirmación humana. Decláralas con honestidad y aplica igualmente los controles reales en el servidor.

## Haz

Define las cuatro anotaciones de forma explícita en cada herramienta, con el valor prudente si hay dudas.

## No hagas

Marcar una herramienta como de solo lectura o no destructiva para evitar confirmaciones, ni tratar los indicadores como tu única protección.

## Artefacto

```json
{
  "name": "cancel_subscription",
  "description": "Cancel a customer's subscription at the end of the current billing period.",
  "inputSchema": {
    "type": "object",
    "properties": { "subscription_id": { "type": "string" } },
    "required": ["subscription_id"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
```

## Fuentes

1. [MCP Specification 2026-07-28: Schema (ToolAnnotations)](https://modelcontextprotocol.io/specification/2026-07-28/schema): readOnlyHint: if true, the tool does not modify its environment (default false); destructiveHint: if true, the tool may perform destructive updates, if false it performs only additive updates (default true); idempotentHint defaults to false and openWorldHint to true. All properties in ToolAnnotations are hints, and clients should never make tool use decisions based on ToolAnnotations received from untrusted servers
2. [OpenAI Apps SDK: App submission guidelines](https://developers.openai.com/apps-sdk/app-submission-guidelines): Set readOnlyHint, destructiveHint, and openWorldHint to explicit boolean values in each tool's annotations object; for writes, use destructiveHint true for potentially destructive or irreversible effects such as deletion, overwriting, cancellation, access revocation, or irreversible sends or transactions. Annotations inform client safeguards; they do not grant permission or replace authentication, authorization and scope checks, input validation, or human confirmation for irreversible operations
3. [Anthropic Engineering: Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents): If you're writing tools for an MCP server, tool annotations help disclose which tools require open-world access or make destructive changes

---
Source: Agent Experience Principles (axprinciples.com)