WebMCP Declarative API: How to Make Forms AI-Agent Ready Without JavaScript

Why the declarative API changes everything for non-JavaScript sites

Most WebMCP tutorials start with JavaScript. They show you how to call navigator.modelContext.registerTool(), pass in a schema object, and wire up an async handler function.

That is great if you are a React developer with a custom build pipeline. But what about the WordPress site owner who just wants AI agents to be able to use their contact form? What about the small business with a booking page built in plain HTML?

The WebMCP declarative API solves exactly this problem. You add three HTML attributes to an existing form, and the browser automatically registers it as a callable tool for AI agents. No JavaScript. No build step. No npm packages. Just HTML.

This guide walks you through everything you need to know about the declarative approach, from the basic syntax to advanced patterns that handle real production scenarios. By the end, you will have working WebMCP tool registrations on your forms without writing a single line of JavaScript.

How the WebMCP declarative form API works

The three attributes that do everything

The entire declarative API comes down to three HTML attributes you add to a <form> element.

toolname gives your tool a machine-readable identifier. AI agents use this name to reference and call your tool. Keep it lowercase with underscores, like search_products or book_appointment.

tooldescription tells AI agents what your tool does and when they should use it. This is the most important attribute because agents read this description to decide whether your tool matches what the user asked for. Write it like you are explaining the form to a helpful assistant.

toolautosubmit controls whether the form submits automatically when an agent fills it, or whether the user needs to confirm first. Set it to "true" only for safe, read-only operations like search. Leave it off for anything that creates data or costs money.

Here is a complete example:

<form toolname="search_products"
      tooldescription="Search for products by keyword and category. Returns matching products with prices."
      toolautosubmit="true"
      method="GET"
      action="/search">
  <input name="q" type="text" placeholder="Search..." required />
  <select name="category">
    <option value="">All Categories</option>
    <option value="electronics">Electronics</option>
    <option value="books">Books</option>
  </select>
  <button type="submit">Search</button>
</form>

When Chrome 146 loads this page, the browser reads those attributes and automatically registers a WebMCP tool. An AI agent visiting the page sees a tool called search_products that accepts a query string and an optional category.

What the browser does behind the scenes

The browser does more work than you might expect when it encounters those attributes.

First, it reads every form field and generates a JSON Schema for the tool's input parameters. The field name attributes become parameter names. The type attributes determine the JSON Schema types. And HTML validation attributes like required, min, max, and pattern become schema constraints.

Second, the browser registers the tool with navigator.modelContext using the name and description you provided. From that point on, any AI agent that queries navigator.modelContext.tools() will see your form as a callable tool.

Third, when an agent actually calls the tool, the browser handles the entire invocation flow. It fills the form fields with the agent's parameter values, optionally shows the user what is about to be submitted, and then submits the form through its normal action URL.

You do not need to understand any of this to use the declarative API. But knowing what happens under the hood helps you write better tool descriptions and debug issues when they come up.

The field type mapping reference

Every HTML input type maps to a specific JSON Schema type. The browser handles this conversion automatically, but you should know the mapping so you can choose the right input types for your tools.

HTML Input Type	JSON Schema Type	Notes
text	string	Most common. Use for any free-text input.
number	number	Respects min and max attributes as constraints.
email	string (format: email)	Agents will provide properly formatted email addresses.
date	string (format: date)	Returns ISO 8601 date format (YYYY-MM-DD).
checkbox	boolean	True when checked, false when unchecked.
select	string (enum)	The option values become the allowed enum values.
textarea	string	Use maxlength to set a character limit.
hidden	string	Passed silently. Agents do not see hidden fields as parameters.

The required attribute on any field makes that parameter required in the JSON Schema. Fields without required become optional parameters that agents can choose to fill or skip.

How agent invocation works step by step

The confirmation flow

When an AI agent calls a declarative form tool, the browser runs a specific sequence.

The browser scrolls the form into view and highlights it visually. Then it fills each field with the values the agent provided. The user sees the pre-filled form and gets a confirmation prompt asking whether to allow the submission.

If the user approves, the form submits normally through its action URL with its method (GET or POST). The response goes back to the agent through the browser.

If the user declines, the agent receives an error indicating the user rejected the tool call. The agent can then explain to the user what it was trying to do and ask for guidance.

This confirmation step is the default behavior, and it exists for a good reason. You do not want an AI agent silently submitting a payment form or creating a support ticket without the user knowing.

Auto-submit for safe operations

For read-only operations where there is no risk, you can skip the confirmation step by adding toolautosubmit="true" to the form.

Search forms are the obvious candidate. An agent searching for products or filtering a catalog is not changing any data. Auto-submit makes these interactions feel instant instead of requiring a click.

Do not use auto-submit for forms that create records, send emails, make purchases, or modify any data. The security model of WebMCP relies on user consent for anything that has side effects.

Detecting agent submissions with the agentInvoked flag

When a form submission is triggered by an AI agent, the SubmitEvent carries an agentInvoked property set to true. This lets you differentiate between human and agent submissions on your backend.

document.querySelector('form').addEventListener('submit', (e) => {
  if (e.agentInvoked) {
    analytics.track('agent_form_submit', {
      tool: e.target.getAttribute('toolname')
    });
  }
});

Tracking agent submissions separately is valuable for understanding how AI agents interact with your site. Over time, this data will show you which forms agents use most and which tool descriptions need improvement.

Real-world examples that you can copy

Hotel booking search

Travel sites have some of the most complex search forms on the web. Here is how to make a hotel search agent-friendly:

<form toolname="search_hotels"
      tooldescription="Search available hotels by destination city, check-in and check-out dates, number of guests, and maximum nightly price. Returns matching hotels with availability and rates."
      toolautosubmit="true">
  <input name="destination" type="text" required
         placeholder="City or hotel name" />
  <input name="checkin" type="date" required />
  <input name="checkout" type="date" required />
  <input name="guests" type="number" min="1" max="10" value="2" />
  <input name="maxPrice" type="number" min="0"
         placeholder="Max price per night" />
  <button type="submit">Search Hotels</button>
</form>

Notice how the tooldescription is specific about what the tool returns. An agent reading this description knows it will get hotel availability and rates back, not just a list of hotel names. That specificity helps agents decide when to use your tool over a competitor's.

Customer support ticket

Support forms are a great candidate for the declarative API because they are simple, structured, and benefit from agent assistance. A user might tell their AI assistant "file a support ticket about my billing issue" and the agent can fill out the form for them.

<form toolname="create_ticket"
      tooldescription="Create a customer support ticket. Requires a subject line, priority level (low, medium, or high), and a description of the issue. The ticket will be routed to the appropriate support team."
      method="POST"
      action="/api/tickets">
  <input name="subject" type="text" required maxlength="200" />
  <select name="priority" required>
    <option value="low">Low</option>
    <option value="medium">Medium</option>
    <option value="high">High</option>
  </select>
  <textarea name="description" required maxlength="5000"></textarea>
  <button type="submit">Submit Ticket</button>
</form>

This form does not have toolautosubmit because creating a ticket has side effects. The user will see the pre-filled form and confirm before it submits. That is the right behavior for any form that writes data.

Newsletter signup

Even something as simple as a newsletter form benefits from the declarative API:

<form toolname="subscribe_newsletter"
      tooldescription="Subscribe to the weekly newsletter. Requires an email address and optionally a first name."
      method="POST"
      action="/api/subscribe">
  <input name="email" type="email" required />
  <input name="firstName" type="text" placeholder="First name" />
  <button type="submit">Subscribe</button>
</form>

When a user tells their AI agent "sign me up for their newsletter," the agent finds this tool, fills in the email, and shows the user the form for confirmation. The entire interaction takes seconds.

Writing tool descriptions that agents actually understand

The tooldescription attribute is the single most important piece of your declarative WebMCP implementation. AI agents use it to decide whether your tool matches the user's intent.

A bad description like "Submit form" tells the agent nothing. It will never match any user request because it does not describe what the form does or what it returns.

A good description has three parts. First, what the tool does in plain language. Second, what inputs it needs. Third, what the user gets back.

Compare these two descriptions for the same search form:

Bad: "Search products"

Good: "Search the product catalog by keyword, with optional category and price filters. Returns matching products with names, prices, ratings, and availability status."

The second description tells an agent exactly when to use the tool, what parameters to send, and what kind of data to expect in the response. Write every description as if you are explaining the form to a new employee who has never seen your site before.

When to choose declarative vs imperative WebMCP

The declarative API is not the right choice for everything. Here is how to decide.

Use the declarative API when you have an existing HTML form that already works. Search forms, contact forms, booking forms, signup forms, filter forms. If users fill it out and submit it today, you can make it agent-ready with three attributes.

Use the imperative JavaScript API when you need multi-step workflows, when the tool does not have a corresponding form in the UI, when you need to transform data before returning it, or when your tool requires complex business logic in the handler.

Many sites will use both. Your marketing pages might use declarative forms for search and contact. Your product dashboard might use imperative tools for data queries and configuration changes. They work alongside each other without conflict.

If you are not sure which to start with, start declarative. You can always add imperative tools later. But getting your existing forms agent-ready today takes minutes, and the benefits start immediately.

Common mistakes and how to avoid them

After seeing dozens of declarative WebMCP implementations, a few patterns of mistakes keep showing up.

The most common is forgetting the tooldescription attribute entirely. The form will still register as a tool, but without a description, no agent will ever call it because they cannot determine what it does.

The second mistake is using auto-submit on forms that have side effects. If your form creates a record, sends an email, or charges money, leave toolautosubmit off. The confirmation step exists to protect users.

The third is vague field names. A field named f1 or data produces a schema parameter that agents cannot interpret. Use descriptive names like destination, checkInDate, or maxPrice. These names become part of the tool schema that agents read.

The fourth is not testing with an actual agent. Open Chrome Canary, load your page, and run navigator.modelContext.tools() in the console. Verify your tool appears with the right name, description, and parameter schema. Then call it with navigator.modelContext.callTool() and confirm the form submits correctly.

What this means for your website

The declarative form API is the fastest path to making any website AI-agent ready. You do not need a JavaScript framework. You do not need a build pipeline. You do not need to change your backend.

If you have HTML forms on your site today, you can make them callable by AI agents in the time it takes to add three attributes. And once Chrome 146 moves to stable release, every Chrome user's AI assistant will be able to discover and use those tools.

Start with your search form. Add the three attributes. Test it in Chrome Canary. Then move to your contact form, your booking form, your signup form. Each one you convert is another interaction that AI agents can handle on behalf of your users.

Do I need JavaScript at all for WebMCP?

No. The declarative API registers tools using only HTML attributes on form elements. The browser handles schema generation, tool registration, and form submission automatically. JavaScript is only needed if you want imperative tools with custom handler logic or multi-step workflows.

What browsers support the declarative form API?

Chrome 146 Canary supports it natively behind a feature flag. Microsoft Edge will follow since Microsoft co-authors the WebMCP spec. For other browsers, the WebMCP polyfill adds support. The declarative attributes are ignored by browsers that do not support them, so nothing breaks for regular users.

Can I use declarative and imperative WebMCP together?

Yes. Declarative form tools and imperative JavaScript tools coexist on the same page without conflict. Many sites use declarative tools for simple form interactions and imperative tools for complex operations. An AI agent sees all registered tools regardless of how they were created.

Is the declarative API secure?

Yes. By default, form submissions triggered by AI agents require user confirmation before executing. The user sees the pre-filled form and must approve it. Auto-submit is opt-in and should only be used for read-only operations. The browser's same-origin policy and CSP rules still apply to all form submissions.

How do I track which forms are being used by AI agents?

Listen for the submit event on your forms and check the agentInvoked property on the SubmitEvent. When it is true, the submission was triggered by an AI agent. Send this data to your analytics platform to track agent usage separately from human submissions.