WebMCP Declarative API: The Beginner’s Implementation Guide

The Declarative API is the easiest entry point into WebMCP. If your website has existing HTML forms, you can make them agent-callable with just two new HTML attributes — no JavaScript required.

This guide covers everything you need: what the Declarative API is, how it works, how to write it correctly, and how to test and debug your implementation.

Prerequisites

• Your site runs over HTTPS (required — WebMCP will not activate on HTTP pages)
• You have existing HTML forms (contact, booking, quote, search, checkout)
• Chrome 146+ Canary or Beta with the WebMCP flag enabled for testing
• No JavaScript knowledge required for the Declarative API

What the Declarative API Does

The Declarative API lets you annotate an existing HTML form so that AI agents can discover and use it as a structured tool. Instead of the agent crawling your page and guessing how your form works, it reads the tool definition and knows exactly what parameters to provide.

Under the hood, the browser reads your form attributes, generates a tool schema from the input fields, and exposes it through the navigator.modelContext interface — all without you writing a single line of JavaScript.

The Two Required Attributes

toolname

A unique identifier for this tool on the page. Rules:

• camelCase format: bookConsultation, not book-consultation or Book Consultation
• Unique per page — no two forms on the same page should share a toolname
• Descriptive and action-oriented: start with a verb (book, search, get, request, submit)
• No spaces, no special characters

Good examples: bookFreeAudit, requestQuote, searchServices, submitSupportTicket

Bad examples: form1, contact, theContactUsFormOnThisPage

tooldescription

A natural language description that tells the agent what the tool does. This is the most important attribute — write it carefully.

A good tooldescription answers three questions:

• What does this tool do? (action)
• What inputs does it accept and in what format?
• What does it return or produce?

Template for tool descriptions

[Action verb] [what it does]. Accepts: [input 1] ([type/format]), [input 2] ([type/format]). Returns: [what the user or agent gets back].

Example: “Book a free SEO audit. Accepts: name (full name, text), email (email address), website (URL of site to audit). Returns: confirmation message and estimated response time within 24 hours.”

Full Implementation Examples

Example 1: Contact / Free Audit Form

<form
  action="/book-audit"
  method="POST"
  toolname="bookFreeAudit"
  tooldescription="Book a free SEO and website audit.
    Accepts: fullName (text), email (email address),
    website (URL). Returns: booking confirmation and
    a response within 24 business hours.">
  <input name="fullName" type="text"
         placeholder="Your name" required>
  <input name="email" type="email"
         placeholder="Email address" required>
  <input name="website" type="url"
         placeholder="https://yoursite.com" required>
  <button type="submit">Book Free Audit</button>
</form>

Example 2: Quote Request Form

<form
  action="/request-quote"
  method="POST"
  toolname="requestSEOQuote"
  tooldescription="Request a custom SEO quote.
    Accepts: name (text), email (email), website (URL),
    serviceType (one of: seo, technical-seo, shopify-seo,
    local-seo), monthlyBudget (optional text).
    Returns: quote request confirmation and follow-up
    within 48 hours.">
  <input name="name" type="text" required>
  <input name="email" type="email" required>
  <input name="website" type="url" required>
  <select name="serviceType" required>
    <option value="seo">SEO</option>
    <option value="technical-seo">Technical SEO</option>
    <option value="shopify-seo">Shopify SEO</option>
    <option value="local-seo">Local SEO</option>
  </select>
  <input name="monthlyBudget" type="text"
         placeholder="e.g. $1,000/month (optional)">
  <button type="submit">Get Quote</button>
</form>

Example 3: Search Form

<form
  action="/services"
  method="GET"
  toolname="searchServices"
  tooldescription="Search Salam Experts SEO services.
    Accepts: query (search keyword, text), industry
    (optional: ecommerce, healthcare, logistics, etc.).
    Returns: list of matching service pages.
    Read-only — no data is submitted.">
  <input name="query" type="text"
         placeholder="Search services..." required>
  <input name="industry" type="text"
         placeholder="Industry (optional)">
  <button type="submit">Search</button>
</form>

How the Browser Generates the Schema

When an agent encounters a page with WebMCP-annotated forms, the browser automatically generates a tool schema from your HTML. Here is what it infers from input types:

This means your form’s native HTML is doing a lot of the schema work for you. The better your HTML, the better the auto-generated schema.

Testing Your Implementation

Using the Model Context Tool Inspector

1. Open your site in Chrome 146+ with the WebMCP flag enabled
2. Open DevTools (F12 or right-click → Inspect)
3. Navigate to the Model Context Tool Inspector tab
4. Your registered tools should appear with their names and descriptions
5. Click a tool, fill in test parameters, and hit Execute
6. Verify the form submission fires and returns the expected response

Common Problems and Fixes

Best Practices Summary

• One toolname per form, unique per page, camelCase, verb-first
• Write tooldescription for an agent, not a human — include input formats and return values
• Use correct input types — email, url, tel — to get better auto-generated schemas
• Mark required fields with the required attribute, not just JavaScript validation
• Test with real tool calls via the Inspector before publishing
• Start with your highest-value forms (booking, quote, audit) and expand from there

When to Upgrade to the Imperative API

The Declarative API covers the majority of service site use cases. Move to the Imperative API when you need:

• Dynamic tool behavior based on user state (e.g., different options for logged-in users)
• Fetching live data before returning results (product search, availability checks)
• Multi-step flows that cannot be represented as a single form
• Custom validation logic beyond HTML attribute constraints

See our Imperative API guide for a full walkthrough of those scenarios.

Ready to implement WebMCP?

Need help implementing the Declarative API on your site? We audit your forms, write optimized tool descriptions, and handle testing — so you do not have to.

WebMCP Readiness Audit

Related Reading

• How to Make Your Website Agent-Ready
• WebMCP Imperative API Guide
• WebMCP Security Best Practices
• WebMCP Implementation Services