Annotations d’outils MCP : readOnlyHint et destructiveHint expliqués

Les annotations d’outils MCP sont un petit bloc de métadonnées (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) qu’un serveur attache à chaque outil qu’il expose. L’hôte à l’autre bout (Claude Desktop, Cursor, un client MCP sur mesure) peut ainsi distinguer une consultation sans danger d’une modification de vos données avant même de l’appeler. Done les définit sur l’ensemble de ses 84 outils, en les dérivant directement de la liste qui applique déjà la restriction des jetons en lecture seule. Le discours de sécurité annoncé et celui qui est appliqué ne peuvent donc pas diverger.

Que signifient réellement readOnlyHint, destructiveHint, idempotentHint et openWorldHint ?

• readOnlyHint : true si l’appel ne peut rien modifier. Les 34 outils de lecture de Done (list_my_tasks, get_task, get_digest, fleet_status et les autres) le portent. Les 50 autres, qui créent, modifient ou suppriment quelque chose, ne le portent pas.
• destructiveHint : true si l’appel supprime ou écrase quelque chose qui existe déjà, au lieu de seulement ajouter. delete_task et delete_project sont les cas évidents. update_task compte aussi, puisque écraser un champ détruit ce qu’il contenait avant, même si les suppressions de Done sont réversibles et récupérables depuis la Corbeille.
• idempotentHint : true si appeler deux fois la même écriture avec les mêmes arguments laisse les choses dans le même état qu’un seul appel. block_task ou set_step_status peuvent être répétés sans risque. Tout ce qui ajoute une nouvelle ligne (comment_on_task, start_run, decompose_task) ne le peut pas, et ne le porte donc pas.
• openWorldHint : indique si l’outil sort d’un ensemble fermé et connu de ressources. Presque tous les outils de Done ne touchent que les lignes de votre propre compte, liens de calendrier compris. La valeur y est donc false. Les exceptions sont les outils de connecteur (search_context, read_context, save_context), qui vont chercher dans les applications que vous avez connectées, comme Drive, Slack ou Notion, et le signalent avec true.

Pourquoi un hôte a-t-il besoin de cela au lieu de simplement demander au modèle ?

Parce que ce n’est pas le modèle qui décide de vous solliciter ou non. C’est l’hôte, et il doit décider avant que l’appel s’exécute, pas après. Un hôte qui veut laisser passer les appels en lecture seule sans vous interrompre, mais marquer une pause devant tout ce qui supprime ou écrase des données, a besoin d’un endroit où lire cette distinction, sans dépendre du fait que le modèle devine correctement l’intention à partir du nom ou de la description d’un outil à chaque appel.

Que se passe-t-il si un serveur ne déclare aucune annotation ?

Cela ne se lit pas comme « probablement sans risque ». Un hôte qui ne peut pas classer un outil doit supposer le pire à son sujet : un appel sans annotation est traité comme une écriture destructrice et non vérifiée sur un monde ouvert, lectures comprises. C’est le manque que Done a comblé. Ses 84 outils ont tous été livrés un temps sans bloc d’annotations. Un hôte qui filtrait tout ce qui n’était « pas explicitement en lecture seule » devait donc filtrer les 84, get_digest et list_my_tasks au même titre que delete_task, parce que rien dans les échanges ne lui disait le contraire.

Comment Done garde-t-il des annotations exactes ?

En les dérivant de la source de vérité que le contrôle de portée utilise déjà, au lieu d’en écrire à la main une seconde copie qui pourrait diverger. WRITE_TOOLS est l’ensemble qui décide si un jeton limité à la lecture seule a le droit d’appeler quelque chose. annotationsFor() lit ce même ensemble pour décider de readOnlyHint. Une écriture destructrice ou idempotente est vérifiée par rapport à deux autres ensembles, DESTRUCTIVE_TOOLS et CONVERGENT_TOOLS, construits selon la même logique (écrase-t-elle ou supprime-t-elle ? converge-t-elle quand on la répète ?). Il y a donc un seul endroit qui dit ce que fait un outil, et non un chemin d’application d’un côté et une description annoncée de l’autre qui se contrediraient en silence.

Les annotations remplacent-elles l’étape d’approbation ou la restriction des jetons ?

Non. C’est une couche différente, en amont des deux. La restriction des jetons contrôle ce que les identifiants d’un agent lui permettent d’appeler. L’étape d’approbation de Done contrôle si une tâche qui n’est pas en clôture automatique peut se clôturer sans la validation d’un humain. Les annotations MCP sont ce sur quoi l’interface d’un hôte peut agir avant même d’atteindre l’une ou l’autre, par exemple en vous demandant de confirmer un appel destructeur sur le moment plutôt qu’après coup. Aucune des trois ne remplace les autres. Les annotations sont des indications pour le jugement de l’hôte, pas une frontière de sécurité sur laquelle Done s’appuierait à elle seule : le contrôle de portée et l’étape d’approbation appliquent toujours les vraies limites côté serveur, quoi que fasse un hôte des métadonnées.