Declara los efectos de cada herramienta antes de que se llame

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

{
  "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
  }
}