Best practice per WebMCP

Alexandra Klepper

Pubblicato: 18 maggio 2026

La dichiarazione dello strumento WebMCP deve essere chiara, senza che gli sviluppatori o gli agenti debbano esaminare gli output e riprovare. Indipendentemente dal fatto che utilizzi l'API imperativa o l'API dichiarativa, segui queste best practice:

• Prima di creare, definisci una strategia per gli strumenti.
• Utilizza un linguaggio chiaro e HTML semantico.
• Progetta gli schemi e gestisci l'input.
• Creare strumenti affidabili.
• Test e debug.

Abbiamo scritto separatamente in merito alla creazione di strumenti orientati alla sicurezza.

Creare una strategia per gli strumenti

Come faresti per qualsiasi applicazione software, il primo passo è pianificare la strategia degli strumenti:

• Ogni strumento deve essere costituito da una singola funzione. Ad esempio, uno strumento potrebbe indirizzare l'utente a un tipo di modulo specifico, mentre un altro strumento dovrebbe abbinare i campi di input alle informazioni dell'utente. Fai attenzione a non creare strumenti sovrapposti, perché l'agente potrebbe non sapere quale usare. Chiediti: posso coprire più attività con la stessa funzione?
• Gestisci la registrazione degli strumenti. Registra gli strumenti quando sono utili in un determinato stato della pagina, poi annulla la registrazione quando lo strumento non è più utilizzabile.
  • API imperative: puoi gestire dinamicamente la registrazione con registerTool.
  • API dichiarativa: puoi gestire dinamicamente la registrazione aggiungendo o rimuovendo gli attributi dello strumento in un modulo con toolname e tooldescription.
• Ridurre la complessità:per la maggior parte delle applicazioni, la registrazione statica dovrebbe essere l'approccio predefinito.
• Affidati all'agente per completare l'attività. Invece di scrivere istruzioni rigide o negative, supponi che l'agente sia in grado di capire cosa è necessario per completare l'attività, anziché aspettarti che gestisca un flusso esatto di passaggi.

Sebbene non esista un numero massimo di strumenti consentiti, ogni strumento occupa una parte della finestra contestuale e aumenta il tempo di completamento. Più strumenti fornisci e più si sovrappongono, più è difficile per l'agente scegliere correttamente. Sperimenta per determinare cosa è giusto per la tua applicazione.

In questo modo puoi creare strumenti individuali, senza sovrapposizioni di scopo, e gestire quando questi strumenti sono disponibili.

Utilizza un linguaggio chiaro e un codice semantico

Usa un linguaggio chiaro e preciso per denominare gli strumenti e descriverne l'utilizzo. In questo modo gli agenti possono trovare ciò di cui hanno bisogno, comprendere ciò che trovano e utilizzare le informazioni come previsto dallo sviluppatore.

Quando scrivi i nomi degli strumenti, distingui l'esecuzione dall'avvio e utilizza verbi che descrivono esattamente cosa succede. Ad esempio, create-event è uno strumento per la creazione immediata di eventi, mentre start-event-creation-process è uno strumento che reindirizza l'utente a un modulo per creare l'evento.

Una descrizione chiara deve descrivere la funzione dello strumento e quando utilizzarlo. Utilizza un linguaggio e preferenze positivi anziché negativi, come limitazioni.

Riduzione al minimo del calcolo cognitivo

Proprio come dovresti ridurre al minimo il carico cognitivo per gli esseri umani che svolgono attività complesse, dovresti anche ridurre al minimo il calcolo cognitivo per il modello:

• Accetta l'input utente non elaborato. Evita di chiedere all'agente di eseguire calcoli o trasformare le stringhe di input. Ad esempio, se un utente dice "Dalle 11:00 alle 15:00", lo strumento deve accettarlo come stringa. Evita di chiedere al modello di calcolare i minuti tra questi orari.
• Dichiara tipi specifici per i parametri, ad esempio stringa, numero o enum.
• Spiega perché hai fatto determinate scelte. La scelta che hai fatto dovrebbe essere autoesplicativa. Il perché aiuta gli agenti a fare scelte migliori. Ad esempio, se gestisci un negozio di e-commerce, dichiara il tipo di spedizione con un linguaggio naturale anziché utilizzare un ID ambiguo: shipping="Express" anziché shipping_id=1.

Dare la priorità all'affidabilità

Gli agenti e gli esseri umani traggono vantaggio da strumenti che si comportano come previsto:

• Imposta un errore controllato per i limiti di frequenza. Gli strumenti devono consentire una ripetizione ragionevole, ad esempio per il confronto dei prezzi. Se uno strumento è soggetto a limitazione della frequenza, restituisci un errore significativo o consiglia all'utente di svolgere manualmente l'attività.
• Aggiorna lo stato dell'interfaccia dopo il completamento delle funzioni. Gli agenti potrebbero fare affidamento sull'interfaccia per pianificare i passaggi successivi, mentre le funzioni potrebbero richiedere più tempo per essere completate rispetto al caricamento dell'interfaccia. L'agente deve confermare che la funzione è completata una volta aggiornata l'interfaccia o richiedere nuovamente un aggiornamento.
• Esegui la convalida in modo rigoroso nel codice e in modo approssimativo nello schema. I vincoli e i test devono essere utilizzati per le funzioni e il codice con logica binaria. Sebbene i vincoli dello schema possano essere utili, non sono garantiti. Aggiungi errori descrittivi al codice della funzione per consentire al modello di correggersi e riprovare con parametri nuovi e validi.

Test e debug della valutazione

Crea test di valutazione e rendi disponibili i tuoi strumenti per il debug. A differenza dei test unitari deterministici, le valutazioni non possono essere codificate in modo rigido, poiché gli output possono assumere forme impreviste.

• Definisci il problema. Puoi inquadrare il problema come un contratto API, inclusi il tipo di input, il formato di output e qualsiasi vincolo aggiuntivo.
• Definisci una base di riferimento e un risultato ideale. Soprattutto con l'input di testo, è importante capire quali tipi di risultati possono darti l'output che ti aspetti.
• Determina come verrà valutato l'output. Probabilmente identifichi e misuri risultati soggettivi e qualitativi in base alla qualità, all'utilità e alla capacità dell'input di portare a termine l'attività successiva. Esistono diverse tecniche che puoi utilizzare per valutare l'output, tra cui controlli basati sul codice per output basati su regole (limiti di caratteri) e LLM-as-a-judge.

Evita di aggiungere regole restrittive per risolvere problemi con un modello specifico. Ad esempio, se includi un campo di selezione per i titoli onorifici, il modello potrebbe fare la scelta sbagliata. Anziché aggiungere regole restrittive per risolvere il problema, rendi astratto e modifica lo strumento. Ti consigliamo di impostare questo campo come facoltativo. Poi, chiedi all'agente di chiedere all'utente quale scelta ha più senso, per assicurarsi che sia soddisfatto del risultato.

Partecipare e condividere feedback

WebMCP è in fase di discussione e soggetto a modifiche in futuro. Se provi queste API e hai un feedback, saremo felici di riceverlo.

• Leggi la spiegazione di WebMCP, fai domande e partecipa alla discussione.
• Esamina l'implementazione per Chrome su Stato di Chrome.
• Partecipa al programma di anteprima per dare un'occhiata in anteprima alle nuove API e accedere alla nostra mailing list.
• Se hai feedback sull'implementazione di Chrome, segnala un bug di Chromium.