WebMCP-best practices

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Gepubliceerd: 18 mei 2026

De declaratie van een WebMCP -tool moet duidelijk zijn, zonder dat ontwikkelaars of agents de uitvoer hoeven te bekijken en het opnieuw hoeven te proberen. Of u nu de Imperatieve API of de Declaratieve API gebruikt, volg deze best practices:

  • Voordat je gaat bouwen, ontwikkel een gereedschapsstrategie.
  • Gebruik duidelijke taal en semantische HTML.
  • Ontwerp je schema's en verwerk de invoer.
  • Ontwikkel betrouwbare tools.
  • Testen en debuggen.

Ontwikkel een toolstrategie

Net zoals bij elke andere softwaretoepassing, is uw eerste stap het plannen van uw toolstrategie:

  • Elk hulpmiddel moet uit één enkele functie bestaan . Een hulpmiddel zou bijvoorbeeld de gebruiker naar een specifiek formuliertype kunnen leiden, terwijl een ander hulpmiddel de invoervelden koppelt aan de gebruikersinformatie. Zorg ervoor dat er geen overlappende hulpmiddelen zijn, omdat de agent dan niet meer weet welk hulpmiddel hij moet gebruiken. Stel jezelf de vraag: kan ik meerdere taken met dezelfde functie uitvoeren?
  • Beheer de registratie van tools . Registreer tools wanneer ze nuttig zijn in een bepaalde paginastatus en verwijder de registratie wanneer de tool niet langer bruikbaar is.
    • Imperatieve API : U kunt de registratie dynamisch beheren met registerTool en unregisterTool .
    • Declaratieve API : U kunt de registratie dynamisch beheren door de toolkenmerken op een formulier toe te voegen of te verwijderen, met behulp van toolName en toolDescription .
  • Verminder de complexiteit: voor de meeste toepassingen zou statische registratie de standaardaanpak moeten zijn.
  • Vertrouw erop dat de agent de taak voltooit *. In plaats van rigide of negatieve instructies te geven, ga ervan uit dat de agent begrijpt wat er nodig is om de taak te voltooien, in plaats van te verwachten dat de agent een exacte stappenreeks volgt.

Hoewel er geen maximum aantal toegestane tools is, neemt elke tool een deel van het contextvenster in beslag en verlengt dit de verwerkingstijd. Hoe meer tools u aanbiedt en hoe meer de tools elkaar overlappen, hoe moeilijker het voor de agent is om de juiste tool te selecteren. Experimenteer om te bepalen wat het beste werkt voor uw toepassing.

Dit helpt je bij het bouwen van afzonderlijke tools, zonder overlappende doelen, en bij het beheren van de beschikbaarheid van deze tools.

Gebruik duidelijke taal en semantische code.

Gebruik duidelijke en directe taal om tools te benoemen en hun gebruik te beschrijven. Dit helpt agenten om te vinden wat ze nodig hebben, te begrijpen wat ze vinden en die informatie te gebruiken zoals de ontwikkelaar verwacht.

Bij het benoemen van tools is het belangrijk onderscheid te maken tussen uitvoering en initiatie, en werkwoorden te gebruiken die precies beschrijven wat er gebeurt. Zo is create-event een tool voor het direct aanmaken van een evenement, terwijl start-event-creation-process een tool is die de gebruiker doorverwijst naar een formulier om het evenement aan te maken.

Een duidelijke beschrijving moet uitleggen wat de tool doet en wanneer je hem moet gebruiken. Gebruik positieve taal en benadruk voorkeuren in plaats van negatieve taal, zoals beperkingen.

Niet doen

"Gebruik deze tool niet voor het weer."

Beperkingen dienen impliciet aanwezig te zijn in een goed geschreven beschrijving.
Doen

"Met deze tool kunt u een agenda-item aanmaken, gepland voor een specifieke datum en tijd."

Minimaliseer cognitieve computergebruik

Net zoals je de cognitieve belasting voor mensen die complexe taken uitvoeren moet minimaliseren, moet je ook de cognitieve rekenkracht voor het model minimaliseren:

  • Accepteer onbewerkte gebruikersinvoer . Vermijd het uitvoeren van wiskundige bewerkingen of het transformeren van de invoerstrings door de agent. Als een gebruiker bijvoorbeeld zegt: "11:00 tot 15:00", moet de tool dit als een string accepteren. Vermijd het model te vragen de minuten tussen deze tijden te berekenen.
  • Declareer specifieke gegevenstypen voor parameters , zoals tekenreeks, getal of opsomming.
  • Leg uit waarom je bepaalde keuzes hebt gemaakt . De gemaakte keuze moet voor zich spreken. De 'waarom' helpt medewerkers betere keuzes te maken. Als je bijvoorbeeld een webshop beheert, geef dan het verzendtype aan in natuurlijke taal in plaats van een vage ID te gebruiken: shipping="Express" in plaats van shipping_id=1 .

Geef prioriteit aan betrouwbaarheid.

Zowel agenten als mensen hebben baat bij tools die zich gedragen zoals verwacht:

  • Stel een gecontroleerde foutmelding in voor snelheidslimieten . Tools moeten redelijke herhaling toestaan, bijvoorbeeld bij prijsvergelijkingen. Als een tool de snelheidslimiet bereikt, geef dan een duidelijke foutmelding of adviseer de gebruiker om de taak handmatig uit te voeren.
  • Werk de interfacestatus bij nadat functies zijn voltooid . Agents kunnen de interface gebruiken om de volgende stappen te plannen, terwijl functies langer kunnen duren dan het laden van de interface. De agent moet bevestigen dat de functie is voltooid zodra de interface is bijgewerkt, of opnieuw een update aanvragen.
  • Valideer strikt in de code, maar losjes in het schema . Beperkingen en testen moeten worden gebruikt voor functies en code met binaire logica. Hoewel schemabeperkingen nuttig kunnen zijn, bieden ze geen garantie. Voeg beschrijvende foutmeldingen toe aan je functiecode, zodat het model zichzelf kan corrigeren en het opnieuw kan proberen met nieuwe, geldige parameters.

Evaluatietesten en debuggen

Maak evaluatietests en stel je tools beschikbaar voor debugging. In tegenstelling tot deterministische unit tests kunnen evaluaties niet hardgecodeerd worden, omdat de output onverwachte vormen kan aannemen.

  • Definieer het probleem . Je kunt je probleem formuleren als een API-contract, inclusief het invoertype, het uitvoerformaat en eventuele aanvullende beperkingen.
  • Definieer een basislijn en een ideaal resultaat . Vooral bij tekstinvoer is het belangrijk te begrijpen welke resultaten de gewenste output opleveren.
  • Bepaal hoe de output geëvalueerd zal worden . Je identificeert en meet waarschijnlijk subjectieve, kwalitatieve resultaten op basis van de kwaliteit van de input, de bruikbaarheid en het vermogen om de volgende taak uit te voeren. Er zijn verschillende technieken die je kunt gebruiken om de output te evalueren, waaronder codegebaseerde controles voor regelgebaseerde outputs (tekenlimieten) en LLM als beoordelaar .

Vermijd het toevoegen van strikte regels om problemen met een specifiek model op te lossen. Als u bijvoorbeeld een selectieveld voor aanspreekvormen toevoegt, kan het model de verkeerde keuze maken. In plaats van strikte regels toe te voegen om dit probleem op te lossen, kunt u beter abstraheren en uw tool aanpassen. U kunt dit veld bijvoorbeeld het beste als optioneel instellen. Vraag de agent vervolgens om de gebruiker te vragen welke keuze het meest logisch is, zodat de gebruiker tevreden is met het resultaat.

Betrek de deelnemers en deel je feedback.

WebMCP wordt momenteel actief besproken en kan in de toekomst nog veranderen. Als u deze API's uitprobeert en feedback heeft, horen we dat graag.