Declarative API Fit for JS-Driven Forms

[dgp1130]

👋 Hi, Angular maintainer here. I've been exploring a framework-level integration with the WebMCP spec in the Chrome early access program and we had some thoughts on the applicability of the declarative API and shared them with Chrome who wanted us to share more broadly.

TL;DR: Our current view is that the declarative forms API is probably not a great fit for Angular (and potentially JS frameworks / JS-driven forms more broadly). Such systems should consider using registerTool directly based on their raw JS form data model instead.

Driving forms systems from models in JS means the rendered <form> / <input> elements are potentially just one consumer of a more expressive form model known to the framework. The most straightforward example I can think of is adding a list of users. In Angular using our newest signal forms implementation, this looks like (demo):

import { Component, signal } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { applyEach, form, FormField, required } from '@angular/forms/signals';

interface User {
  name: string;
}

@Component({
  selector: 'app-root',
  template: `
    <form (submit)="submit($event)">
      <ul>
        @for (user of userForm.users; track user.name()) {
          <li><input type="text" [formField]="user.name" /></li>
        }
      </ul>

      @if (userForm().invalid() && userForm().touched()) {
        <ul>
          @for (error of userForm().errorSummary(); track error) {
            <li>{{ error.message }}</li>
          }
        </ul>
      }

      <button type="button" (click)="addUser()">Add user</button>
      <button type="submit">Submit</button>
    </form>
  `,
  imports: [FormField],
})
export class App {
  protected readonly model = signal({ users: [{ name: '' }] as User[] });
  protected readonly userForm = form(this.model, (f) => {
    applyEach(f.users, (user) => {
      required(user.name, { message: 'Name is required.' });
    });
  });

  protected addUser(): void {
    this.model.update((m) => ({ ...m, users: [...m.users, { name: '' }] }));
  }

  protected submit(evt: SubmitEvent): void {
    evt.preventDefault();

    console.log(
      `Submitted ${this.model()
        .users.map((u) => u.name)
        .join(', ')}!`
    );
  }
}

bootstrapApplication(App);

In this example, the user is allowed to submit any number of user objects, each of which has a required name. At any given time, the <form> element has a fixed number of <input> elements, but there are other controls on the page to add more users and generate more <input> fields dynamically, which is not visible to the WebMCP agent. When it looks at this form, it just sees a single input with a single user name, and has no visibility into the fact that multiple users are allowed. If we update the <input name="..."> attribute for each field, the agent is effectively working with:

{
  "name": "add-users",
  "description": "Adds users to the database",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name0": {"type": "string"},
      "name1": {"type": "string"}
    },
    "required": ["name0", "name1"]
  }
}

When the user asks it to submit 5 users, the agent's only path here is to scrape the page to find the "Add user" button, click it up to 5 times, notice that the generated form tool has updated to support name0 - name4, and then invoke that tool with all 5 inputs. This is less efficient for the agent (more tokens consumed, more interactions), the page (need to render intermediary steps), and the user (slower response, might interrupt other actions on the page).

Going one step further, if the user then changes their mind and asks to submit 3 users, the agent is seeing a form with 5 required fields, yet they're only required because multiple users have been added. The agent needs to figure out it can click a "Remove user" button to delete that field, and reduce down to only 3 required users. The schema is actively misleading the agent and the agent needs to understand that it can effectively "mutate" that schema by interacting with the rest of the page. That's not typically how "schemas" work.

While the <form> and <input> tags rendered to the page don't know there's more to the form, the core data model they are driven by potentially does. In the above example, we have {users: User[]} as the foundational data model. And through evaluating the applyEach and required schemas, we actually know this relationship at runtime.

The actual MCP schema this form should generate is something like:

{
  "name": "add-users",
  "description": "Adds users to the database",
  "inputSchema": {
    "type": "object",
    "properties": {
      "users": {
        "type": "object",
        "array": true,
        "properties": {
          "name": {"type": "string"}
        },
        "required": ["name"]
      }
    }
  }
}

This is roughly a reflection of the actual {users: User[]} form model, not the rendered <form> and <input> elements.

This mental model can also support use cases which don't strictly use <input> elements to capture user data. Developers might create custom controls for inputting complex data, and since they rely on the framework form system for managing and rendering that content, they don't strictly need <input> elements to achieve that goal. Any such field would be invisible to the AI using an automatically generated WebMCP tool.

While I'm discussing Angular as the thing I'm most concerned with, I think all of these points are potentially relevant to 1) other JS frameworks and 2) any JS-driven form system. Any codebase which uses a JS object as the source of truth for its form system potentially has much more insight into the foundational data model at play than scraping <form> and <input> tags would ever be able to give you. Certainly it depends on the DX of any particular system (ex. if that information is stored in TypeScript and erased at runtime, it might be hard to action on), but I'd be curious to know how maintainers of other frameworks / libraries feel about this.

We're ultimately still exploring this space ourselves, but our current thinking is that it might be better for Angular to intentionally disable / block the WebMCP declarative forms API, and then instead create our own invocation of navigator.modelContext.registerTool based on the raw form data model. We believe this could result in a more comprehensive and usable tool definition for the same amount of effort from developers.

Note that I'm not trying to argue the declarative form API shouldn't exist or that no one should use it. If a form is primarily driven by its rendered HTML and not a JS data model, or if we want to provide some out-of-the-box or minimal effort support for the millions of existing <form> tags out there, this very well could be an excellent fit. I just wanted to share our current thinking that this might not be a great fit for JS-driven forms specifically.

/cc @arick @leonsenft @kirjs

[chrishtr]

Hi, thanks for this example.

As far as I can tell, the feature gap here is "dynamic forms conditionally based on user interaction are not supported natively in HTML". I don't see anything specific to use of Angular or other frameworks. If HTML were extended to support such situations, then WebMCP would naturally benefit.

Therefore, pure use of the declarative version of WebMCP may be limited in some cases to what is expressible via declarative HTML forms, but the solution in my view should be to look at extending HTML forms.

In the specific case of the "submit a list of user names that can be of arbitrary length", I think this could be modeled in WebMCP as multiple tool calls:

• An imperative tool (called add-users, like you suggested) that adds users to the form but does not submit it.
• A declarative tool (called submit-users) that submits the form (including other non-repeated fields which may be present in the form).

So if the prompt is "please submit foo and bar as new users", the agent would call add-users([foo, bar]) and then call submit-users, at which time focus would come back to the website and it'd ask the user to confirm if this looks good and should be submitted. This UI flow gives the user an opportunity to:

• Know what is going on on the website
• Check that the users are typed correctly
• Realize maybe they forgot about user "baz", which they can quickly fix by clicking "add user", typing in "baz" and then submitting

It also benefits the website developer because HTML forms are built in and wouldn't need to be partially reinvented. And it benefits browsers and other agents because forms have well-defined semantics that can be inspected.

[domfarolino]

Realize maybe they forgot about user "baz", which they can quickly fix by clicking "add user", typing in "baz" and then submitting

In your example, what is the submit-users declarative tool doing, if form-filling is handled by the imperative tool, and the form has no toolautosubmit attribute? Is it just bringing the user's attention to the form to submit? (I feel like the imperative tool could just do that after it's done filling it out).

Also, if we want a "submit-only (don't fill the form out)" kind of declarative tool, we'd need to make JUST the submit button a tool, instead of the whole form. If the whole form was a tool, we'd synthesize a full input schema for the inputs that the imperative tool already filled out, and the agent would overwrite their values.

[dgp1130]

@chrishtr, I agree there's nothing intrinsically coupled to Angular here, I mainly use it as context and motivation, but any dynamic form has the issues I've described. I do like the mental model of dynamic forms for framing this problem.

I agree splitting off into separate tools of add-users and submit-users is one potential solution. I share @domfarolino's concern that submit-users doesn't do much if add-users is doing most of the work. I also personally feel like splitting each dynamic action into a separate tool doesn't scale particularly well for complex forms with many such interwoven tools. It's not intrinsically clear to the AI that add-users and submit-users are operating on the same form and I suspect the AI would work better with a single tool which supports all permutations of the form, but that's a just a hypothesis.

It also benefits the website developer because HTML forms are built in and wouldn't need to be partially reinvented. And it benefits browsers and other agents because forms have well-defined semantics that can be inspected.

Can you expand on what you're envisioning here? My main point is that this use case is not expressible via the declarative API, I'm not sure how you'd express add-users and submit-users as distinct forms within this API structure?

I can maybe see some nested form structure where the "add user" button is a submit button for a mini-form which alters the <input> elements / schema of the other form, but I don't typically see web developers use forms like that and feel like it might actually fight against the patterns they're using. It also requires a certain amount of product knowledge for the AI to relate that "I want to add X users" -> "Therefore I need to submit the add-users form" -> "Now I can fill in the X users and submit the real form".

I think my deeper point here is that the declarative API design is intrinsically limited and can't express those use cases. Whether you go with my suggestion for an array parameter, or your suggestion for a separate add-users tool, the page needs to manually register and implement those tools. It's not expressible in the declarative form API and naturally limits its inherent usefulness.

[chrishtr]

In your example, what is the submit-users declarative tool doing, if form-filling is handled by the imperative tool, and the form has no toolautosubmit attribute? Is it just bringing the user's attention to the form to submit? (I feel like the imperative tool could just do that after it's done filling it out).

Yes it's to bring it to their attention and let them fix and submit. add-users can't necessarily be used directly, because it's possible the agent will add-users some more before the user is ready to submit.

If the whole form was a tool, we'd synthesize a full input schema for the inputs that the imperative tool already filled out, and the agent would overwrite their values.

Good point. This raises the question: should the agent be expected to understand that it has already filled out some of the form via other tool calls? Similarly it is useful for the user for there to be a way for the user and agent to collaborate on the form together. For example, consider this situation: the user decides to start filling it out, does some easy parts, and then decides to delegate the rest to the agent. In this case the agent needs to now not to overwrite what the user has already done.

[chrishtr]

Can you expand on what you're envisioning here? My main point is that this use case is not expressible via the declarative API, I'm not sure how you'd express add-users and submit-users as distinct forms within this API structure?

Suppose we extended HTML forms to allow a repeated attribute to <input>, with the meaning that "this field can be repeated as many times as desired by the user". The browser could then render this as an input field with a + button next to it that adds a new one, which if clicked would automatically add the new <input> into the DOM and render accordingly. Then if a developer put a WebMCP tool on this form, the agent would automatically know that this input is a repeated field and it can directly instruct the browser to add the inputs and fill them in in one go (because the agent can talk to the browser via a direct mechanism).

I think my deeper point here is that the declarative API design is intrinsically limited and can't express those use cases. Whether you go with my suggestion for an array parameter, or your suggestion for a separate add-users tool, the page needs to manually register and implement those tools. It's not expressible in the declarative form API and naturally limits its inherent usefulness.

I agree with you that HTML forms' built-in behaviors are limited to the UX design patterns built into them in the specs, and in that sense declarative WebMCP is similarly limited.

[dgp1130]

I see. I can certainly envision a future where forms APIs are expanded and potentially more expressive for WebMCP. I'm not sure how practically achievable that is in this context but I'll defer to others more familiar with web standards as to whether this is truly a viable solution from a process perspective.

[domfarolino]

Then if a developer put a WebMCP tool on this form, the agent would automatically know that this input is a repeated field and it can directly instruct the browser to add the inputs and fill them in in one go (because the agent can talk to the browser via a direct mechanism).

A repeated attribute solves the problem when it's narrowly-scoped to inputs, because the agent could then know ahead of time, the values for input elements that didn't exist at form/tool registration time. So if the user says "Add Foo, Bar, and Baz to the database", the agent can handle a form that has a single input element, because it knows the form has the potential to expand into to many inputs, and it can invoke that expansion as needed.

But I imagine the ways in which "dynamic" forms mutate over time is not limited to repeated input elements. Maybe @dgp1130 knows more, but I feel like I've seen complex forms whose structure alters significantly as you fill it out. Supporting those would need a more general solution, but maybe they're just edge cases?

(The "more general solution" would be some HTML way to hint to the platform the possible expansions, instead of keeping all of that logic in JavaScript. That way the form tool's inputSchema could account for the ways it could expand, so the agent can know up-front what data it needs to provide to account for the form expansions. Alternatively, we could have a way for a form that expands dynamically, to call "back into the agent" to request more values for the new parts of the form that have been revealed. I don't like this though, since MCP tools aren't multi-turn; they're one-shot by design).

[dgp1130]

An array of a repeated field is certainly one example, but it is by no means exhaustive. We can go even just one step further by having this be a list of "new users", of which each user requires a first name and last name. In this case, there's two repeated fields but they are individually associated with a singular user (it's conceptually not {firstNames: string[], lastNames: string[]}, it's {users: Array<{firstName: string, lastName: string}>}).

I'm not expert, but there's plenty of other examples of dynamic forms. A radio button might let you choose between different options (login as new user or existing user) and then populate the rest of the form based on that decision with potentially completely disparate options. A checkbox could decide whether or not to ask for additional information (Do you have a car? If yes, what is its make/model/year?). I'm not sure even Angular's design could handle arbitrary conditionals in an automated fashion without some amount of developer involvement, but I think it's this level of complexity we would be taking on if we tried to down the route of updating existing form APIs to cover more use cases.

I think my broader point is that the rendered DOM is just one particular "view" of a higher-level abstraction around the core form data model. That model could be quite large, include arrays, nested objects, enums, and more. Only some parts of it may be relevant to a particular user at any given time. Those are the parts which are rendered to the document, but there could be any number of additional fields not currently visible to the user. Just because a field happens to be invisible right now to the user right now doesn't mean it needs to necessarily be invisible to the AI. So this is where I think it is likely a better abstraction to derive a WebMCP tool from that underlying form model, being a more authoritative representation of the desired data, rather than attempting to extract this data from the rendered <form> and <input> elements which represent only one particular view of that data model.

[jyasskin]

This seems related to the autofill improvements described at https://github.com/WICG/autofill-event. It would be great to design a unified system that serves both kinds of needs. cc/ @yoavweiss

[7mehul]

One thing that helps with this is offloading the policy resolution entirely. Maango checks what a domain allows for AI (training, scraping, inference) across all major standards and returns it structured. Takes 5 minutes to integrate.