The declarative API

The idea: your semantic HTML is already most of the way there

A well-built form already says what it wants. It has fields with names, labels, required markers, and types. The declarative API's premise is that you should not have to rewrite all of that in JavaScript just to make it callable by an agent. You annotate the form you have, and the browser reads its structure to build the tool.

The attributes

The draft introduces attributes on the <form> and on its controls:

• toolname on the form: the tool's name, the equivalent of the imperative tool's name.
• tooldescription on the form: plain language describing what the tool does.
• toolautosubmit on the form: a boolean that lets an agent submit the form without a manual review step. Powerful, and worth a hard look before you set it.
• toolparamdescription on a form control: describes that individual field, feeding the description for its parameter in the generated schema.

A complete example

This is a car-search form. With the annotations, the browser exposes a search-cars tool whose input schema is built from the two fields.

<form toolname="search-cars"
      tooldescription="Perform a car make/model search"
      toolautosubmit>
  <input type="text" name="make"
         toolparamdescription="The vehicle's make (i.e., BMW, Ford)" required>
  <input type="text" name="model"
         toolparamdescription="The vehicle's model (i.e., 330i, F-150)" required>
  <button type="submit">Search</button>
</form>

Example adapted from the WebMCP declarative-API explainer. Current as of 23 July 2026.

How a form becomes a tool

When a form carrying these attributes is added to the page, removed, or has the attributes changed, the browser creates or updates a declarative tool. The name attributes on the form's controls become the property names in the generated input schema, and each field's toolparamdescription and native constraints, like required, inform that property. In the example, an agent sees a search-cars tool that takes a make and a model, both required strings.

Declarative or imperative?

Use the declarative API for standard actions you can express as a form: a search box, a booking request, a contact form, a filter. Use the imperative API when the action needs real logic, a dynamic result, or a shape a form cannot describe. They are designed to coexist; the declarative approach exists so you are not forced into JavaScript for the common cases.

What is still unfinished

• Input-schema synthesis. The exact algorithm for reducing a form and its fields, including constraints like step and min, into a schema is marked to-be-determined.
• The response mechanism. How a declarative tool returns its result to the agent, for example structured data versus full page contents, is under active debate.
• Output schemas. Whether declarative tools should describe their output at all is an open question.
• Auto-submit safety. toolautosubmit removes the human review step, which shifts responsibility for validation and consent entirely onto your side. Treat it as you would an endpoint that acts without confirmation.

Sources

• The WebMCP declarative-API explainer, W3C Web Machine Learning Community Group.
• webmachinelearning/webmcp: specification source and issue tracker.

Reviewed 23 July 2026. Attribute names and synthesis behaviour are current as of this date and are expected to change while WebMCP is pre-standard.