webmcp-declarative-forms

WebMCP Declarative Forms

Before writing code

Fetch live docs:

1. Fetch https://webmachinelearning.github.io/webmcp/ for the declarative form attribute specification
2. Web-search webmcp declarative form toolname tooldescription HTML attributes for attribute syntax and behavior
3. Web-search site:developer.chrome.com webmcp declarative forms for Chrome implementation details
4. Web-search webmcp SubmitEvent agentInvoked for the agent submission event API

Conceptual Architecture

What Declarative Forms Are

The Declarative API lets developers make existing HTML forms agent-ready by adding attributes — no JavaScript required for basic cases. Chrome auto-extracts form tools and exposes them to agents.

HTML Attributes

Attribute	Applied To	Purpose
toolname	<form>	Unique tool name (becomes the tool's name)
tooldescription	<form>	Natural-language description for the agent
Standard name, type	<input>, <select>, <textarea>	Mapped to JSON Schema properties automatically

How It Works

1. Developer adds toolname and tooldescription to a <form> element
2. Browser auto-extracts form fields into a JSON Schema (input names become properties, types are inferred)
3. The form becomes a registered tool visible to agents
4. When an agent invokes the tool, the browser fills the form fields and submits
5. A SubmitEvent fires with agentInvoked property set to true
6. The site can detect agent submissions and handle them accordingly

Basic Example

<form toolname="searchProducts" tooldescription="Search the product catalog by keyword and price range">
  <label>
    Search: <input name="query" type="text" required />
  </label>
  <label>
    Max Price: <input name="maxPrice" type="number" min="0" />
  </label>
  <label>
    Category:
    <select name="category">
      <option value="all">All</option>
      <option value="electronics">Electronics</option>
      <option value="clothing">Clothing</option>
    </select>
  </label>
  <button type="submit">Search</button>
</form>

Detecting Agent Submissions

form.addEventListener("submit", (event) => {
  if (event.agentInvoked) {
    // Agent submitted this form — handle programmatically
    event.preventDefault();
    const data = new FormData(form);
    handleAgentSearch(Object.fromEntries(data));
  }
  // Otherwise, normal user submission
});

Schema Inference

The browser infers JSON Schema from form fields:

• <input type="text"> → { type: "string" }
• <input type="number"> → { type: "number" }
• <input type="email"> → { type: "string", format: "email" }
• <input required> → Added to required array
• <select> → { type: "string", enum: [...options] }
• <input type="checkbox"> → { type: "boolean" }

When to Use Declarative vs Imperative

Scenario	Recommended
Simple search or filter forms	Declarative
Legacy server-rendered pages	Declarative
Complex multi-step interactions	Imperative
Dynamic SPA with state management	Imperative
Quick agent enablement of existing forms	Declarative
Tools that need user confirmation dialogs	Imperative
Both simple and complex on one page	Both

Combining Both APIs

A page can use both declarative forms and imperative tools simultaneously:

• Simple forms get toolname/tooldescription attributes
• Complex interactions use navigator.modelContext.registerTool()
• Both appear in the agent's tool list together

Best Practices

• Use descriptive toolname values that clearly identify the action
• Write tooldescription for the agent, not the user — explain what the form does and what it returns
• Ensure form field name attributes are semantic (query not q, maxPrice not mp)
• Handle agentInvoked submissions gracefully — return structured data, not HTML redirects
• Test with agents to verify the auto-inferred schema matches expectations
• Add required attributes to mandatory fields so the schema reflects them

Fetch the specification for exact attribute names, SubmitEvent properties, and schema inference rules before implementing.