API Quick Reference (IDL, Attributes, Events, Errors)

“Tool execution errors are not exposed to the web.”

— WebMCP specification, §3 Supporting concepts¹

This is the page I keep open while I write tool code, and I hope it earns the same place on your second screen. It collects the whole WebMCP surface in one spot: the WebIDL, every dictionary member, the three events, the Permissions Policy feature and the exceptions each method can reject with. It doesn’t teach (the chapters do that), so each section points back to the chapter that explains the idea.

Everything here was checked against the WebMCP Draft Community Group Report dated 27 October 2026, read on 2 November 2026.² The good news first: its IDL is the same, line for line, as the 15 October draft the first edition of this book was written against. What changed in those twelve days is prose (a written-up section on the same-origin policy, new text on agent-ecosystem risks, a fourth editor), not API. If you wrote code against the October shape, it still matches the spec.

Every behaviour marked “tested” was observed in Chromium 156.0.8078.4 with the WebMCPTesting feature switched on, which is what chrome://flags/#enable-webmcp-testing turns on in Chrome.³ Chrome 156 has been the stable channel since 20 October 2026, and Chrome 157 is due on 3 November 2026.⁴ The probes behind the tables live in the book’s demos repository, in appendices/a-api-reference/, and I re-ran all 25 of them on 2 November 2026: they all pass. Where Chromium and the draft disagree, the tables show both columns.

A.1 The interface at a glance

Listing A.1 is the specification’s IDL index, unabridged. It’s short, and that tells you something: the whole imperative API is three methods, three events and seven dictionaries.

partial interface Document {  [SecureContext, SameObject] readonly attribute ModelContext modelContext;};[Exposed=Window, SecureContext]interface ModelContext : EventTarget {  Promise<undefined> registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});  Promise<sequence<RegisteredTool>> getTools(optional ModelContextGetToolOptions options = {});  Promise<DOMString> executeTool(RegisteredTool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {});  attribute EventHandler ontoolchange;  attribute EventHandler ontoolactivated;  attribute EventHandler ontoolcancel;};dictionary ModelContextTool {  required DOMString name;  // Because `title` is for display in possibly native UIs, this must be a `USVString`.  // See https://w3ctag.github.io/design-principles/#idl-string-types.  USVString title;  required DOMString description;  object inputSchema;  required ToolExecuteCallback execute;  ToolAnnotations annotations;};dictionary ToolAnnotations {  boolean readOnlyHint = false;  boolean untrustedContentHint = false;  boolean consequentialHint = false;  boolean debugging = false;};dictionary ToolExecuteCallbackOptions {  required AbortSignal signal;};callback ToolExecuteCallback = Promise<any> (object inputObject, ToolExecuteCallbackOptions options);dictionary ModelContextRegisterToolOptions {  sequence<USVString> exposedTo;  AbortSignal signal;};dictionary ModelContextGetToolOptions {  sequence<USVString> fromOrigins;};dictionary ModelContextExecuteToolOptions {  AbortSignal signal;};dictionary RegisteredTool {  required DOMString name;  // `title` can be exposed as a `DOMString` since it was taken in by a  // `USVString`, meaning all unmatched surrogate processing has already been  // done, and there's no need to do it again on tool exposure.  DOMString title;  required DOMString description;  object inputSchema;  required Window window;  required USVString origin;  ToolAnnotations annotations;};[Exposed=Window, SecureContext]interface ToolActivatedEvent : Event {  constructor(DOMString type, optional ToolActivatedEventInit eventInitDict = {});  readonly attribute DOMString toolName;};dictionary ToolActivatedEventInit : EventInit {  DOMString toolName = "";};[Exposed=Window, SecureContext]interface ToolCancelEvent : Event {  constructor(DOMString type, optional ToolCancelEventInit eventInitDict = {});  readonly attribute DOMString toolName;};dictionary ToolCancelEventInit : EventInit {  DOMString toolName = "";};

Three things in Listing A.1 matter more than the rest:

• The entry point is document.modelContext. It hangs off Document, not Navigator, and it only exists in secure contexts.⁵ There is one ModelContext per document, so every iframe has its own. (Tested: 'modelContext' in document is true and 'modelContext' in navigator is false in Chromium 156.) Appendix D covers the move from navigator.
• There is no unregisterTool(). You unregister by aborting the AbortSignal you passed to registerTool().⁶
• Results are strings. executeTool() resolves with a DOMString, whatever the tool returned.⁷ How that string is produced is the one place where Chrome and the draft still disagree (Section A.4).

A.2 registerTool(tool, options)

await document.modelContext.registerTool(tool, { signal, exposedTo });

Registers one tool on the current document and returns a Promise<undefined>. Tested, it resolves with undefined in Chromium 156 too.⁶ Chapter 5 introduces it, and Chapter 6 covers annotations and the execute callback’s signal.

Table A.1 — ModelContextTool members

The rules in Table A.1 are the draft’s registration steps.⁶ I tested all of them in Chromium 156, and the browser agrees with the draft. A name with a space, a 129-character name, an empty description and a duplicate name each reject with InvalidStateError. A missing execute, a circular inputSchema and a toJSON() that returns undefined each reject with TypeError.

Table A.2 — ToolAnnotations members (all boolean, default false)

The wording in Table A.2 paraphrases the draft’s dictionary descriptions.⁹ The draft carries annotations through to getTools(), but it doesn’t say what an agent must do with them. That is the agent’s policy (Chapter 6). Since 20 October 2026 the security section also says it plainly: a malicious site can omit or misrepresent the hints, and keeping an agent safe from that is the agent’s job, not something the specification can enforce.¹⁰ Two open pull requests would add to this table, see Section A.9.

Table A.3 — ModelContextRegisterToolOptions members

Both members come from the draft’s registration steps.⁶¹¹ Tested in Chromium 156: an already-aborted signal rejects with AbortError (the default abort reason), and exposedTo: ['http://example.com'] rejects with SecurityError: Only secure origins are allowed in the exposedTo list. Please note: unregistering a tool doesn’t cancel calls already in flight. Chrome’s documentation dates that behaviour to Chrome 153,⁸ and Chapter 6 shows how to live with it.

A.3 getTools(options) and RegisteredTool

const tools = await document.modelContext.getTools({ fromOrigins });

Returns the tools an in-page agent may see. To be precise: the tools of every document in the tab’s frame tree that is allowed the tools feature, is same-origin with the caller or listed in fromOrigins, and has exposed the tool to the caller’s origin. The list is sorted by name.¹² The browser’s own agent doesn’t use this method (it has an internal mechanism).⁷ Chapter 7 builds an in-page agent on it.

Table A.4 — RegisteredTool members, as getTools() returns them

fromOrigins follows the same rule as exposedTo: every entry must be a URL with a potentially trustworthy origin, or getTools() rejects with SecurityError.¹³ Tested: an insecure origin and a string that isn’t a URL both reject that way in Chromium 156.

Still in fluxwhat an empty title looks like

The draft fills a missing title with the empty string, and an inline issue in the getTools() steps asks whether to leave the member out instead.¹² Issue #224, “Tool title and inputSchema: what to expose when not provided?”, opened on 21 July 2026, was still open on 2 November 2026.¹⁴ Test for a falsy title rather than for undefined or "" specifically.

A.4 executeTool(tool, inputObject, options)

const text = await document.modelContext.executeTool(tool, { query: 'tent' }, { signal });

Runs a tool on the document that registered it and resolves with the result as a string. tool is a RegisteredTool, usually one that getTools() returned. The browser looks the tool up again by name in the document behind tool.window and checks that document’s origin against tool.origin, so a hand-made dictionary can’t reach a tool it couldn’t see. A missing inputObject becomes {}. The options take one member, signal: aborting it rejects the promise with the signal’s reason and cancels the execution in the target document.⁷ Chrome’s documentation adds one case the draft doesn’t spell out: when the tool triggers a navigation, the call returns null instead of a result.⁸ Pass an object as inputObject, too. Chrome deprecated JSON-string input arguments in Chrome 155.⁸

Table A.5 — What executeTool() resolves with (tested, Chromium 156)

The draft’s column follows its execution steps. They serialize whatever the tool’s promise fulfils with to a JSON string and treat a failure to do so (JSON.stringify throws or yields undefined) as the “unserializable result” error.⁷¹ Chapter 5 recommends returning a small, flat object, which behaves the same everywhere.

Still in fluxwhich column is right

Issue #361, opened on 23 October 2026, reports the same mismatch in stable Chrome 156.0.8078.48 and in Chrome 158.0.8119.0, and notes that the web-platform-tests follow Chrome. On 26 October François Beaufort, one of the people who wrote these steps, answered: “The WPT assertions are wrong, and so is Chrome. A tool that returns "hi" should resolve to '"hi"'.” In the same thread he suggests that undefined should map to null, so the result becomes the string "null", instead of rejecting. Nothing was merged as of 2 November 2026.¹⁵ So the plain-string row will most likely move to the draft’s column, and the undefined row may change in both. Return objects and you won’t notice either change.

A.5 Events

ModelContext is an EventTarget with three events. Each has an on… handler attribute as well.¹⁶

Table A.6 — ModelContext events

The firing rules in Table A.6 are from the draft’s toolchange notification steps, its execution steps and its cancellation steps.¹⁶¹⁷ The draft warns that toolchange is queued from parallel steps, so you can’t rely on its timing relative to other tasks.¹⁷ ToolActivatedEvent and ToolCancelEvent were added to the draft on 17 September 2026.¹⁸ Listen for them on document.modelContext: Chrome’s documentation says that window.ontoolactivated and window.ontoolcancel are not supported from Chrome 156, and that both events are non-cancelable.¹⁹

A.6 Permissions Policy

All three methods are gated on the policy-controlled feature tools, whose default allowlist is 'self'.²⁰ In practice:

• A same-origin iframe can use the API. A cross-origin iframe can’t, unless the embedder delegates the feature with <iframe allow="tools">.
• Permissions-Policy: tools=() on a response turns the API off for that document and every frame inside it. The draft lists this header as a mitigation for pages where WebMCP isn’t an intended capability.²¹
• A document without the feature gets NotAllowedError from registerTool(), getTools() and executeTool(), and getTools() in other documents skips it.¹²¹³

Tested in Chromium 156: with Permissions-Policy: tools=(), document.featurePolicy.allowsFeature('tools') is false and all three methods reject with NotAllowedError. A cross-origin iframe without allow="tools" gets NotAllowedError from registerTool(). With allow="tools" and exposedTo naming the parent, the parent sees the frame’s tool through getTools({ fromOrigins }), and without fromOrigins it doesn’t.

Those three switches (the embedder’s allow="tools", the provider’s exposedTo and the consumer’s fromOrigins) now have a name in the specification. Since 27 October 2026 §6.3.4, “Interaction with the Same-Origin Policy”, describes them as “Enforcing Same-Origin Isolation via Two-Sided Opt-In”, three independent gates that all have to say yes. That section replaced the to-do note the first edition pointed at.²² Chapter 7 covers the three opt-ins in detail.

A.7 Errors

The draft names five platform failures for a tool execution and maps each one to an exception name. Callers only ever see the exception name.¹ Other exceptions come from the method steps themselves.⁶⁷¹² Table A.7 puts all of them next to what Chromium 156 actually does. If you read only one table in this appendix, make it this one.

Table A.7 — Exception names: the 27 October 2026 draft vs Chromium 156 with WebMCPTesting (tested)

A ✓ means Chromium agrees with the draft, and bold marks a difference. Chromium’s UnknownError comes with two different messages. For a tool that threw, it says “Tool was executed but the invocation failed. For example, the script function threw an error”. For a missing or forged tool and for a removed frame, it says “The operation failed for an unknown transient reason (e.g. out of memory).” The messages aren’t part of any contract, so please don’t parse them.

Chapter 7 observed the same UnknownError for forged names and origins and for a frame that went away mid-call, and the same NotAllowedError under a blocking policy. Until Chromium and the draft line up, I treat the two names as one family, and Listing A.2 does exactly that.

// Listing A.2: classify an executeTool() rejection in a way that works with both// the draft's exception names (since 8 October 2026) and Chromium 156's.export function classifyToolError(err) {  const name = err && err.name;  switch (name) {    case 'AbortError':      return { kind: 'cancelled', retry: false };   // caller's signal, or (draft) target unloaded    case 'NotAllowedError':      return { kind: 'blocked', retry: false };     // "tools" Permissions Policy says no    case 'SecurityError':      return { kind: 'bad-origin', retry: false };  // exposedTo / fromOrigins not secure    case 'NotFoundError':                           // draft: tool gone or not exposed    case 'InvalidStateError':                       // document inactive or other tab      return { kind: 'gone', retry: true };         // re-read getTools(), then retry    case 'OperationError':                          // draft: the tool threw or rejected    case 'UnknownError':                            // Chromium 156: all of the above      return { kind: 'failed', retry: true };    default:      return { kind: 'error', retry: false };  }}

Still in fluxexception names

Chromium’s UnknownError isn’t a bug against some old idea. It is what the draft itself said until recently. Until 8 October 2026 the executeTool() steps rejected with UnknownError in each of these cases, next to an inline issue asking for “more granular errors than UnknownError”. A pull request merged that day replaced it with the specific names in Table A.7 and added the tool execution error table.²⁴ Chromium 156 still behaves the way the draft read before that change. Expect the right-hand column of Table A.7 to move toward the draft, and key error handling on families (Listing A.2), not on single names.

Still in fluxwhat registerTool() resolves with

Issue #234, “registerTool should return registered tool instead of undefined”, opened on 29 July 2026, was still open on 2 November 2026.²⁵ Code that ignores the resolved value, as every listing in this book does, won’t break either way. The Tool interface proposal in Section A.9 is the most likely way this one gets settled.

A.8 The declarative attributes (removed from the specification)

Chapter 8 covers the declarative API: HTML attributes that turn a <form> into a tool. It was removed from the specification on 8 October 2026.²⁶ The project README calls it a “future exploration” that “is not part of the specification at this time”, and its explainer stays in the repository.²⁷ Chrome’s documentation still describes it, and Chromium 156 still ships it behind the same flag.¹⁹ On 16 October 2026 the explainer was corrected to name the cancel event toolcancel (it had said toolcanceled), and its open question now asks whether the events should fire at ModelContext or at the <form>.²⁸

Table A.8 — Declarative API surface: removed from the spec on 8 October 2026, still in Chrome’s trial

The rows in Table A.8 are from Chrome’s declarative API page (published 18 May 2026, last updated 25 September 2026, unchanged on 2 November 2026).¹⁹ Tested in Chromium 156: a <form toolname="search_availability" tooldescription="Find free tables"> with a required date input and a required number input (min="1" max="12") shows up in getTools() as a tool with a generated schema: date becomes { type: 'string', format: 'date' }, partySize becomes { type: 'number', minimum: 1, maximum: 12, multipleOf: 1 }, and both are listed in required.

Still in fluxthe declarative API

Removed from the specification doesn’t mean removed from Chrome. Use the attributes only behind feature detection, keep an imperative tool for the same action, and check Chapter 8 and the Chrome page before you rely on them.

A.9 Proposals that would change this page

Nothing below is in the specification. These are open pull requests that touch the IDL or the tables above, as of 2 November 2026.²⁹ I list them because the day one of them merges, a table in this appendix goes out of date, and you might want to know which one before your code tells you.

Table A.9 — Open pull requests against the API, 2 November 2026

Tip Watching these is cheap. Subscribe to the four pull requests on GitHub, and re-run the probes in appendices/a-api-reference/ whenever one of them merges or a new Chrome version reaches stable. The checks named “Chromium differs” are written to fail on purpose when Chromium catches up with the draft.

A.10 Summary

• The API is document.modelContext with three methods, registerTool(tool, { signal, exposedTo }), getTools({ fromOrigins }) and executeTool(tool, input, { signal }), plus three events: toolchange, toolactivated and toolcancel. The 27 October 2026 draft has the same IDL as the 15 October one.
• Unregister by aborting the signal. There’s no unregisterTool(), provideContext() or clearContext() any more (Appendix D).
• The tools Permissions Policy feature, default 'self', gates all three methods. Without it you get NotAllowedError. Cross-origin access needs all three opt-ins, which the draft now calls two-sided opt-in.
• exposedTo and fromOrigins accept only potentially trustworthy origins. Anything else is a SecurityError.
• Chromium 156 reports most execution failures as UnknownError where the draft says NotFoundError, OperationError or AbortError, and it resolves results the draft would reject or quote. The spec’s editors say the draft is right about strings. Handle errors by family and return objects.
• The declarative form attributes left the specification on 8 October 2026 but still work in Chrome.
• Four open pull requests (Tool interface, outputSchema, requestUserInput, openWorldHint) would change this page if they merge.