Best practice per WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Pubblicato: 18 maggio 2026

La dichiarazione dello strumento WebMCP deve essere chiara, senza che sviluppatori o agenti debbano esaminare gli output e riprovare. Indipendentemente dal fatto che utilizzi l'API imperativa o 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.

Creare una strategia per gli strumenti

Come faresti per qualsiasi applicazione software, il primo passo dovrebbe essere 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 utilizzare. Chiediti: posso coprire più attività con la stessa funzione?
  • Gestire la registrazione dello strumento. 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 e unregisterTool.
    • API dichiarativa: puoi gestire dinamicamente la registrazione aggiungendo o rimuovendo gli attributi dello strumento in un modulo, con toolName e toolDescription.
  • Riduzione della complessità:per la maggior parte delle applicazioni, la registrazione statica dovrebbe essere l'approccio predefinito.
  • Affidati all'agente per completare l'attività*. Anziché 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 parte della finestra contestuale e aumenta il tempo necessario per il completamento. Più strumenti fornisci e più questi 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 sovrapposizioni di scopo, e gestire quando questi strumenti sono disponibili.

Utilizzare un linguaggio chiaro e un codice semantico

Usa un linguaggio chiaro e diretto 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 di scrittura, distingui l'esecuzione dall'avvio e usa verbi che descrivano 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.

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 nel calendario, pianificato per una data e un'ora specifiche".

Ridurre al minimo il 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 il 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 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 è completa una volta aggiornata l'interfaccia o richiedere nuovamente un aggiornamento.
  • Convalida rigorosa nel codice, meno rigorosa 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 di Eval

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, in quanto 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à dell'input, all'utilità e alla capacità di svolgere 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 specifiche per risolvere il problema, rendi più astratto e regola 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.

Interagire e condividere feedback

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