Spec the `executeTool()` API by domfarolino · Pull Request #226 · webmachinelearning/webmcp

domfarolino · 2026-07-21T19:48:00Z

This PR specifies the executeTool() API on ModelContext.

Closes #57.
Closes #117.
Closes #159.
Closes #160.

This CL introduces the `executeTool()` method to the `ModelContext` interface in the WebMCP specification. This aligns the spec with the C++ implementation in Blink. Key changes: - Adds `executeTool()` and `ExecuteToolOptions` IDL definitions. - Specifies the `executeTool()` algorithm, detailing cross-document tool lookup, origin visibility checks, and asynchronous invocation in the target document`s realm. - Clarifies the execution callback arguments and JSON serialization. - Incorporates `AbortSignal` handling for tool cancellation, dispatching a `toolcancel` event in the target document. - Fires `toolactivated` event in the target document. - Updates IDL member access syntax to use idiomatic Bikeshed style. Small things Fix some things Don't serialize Object argument enforcement Add AbortSignal issue Small things

beaufortfrancois · 2026-07-22T06:09:53Z

 interface ModelContext : EventTarget {
  Promise<undefined> registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});
  Promise<sequence<RegisteredTool>> getTools(optional ModelContextGetToolOptions options = {});
+  Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ExecuteToolOptions options = {});


For consistency with the options naming convention, should we also prepend ModelContext to this dictionary name (e.g., ModelContextExecuteToolOptions)?

Suggested change

Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ExecuteToolOptions options = {});

Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ModelContextExecuteToolOptions options = {});

I now wonder if we should have used ModelContextRegisteredTool as well ;)

beaufortfrancois · 2026-07-22T06:14:45Z

+1. If |invokingDocument| is not [=Document/fully active=], then return [=a promise rejected with=]
+   an "{{InvalidStateError}}" {{DOMException}}.
+
+1. If this's [=surrounding agent=]'s [=agent cluster=]'s [=is origin-keyed=] is false and this's


Suggested change

1. If this's [=surrounding agent=]'s [=agent cluster=]'s [=is origin-keyed=] is false and this's

1. If [=this=]'s [=surrounding agent=]'s [=agent cluster=]'s [=is origin-keyed=] is false and [=this=]'s

This suggestion applies as well to getTools and registerTool.

beaufortfrancois · 2026-07-22T06:26:47Z

+1. Let |expectedTargetOriginURL| be the result of [=URL parser|parsing=] |tool|'s
+   {{RegisteredTool/origin}}.
+
+1. If |expectedTargetOriginURL| is failure, then return [=a promise rejected with=] a


How about using NotSupportedError instead and return a rejected promise in both cases?

expectedTargetOriginURL is a failure

expectedTargetOrigin is opaque

beaufortfrancois · 2026-07-22T06:29:46Z

+1. Let |signal| be |options|'s {{ExecuteToolOptions/signal}} if it [=map/exists=]; otherwise null.
+
+1. If |signal| is not null, then:


Suggested change

1. Let |signal| be |options|'s {{ExecuteToolOptions/signal}} if it [=map/exists=]; otherwise null.

1. If |signal| is not null, then:

1. Let |signal| be |options|'s {{ExecuteToolOptions/signal}}.

1. If |signal| [=map/exists=], then:

beaufortfrancois · 2026-07-22T06:33:41Z

+   1. If |targetDocument|'s [=node navigable=]'s [=navigable/traversable navigable=] is not
+      |invokingDocument|'s [=node navigable=]'s [=navigable/traversable navigable=], then [=queue a
+      global task=] on the [=webmcp task source=] given |invokingDocument|'s [=relevant global
+      object=] to [=reject=] |promise| with an "{{UnknownError}}" {{DOMException}}, and abort these


UnknownError feels weird to me in these cases. Maybe InvalidStateError?

beaufortfrancois · 2026-07-22T07:02:18Z

+  <dt><code><var ignore>document</var>.{{Document/modelContext}}.{{ModelContext/executeTool(tool, inputArguments, options)}}</code></dt>
+  <dd>
+    <p>Executes a tool on the document it was registered on. Returns a promise that resolves to the
+    result of the tool's execution.</p>


Maybe extends that it's a stringified result only for now.

beaufortfrancois · 2026-07-22T07:02:59Z

+The <dfn method for=ModelContext>executeTool(<var>tool</var>, <var>inputArguments</var>,
+<var>options</var>)</dfn> method steps are:
+
+1. Let |invokingDocument| be [=this=]'s [=relevant global object=]'s [=associated


Nit: Shall we use executingDocument?

beaufortfrancois · 2026-07-22T07:06:49Z

 </div>

+<div algorithm>
+The <dfn method for=ModelContext>executeTool(<var>tool</var>, <var>inputArguments</var>,


A JS example of how to execute a tool from a cross-origin iframe may come handy in this spec. See previous comment at #223 (comment)

beaufortfrancois · 2026-07-22T07:09:15Z

+   loop=].
+
+1. Let |inputObject| be the result of [=parse a JSON string to a JavaScript value=] given
+   |inputArguments| and |targetWindow|'s [=relevant realm=]. If <a spec=webidl lt="an exception was thrown">exception was thrown</a>, then


Why not add this webidl bit to <pre class="link-defaults"> at the top of the file?

beaufortfrancois · 2026-07-22T07:13:13Z

 interface ModelContext : EventTarget {
  Promise<undefined> registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});
  Promise<sequence<RegisteredTool>> getTools(optional ModelContextGetToolOptions options = {});
+  Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ExecuteToolOptions options = {});


Out of scope for this PR.

Have we consider moving executeTool from document.modelContext to RegisteredTool interface hinted in https://issues.chromium.org/536063275? FWIW This would match what Puppeteer does: https://pptr.dev/guides/webmcp#executing-tools

beaufortfrancois

We should update README as well: https://github.com/webmachinelearning/webmcp#discovering-and-running-tools

bvandersloot-mozilla · 2026-07-22T13:18:46Z

+
+1. Run the following steps [=in parallel=]:
+
+   1. If |targetDocument|'s [=node navigable=]'s [=navigable/traversable navigable=] is not


Should we check that this document is fully active?

bvandersloot-mozilla · 2026-07-22T13:22:43Z

+
+   1. Let |toolName| be |tool|'s {{RegisteredTool/name}}.
+
+   1. If |targetToolMap|[|toolName|] does not [=map/exist=], then [=queue a global task=] on the


Weird case we could get into here: |targetToolMap|[|toolName|] isn't the same tool as returned from getTools. It may have been modified in between.

Yep, some modifications are OK, others are not. I'll be carrying over some from our implementation before taking this PR out of draft mode.

domfarolino and others added 2 commits July 21, 2026 19:42

Remove spec issue now that #227 is filed

90ccdfa

beaufortfrancois reviewed Jul 22, 2026

View reviewed changes

bvandersloot-mozilla reviewed Jul 22, 2026

View reviewed changes

	Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ExecuteToolOptions options = {});
	Promise<DOMString?> executeTool(RegisteredTool tool, DOMString inputArguments, optional ModelContextExecuteToolOptions options = {});

	1. If this's [=surrounding agent=]'s [=agent cluster=]'s [=is origin-keyed=] is false and this's
	1. If [=this=]'s [=surrounding agent=]'s [=agent cluster=]'s [=is origin-keyed=] is false and [=this=]'s

		1. Let \|signal\| be \|options\|'s {{ExecuteToolOptions/signal}} if it [=map/exists=]; otherwise null.

		1. If \|signal\| is not null, then:


		1. Run the following steps [=in parallel=]:

		1. If \|targetDocument\|'s [=node navigable=]'s [=navigable/traversable navigable=] is not


		1. Let \|toolName\| be \|tool\|'s {{RegisteredTool/name}}.

		1. If \|targetToolMap\|[\|toolName\|] does not [=map/exist=], then [=queue a global task=] on the

Uh oh!

Conversation

domfarolino commented Jul 21, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beaufortfrancois left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

domfarolino commented Jul 21, 2026 •

edited by pr-preview Bot

Loading