La conferma sulle scritture

I tool di lettura (GET, “Tipo: Lettura” nel catalogo) si chiamano senza altro. I tool di scrittura — creare un lead, aggiornare un appuntamento, inviare un messaggio… qualsiasi tool marcato “Tipo: Scrittura” — richiedono un argomento aggiuntivo: confirm: true.

Come funziona

1. Il tuo assistente decide di chiamare un tool di scrittura (per esempio aymar_leads_create).

2. Se la chiamata non include confirm: true, il server MCP la rifiuta prima di toccare la API — non viene creato nulla — e restituisce un riepilogo leggibile di ciò che stava per fare:

   {
     "error": "confirmation_required",
     "message": "This action requires confirmation. Review the summary and call again with confirm: true.",
     "action_summary": "POST /public/v1/leads (aymar_leads_create) with customerName='Lead di esempio', quality='hot'"
   }

3. Un client MCP ben progettato mostra quel action_summary alla persona e richiama il tool con confirm: true solo se la persona approva esplicitamente.

4. Con confirm: true, la chiamata arriva alla API e il lead viene creato davvero.

Cosa vede l’utente

Ciò che la persona vede a schermo dipende dal suo client MCP, non da Aymar Agents: ogni client decide come presenta un action_summary e come chiede l’approvazione (una finestra di conferma, un messaggio dello stesso assistente che chiede un “sì”…). Ciò che Aymar Agents garantisce è il livello minimo: il server MCP non esegue mai una scrittura senza un confirm: true esplicito nella chiamata, qualunque sia il client — questo non dipende dal fatto che il client “si comporti bene”, è un controllo che fa il server stesso prima di inoltrare qualsiasi cosa alla API.

Perché esiste

È lo stesso principio che governa il resto del prodotto: un modello linguistico può decidere di chiamare il tool sbagliato, o interpretare male un’istruzione — l’LLM non è mai, da solo, l’unica barriera prima di una scrittura reale. Il confirm obbligatorio fa sì che quell’errore, se accade, si fermi a un riepilogo di testo — mai a un lead creato, un appuntamento spostato o un messaggio inviato senza che nessuno lo approvasse.

Nessuna cancellazione

Nessun tool può cancellare nulla — la API pubblica non ha nessun endpoint DELETE (vedi Casi d’uso e il riferimento completo). Il peggior caso di una scrittura confermata male è un record in più o un dato non aggiornato, mai una perdita di dati.