WebMCP Declarative vs. Imperative API: When to Use Each

WebMCP gives developers two distinct ways to expose a website's functionality to AI agents, and most introductory guides mention both without answering the question developers actually have: which one should I use, and when? This post is a decision guide, not a spec summary — by the end, you'll have a clear rule for choosing between them on a feature-by-feature basis.

The two APIs, briefly

The Declarative API lets you annotate existing HTML <form> elements with toolname and tooldescription attributes. The browser reads the form's structure — its inputs, labels, and validation — and automatically translates it into a structured tool schema an agent can call. No JavaScript required for the basic case.

The Imperative API lets you register a JavaScript function directly via navigator.modelContext.registerTool(), with an explicit name, natural-language description, input schema, and an execute() function that runs your custom logic.

Both produce the same end result from an agent's perspective — a discoverable, callable tool with a schema — but they get there very differently, and that difference is what determines which one fits your use case.

When the Declarative API is the right choice

The Declarative API is designed for interactions that are already well-represented by a standard HTML form: a single submission, a fixed set of fields, a predictable result. If your feature looks like this, start here:

• Contact and lead-gen forms. Name, email, message, submit. There's no branching logic, no multi-step state — a form annotation captures the whole interaction.
• Newsletter signups. One field, one action.
• Simple search bars. A text input and a submit button that navigates to a results page.
• Basic filtering. Checkboxes and selects that refine a static list, where the "logic" is really just form submission plus a page reload or a straightforward client-side filter.

The appeal here is real: if your forms already use proper <label> elements, sensible input types, and clear validation messages, you're most of the way to a working WebMCP tool before you write a line of new code. Two extra attributes on the <form> tag, and the browser handles translating your existing structure into a schema an agent can call.

The Declarative API also has a specific technical feature worth knowing: when an agent invokes an annotated form, the browser can focus the form and pre-fill the fields for the user to review. By default, the human still has to click submit — the agent doesn't bypass that step unless you've explicitly enabled autosubmit. That default matters for anything with real-world consequences.

When the Imperative API is the right choice

The Imperative API exists for everything the Declarative API structurally cannot handle: state, sequencing, and logic that lives beyond a single form submission.

• Multi-step workflows. A travel booking that needs to check seat availability before confirming a purchase involves two dependent calls, not one form. That's a job for registerTool(), likely as two separate tools — checkAvailability() and confirmBooking() — called in sequence by the agent.
• Anything backed by application state. A shopping cart where the total needs to update dynamically, an editor where an agent needs to read the current document state before modifying it, a dashboard where filters compound on each other — these require JavaScript that reads and writes real state.
• Conditional logic. If the available actions change depending on context (a logged-in user sees different options than a guest), you need code, not markup.
• Actions with no natural form representation. "Summarize my last three orders" or "compare these two products" don't map to a form field-and-submit pattern at all. They're function calls with typed parameters.

The decision rule

If you can honestly describe the interaction as "a form with fields and a submit button," start with the Declarative API. The moment you find yourself writing "but only if," "and then check," or "depending on what the user already did," that's your signal to move to the Imperative API. Most real applications end up using both — a Declarative form for the newsletter signup in the footer, and Imperative tools for the checkout flow.

A worked example: e-commerce checkout

1. Add to cart — Imperative: addToCart(productId, variantId, quantity).
2. Apply a discount code — Declarative: an annotated form with a code input.
3. Shipping address entry — Declarative: a form with fixed, well-defined fields.
4. Payment and order confirmation — Imperative, with an explicit human confirmation step for the actual charge.

Common mistakes

• Using Imperative for everything "to be safe." This throws away automatic schema generation and semantic-HTML benefits.
• Using Declarative for something that has hidden state. A form depending on hidden session state will produce an inconsistent tool.
• Forgetting that both share the same security model. Both inherit same-origin policy, HTTPS, and CSP directives.

Where to start if you're implementing WebMCP

Audit your site's existing forms first for quick Declarative wins, then identify your top 2–3 multi-step flows for Imperative tools. Scan your site with AgentReady to confirm your tools are discoverable.