Annotazioni degli strumenti MCP: readOnlyHint e destructiveHint spiegati

Le annotazioni degli strumenti MCP sono un piccolo blocco di metadati (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) che un server allega a ogni strumento che espone, così l'host dall'altra parte (Claude Desktop, Cursor, un client MCP personalizzato) può distinguere una consultazione innocua da una modifica ai tuoi dati prima ancora di chiamarlo. Done le imposta su tutti i suoi 84 strumenti, ricavandole direttamente dallo stesso elenco che già fa rispettare i token di sola lettura: così ciò che viene dichiarato sulla sicurezza e ciò che viene applicato non possono divergere.

Che cosa significano davvero readOnlyHint, destructiveHint, idempotentHint e openWorldHint?

• readOnlyHint: true se la chiamata non può modificare nulla. Lo hanno i 34 strumenti di lettura di Done (list_my_tasks, get_task, get_digest, fleet_status e gli altri); non lo hanno gli altri 50, che creano, aggiornano o eliminano qualcosa.
• destructiveHint: true se la chiamata rimuove o sovrascrive qualcosa che c'è già, invece di aggiungere soltanto. delete_task e delete_project sono i casi ovvi; conta anche update_task, perché sovrascrivere un campo distrugge ciò che conteneva prima, anche se le eliminazioni di Done sono reversibili e recuperabili dal Cestino.
• idempotentHint: true se chiamare due volte la stessa scrittura con gli stessi argomenti lascia le cose nello stesso stato di una sola chiamata. block_task o set_step_status si possono ripetere senza rischi; tutto ciò che aggiunge una nuova riga (comment_on_task, start_run, decompose_task) no, quindi non lo ha.
• openWorldHint: indica se lo strumento esce da un insieme chiuso e noto di risorse. Quasi tutti gli strumenti di Done toccano soltanto le righe del tuo account, collegamenti al calendario compresi, quindi lì è false. Le eccezioni sono gli strumenti dei connettori (search_context, read_context, save_context), che entrano nelle app che hai collegato, come Drive, Slack o Notion, e lo dichiarano con true.

Perché un host ne ha bisogno, invece di chiedere semplicemente al modello?

Perché non è il modello a decidere se chiederti conferma: è l'host, e deve deciderlo prima che la chiamata venga eseguita, non dopo. Un host che vuole lasciar passare le chiamate di sola lettura senza interromperti, ma fermarsi davanti a tutto ciò che elimina o sovrascrive dati, ha bisogno di un posto in cui leggere questa distinzione senza dipendere dal fatto che il modello indovini ogni volta l'intenzione dal nome o dalla descrizione di uno strumento.

Che cosa succede se un server non dichiara alcuna annotazione?

Non viene letto come “probabilmente va bene”. Un host che non riesce a classificare uno strumento deve presumere il peggio: una chiamata senza annotazioni viene trattata come una scrittura distruttiva e non verificata su un mondo aperto, letture comprese. È la lacuna che Done ha colmato: per un certo periodo tutti i suoi 84 strumenti sono stati distribuiti senza blocco di annotazioni, quindi un host che chiedeva conferma per tutto ciò che non era “esplicitamente di sola lettura” doveva chiederla per tutti e 84 (get_digest e list_my_tasks insieme a delete_task), perché nulla di ciò che riceveva gli diceva il contrario.

Come fa Done a mantenere oneste le annotazioni?

Ricavandole dalla stessa fonte che il controllo dell'ambito usa già, invece di scriverne a mano una seconda copia che potrebbe divergere. WRITE_TOOLS è l'insieme che decide se un token di sola lettura può chiamare qualcosa; annotationsFor() legge lo stesso insieme per decidere readOnlyHint. Una scrittura distruttiva o idempotente viene confrontata con altri due insiemi, DESTRUCTIVE_TOOLS e CONVERGENT_TOOLS, costruiti con la stessa logica (sovrascrive o rimuove? converge se ripetuta?), quindi c'è un solo posto che dice che cosa fa uno strumento, non un percorso di applicazione e una descrizione dichiarata che in silenzio si contraddicono.

Le annotazioni sostituiscono il passaggio di approvazione o l'ambito dei token?

No: sono un livello diverso, a monte di entrambi. L'ambito dei token controlla che cosa le credenziali di un agente gli permettono di chiamare; il passaggio di approvazione di Done controlla se un'attività senza Auto-OK può chiudersi senza il via libera di una persona; le annotazioni MCP sono ciò su cui l'interfaccia di un host può agire prima ancora di arrivare a uno dei due, per esempio chiedendoti sul momento di confermare una chiamata distruttiva, invece che a cose fatte. Nessuno dei tre sostituisce gli altri, e le annotazioni sono indicazioni per il giudizio dell'host, non un confine di sicurezza su cui Done fa affidamento da solo: il controllo dell'ambito e il passaggio di approvazione continuano ad applicare i limiti veri sul server, qualunque cosa un host faccia con i metadati.