Best practice per WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Pubblicato il 18 maggio 2026

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, crea una strategia per gli strumenti.
  • Usa un linguaggio chiaro e HTML semantico.
  • Progetta gli schemi e gestisci l'input.
  • Crea strumenti affidabili.
  • Esegui test e debug.

Crea una strategia per gli strumenti

Come faresti per qualsiasi applicazione software, il primo passo è pianificare la strategia per gli 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 utilizzare. 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, quindi annulla la registrazione quando lo strumento non è più utilizzabile.
    • API imperativa: 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.
  • Riduci 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, presupponi che l'agente sia in grado di comprendere ciò che è 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. Fai delle prove per determinare la soluzione più adatta alla tua applicazione.

In questo modo, puoi creare singoli strumenti, senza scopi sovrapposti, e gestire la disponibilità di questi strumenti.

Usa un linguaggio chiaro e codice semantico

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

Quando scrivi i nomi degli strumenti, distingui l'esecuzione dall'inizializzazione e usa verbi che descrivano esattamente ciò che accade. 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 cosa fa lo strumento e quando utilizzarlo. Affidati a un linguaggio e a preferenze positive anziché a un linguaggio negativo, ad esempio limitazioni.

Cosa non fare

"Non utilizzare questo strumento per il meteo."

Le limitazioni devono essere implicite in una descrizione ben scritta.
Cosa fare

"Questo strumento può creare un evento di calendario, pianificato per una data e un'ora specifiche."

Riduci al minimo il calcolo cognitivo

Proprio come dovresti ridurre al minimo il carico cognitivo per le persone che completano 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 accettare questa 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 deve essere autoesplicativa. Il motivo aiuta gli agenti a fare scelte migliori. Ad esempio, se gestisci un negozio di e-commerce, dichiara il tipo di spedizione con il linguaggio naturale anziché utilizzare un ID ambiguo: shipping="Express" anziché shipping_id=1.

Dai la priorità all'affidabilità

Gli agenti e le persone 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 limiti di frequenza, restituisci un errore significativo o consiglia all'utente di svolgere manualmente l'attività.
  • Aggiorna lo stato dell'interfaccia al termine 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 è stata completata una volta aggiornata l'interfaccia o richiedere di nuovo un aggiornamento.
  • Esegui la convalida in modo rigoroso nel codice e in modo meno rigoroso 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 automaticamente e riprovare con nuovi parametri validi.

Test e debug della valutazione

Crea test di valutazione e rendi disponibili gli strumenti per il debug. A differenza dei test delle unità deterministici, le valutazioni non possono essere hardcoded, 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 baseline e un risultato ideale. Soprattutto con l'input di testo, è importante capire quali tipi di risultati possono generare l'output previsto.
  • Determina come verrà valutato l'output. Probabilmente identificherai e misurerai risultati soggettivi e qualitativi in base alla qualità dell'input, all'utilità e alla capacità di svolgere l'attività successiva. Puoi utilizzare diverse tecniche per valutare l'output, inclusi controlli basati sul codice per gli output basati su regole (limiti di caratteri) e LLM-as-a-judge.

Evita di aggiungere regole restrittive per risolvere i problemi con un modello specifico. Ad esempio, se includi un campo di selezione per i titoli onorifici, il modello potrebbe fare la scelta sbagliata. Invece di aggiungere regole restrittive per risolvere questo problema, astrarre e modificare lo strumento. Potresti ottenere risultati migliori impostando questo campo come facoltativo. Poi, chiedi all'agente di chiedere all'utente quale scelta ha senso, per assicurarti che l'utente sia soddisfatto del risultato.

Interagisci e condividi feedback

WebMCP è in fase di discussione attiva e sarà soggetto a modifiche in futuro. Se provi queste API e hai feedback, saremo felici di riceverli.