Anotaciones de herramientas MCP: cómo el host de tu agente de IA sabe qué llamadas necesitan tu visto bueno

Las anotaciones de herramientas MCP son un pequeño bloque de metadatos —readOnlyHint, destructiveHint, idempotentHint, openWorldHint— que un servidor adjunta a cada herramienta que expone, para que el host del otro lado (Claude Desktop, Cursor, un cliente MCP propio) pueda distinguir una consulta inofensiva de un cambio en tus datos antes de llamarla. Done las define en sus 56 herramientas, derivadas directamente de la misma lista que ya aplica el límite de solo lectura en los tokens, así que lo que se anuncia sobre seguridad y lo que realmente se aplica no pueden desincronizarse.

¿Qué significan realmente readOnlyHint, destructiveHint, idempotentHint y openWorldHint?

• readOnlyHint: true si la llamada no puede cambiar nada. Las 18 herramientas de lectura de Done (list_my_tasks, get_task, get_digest, fleet_status y el resto) lo tienen; las otras 38, que crean, actualizan o eliminan algo, no.
• destructiveHint: true si la llamada elimina o sobrescribe algo que ya existía, en lugar de solo agregar. delete_task y delete_project son los casos obvios; update_task también cuenta, porque sobrescribir un campo destruye lo que había antes, aunque en Done las eliminaciones son reversibles y se pueden recuperar desde la Papelera.
• idempotentHint: true si hacer la misma escritura dos veces con los mismos argumentos deja todo igual que hacerla una sola vez. block_task o set_step_status se pueden repetir sin problema; todo lo que agrega un registro nuevo —comment_on_task, start_run, decompose_task— no, así que no lo lleva.
• openWorldHint: indica si la herramienta llega más allá de un conjunto cerrado y conocido de recursos. Todas las herramientas de Done tocan solo los registros de tu propia cuenta, incluidos los vínculos con el calendario, así que es false en todas.

¿Por qué el host necesita esto en lugar de simplemente preguntarle al modelo?

Porque quien decide si pedirte confirmación no es el modelo, sino el host, y tiene que decidirlo antes de que la llamada se ejecute, no después. Un host que quiere dejar pasar las llamadas de solo lectura sin interrumpirte, pero detenerse ante cualquier cosa que elimine o sobrescriba datos, necesita un lugar donde leer esa distinción que no dependa de que el modelo adivine bien la intención a partir del nombre o la descripción de la herramienta en cada llamada.

¿Qué pasa si un servidor no declara ninguna anotación?

No se interpreta como “seguramente está bien”. Un host que no puede clasificar una herramienta tiene que suponer lo peor: una llamada sin anotaciones se trata igual que una escritura destructiva no verificada sobre un mundo abierto, incluso si es una lectura. Esa es la brecha que cerró Done: durante un tiempo, sus 56 herramientas no tenían bloque de anotaciones, así que un host que pedía confirmación para todo lo que “no fuera explícitamente de solo lectura” tenía que pedirla para las 56 —get_digest y list_my_tasks junto con delete_task—, porque nada en la comunicación le indicaba lo contrario.

¿Cómo mantiene Done la honestidad de las anotaciones?

Derivándolas de la misma fuente de verdad que ya usa la protección de alcance, en lugar de escribir a mano una segunda copia que podría desincronizarse. WRITE_TOOLS es el conjunto que decide si un token de solo lectura puede llamar a una herramienta; annotationsFor() lee ese mismo conjunto para decidir readOnlyHint. Una escritura destructiva o idempotente se compara con dos conjuntos más —DESTRUCTIVE_TOOLS y CONVERGENT_TOOLS—, construidos con la misma lógica (¿sobrescribe o elimina?, ¿converge al repetirse?), así que hay exactamente un lugar que dice lo que hace una herramienta, y no una ruta de aplicación y una descripción anunciada que se contradicen en silencio.

¿Las anotaciones reemplazan la aprobación o el límite de los tokens?

No: son otra capa, anterior a ambas. El límite del token controla qué puede llamar un agente con sus credenciales; la aprobación de Done controla si una tarea que no es auto-OK puede cerrarse sin que una persona la apruebe; las anotaciones MCP son aquello sobre lo que la propia interfaz del host puede actuar antes de llegar a cualquiera de las dos, por ejemplo, pidiéndote que confirmes en el momento una llamada destructiva en lugar de enterarte después. Ninguna de las tres sustituye a las otras, y las anotaciones son pistas para el criterio del host, no un límite de seguridad en el que Done confíe por sí solo: la protección de alcance y la aprobación siguen aplicando los límites reales en el servidor, sin importar qué haga el host con los metadatos.