diff --git a/README.md b/README.md index bf2dfb3..320a995 100644 --- a/README.md +++ b/README.md @@ -353,7 +353,7 @@ Any document in the tree matching these origins (and allowed to use `tools` perm Once tools are registered, in-page agents can discover and invoke them using `getTools()` and `executeTool()`. -Calling `document.modelContext.getTools()` returns a promise that resolves with an array of `RegisteredTool` dictionary objects. Each object contains the tool's `name`, `description`, `inputSchema`, `outputSchema`, `origin`, and owner `window`. By default, `getTools()` only returns tools registered by documents same-origin with the caller in the frame tree. To retrieve cross-origin tools, you must explicitly list their origins in the `fromOrigins` option. This array only supports secure origins. +Calling `document.modelContext.getTools()` returns a promise that resolves with an array of [`Tool`](https://webmachinelearning.github.io/webmcp/#tool) objects. Each `Tool` exposes the tool's `name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`, `origin`, and `source` (the owner window). By default, `getTools()` only returns tools registered by documents same-origin with the caller in the frame tree. To retrieve cross-origin tools, you must explicitly list their origins in the `fromOrigins` option. This array only supports secure origins. ```js // Discover tools exposed by same-origin frames in the tree (default) @@ -373,7 +373,7 @@ const crossOriginTools = await document.modelContext.getTools({ }); ``` -An agent executes a discovered `RegisteredTool` by passing the tool dictionary and input arguments along to `document.modelContext.executeTool()`. The browser securely mediates the execution, ensuring the [`exposedTo`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextregistertooloptions-exposedto) and [`fromOrigins`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextgettooloptions-fromorigins) agree, and the tool runs in the tool owner's execution context: +An agent executes a discovered `Tool` by passing it and input arguments along to `document.modelContext.executeTool()`. The browser securely mediates the execution, ensuring the [`exposedTo`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextregistertooloptions-exposedto) and [`fromOrigins`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextgettooloptions-fromorigins) agree, and the tool runs in the tool owner's execution context. `Tool` objects can only be obtained from `getTools()`, and each one refers to the specific tool registration it was returned for: if that tool is unregistered, executing the `Tool` fails, even if a new tool is later registered under the same name. ```js const tools = await document.modelContext.getTools(); diff --git a/index.bs b/index.bs index bbb561c..d68196c 100644 --- a/index.bs +++ b/index.bs @@ -100,6 +100,8 @@ spec: webidl; type: dfn; spec: html; urlPrefix: https://html.spec.whatwg.org/C type: dfn text: browsing context group + for: browsing context + text: active window spec: SECURE-CONTEXTS; urlPrefix: https://w3c.github.io/webappsec-secure-contexts/ type: abstract-op text: is origin potentially trustworthy?; url: is-origin-trustworthy @@ -177,8 +179,8 @@ A model context is a [=struct=] with the following [=struct/items=]:
: tool map - :: a [=map=] whose [=map/keys=] are [=strings=] and whose [=map/values=] are [=tool definition=] - [=structs=]. + :: a [=map=] whose [=map/keys=] are [=unique internal values=] and whose [=map/values=] are [=tool + definition=] [=structs=]. : local pending tool executions map :: a [=map=] whose [=map/keys=] are [=unique internal values=] and whose [=map/values=] are @@ -195,9 +197,15 @@ A model context is a [=struct=] with the following [=struct/items=]: A tool definition is a [=struct=] with the following [=struct/items=]:
+ : tool id + :: a [=unique internal value=]. + + Note: This identifies a specific registration of a tool. Unlike the tool's [=tool + definition/name=], it is not reused when a same-named tool is re-registered later. + : name :: a [=string=] uniquely identifying a tool registered within a [=model context=]'s [=model - context/tool map=]; it is the same as the [=map/key=] identifying this object. + context/tool map=]. The [=tool definition/name=]'s [=string/length=] must be between 1 and 128, inclusive, and only consist of [=ASCII alphanumeric=] [=code points=], U+005F LOW LINE (_), @@ -501,10 +509,10 @@ a [=list=] of [=origins=] |exposed origins|, and an [=origin=] |accessing origin
-The tool execute steps, given a [=string=] |toolName|, a {{Document}} |targetDocument|, a -[=string=] |inputArguments|, an algorithm |completionSteps|, and a [=unique internal value=] |uuid|, -are as follows. The |completionSteps| algorithm takes a [=string=]-or-null result -and a [=tool execution error=]-or-null error. +The tool execute steps, given a [=unique internal value=] |toolId|, a {{Document}} +|targetDocument|, a [=string=] |inputArguments|, an algorithm |completionSteps|, and a [=unique +internal value=] |uuid|, are as follows. The |completionSteps| algorithm takes a [=string=]-or-null +result and a [=tool execution error=]-or-null error. 1. [=Assert=]: these steps are running on |targetDocument|'s [=relevant agent=]'s [=agent/event loop=]. @@ -512,18 +520,18 @@ and a [=tool execution error=]-or-null error. 1. Let |toolMap| be |targetDocument|'s [=Document/associated ModelContext|associated ModelContext=]'s [=ModelContext/internal context=]'s [=model context/tool map=]. -1. If |toolMap|[|toolName|] does not [=map/exist=], then run |completionSteps| given null and +1. If |toolMap|[|toolId|] does not [=map/exist=], then run |completionSteps| given null and [=tool execution error/tool not found=], and abort these steps.
-

This protects us against a race between tool unregistration and execution. While tool - existence is protected from this race, tool unregistration followed by a quick - re-registration of a tool with the same |toolName| but input schema is not protected - against.

+

This protects against a race between tool unregistration and execution: the tool might have + been unregistered after {{ModelContext/executeTool()}} checked for its existence [=in + parallel=], but before these steps run.

-

This might result in |inputArguments| for an old tool being applied to the [=tool - definition/input schema=] of a newer tool, and causing whatever error that might cause, when issue #92 is resolved.

+

Because tools are looked up by |toolId| rather than by name, this also protects against the + tool being unregistered and quickly re-registered under the same name. The re-registered tool + has a different |toolId|, so a caller holding a {{Tool}} for the old tool fails to execute, + instead of silently executing the new tool with |inputArguments| intended for the old one.

@@ -533,22 +541,24 @@ and a [=tool execution error=]-or-null <var ignore>error</var>. const ac = new AbortController(); document.modelContext.registerTool({..., inputSchema: oldInputSchema}, {signal: ac.signal}); + // -- Executing document. -- + const [oldTool] = await document.modelContext.getTools(); + + // -- Tool owner document. -- // Unregister, and quickly re-register with an updated input schema. ac.abort(); document.modelContext.registerTool({..., inputSchema: newInputSchema}); - // -- Executing document. -- // - // This could target either the "old" tool, or the "new" one above, - // and the execution might encounter any requisite errors due to the mismatch. - const [tool] = await document.modelContext.getTools(); - document.modelContext.executeTool(tool, {a: 10}); + // `oldTool` refers to the old tool, so this rejects with a "NotFoundError" + // DOMException rather than executing the new tool. + document.modelContext.executeTool(oldTool, {a: 10});
-1. Let |tool| be |toolMap|[|toolName|]. +1. Let |tool| be |toolMap|[|toolId|]. 1. Run |tool|'s [=tool definition/execute steps=] given |targetDocument|, |inputArguments|, |completionSteps|, and |uuid|. @@ -633,7 +643,7 @@ internal value=] |uuid|, run these steps:
To unregister a tool given a {{ModelContext}} |modelContext| and a -[=string=] |tool name|, run these steps: +[=unique internal value=] |tool id|, run these steps: 1. [=Assert=]: these steps are running on |modelContext|'s [=relevant agent=]'s [=agent/event loop=]. @@ -641,17 +651,22 @@ To unregister a tool given a {{ModelContext}} |mo 1. Let |tool map| be |modelContext|'s [=ModelContext/internal context=]'s [=model context/tool map=]. -1. If |tool map|[|tool name|] does not [=map/exist=], then return. +1. [=Assert=]: |tool map|[|tool id|] [=map/exists=]. + + Note: These steps only run as the abort steps of the {{ModelContextRegisterToolOptions/signal}} + passed to the {{ModelContext/registerTool()}} call that registered the tool identified by + |tool id|. Since {{AbortSignal}}s only abort at most once, and nothing else removes tools from + the |tool map|, we can guarantee that the tool we're targeting is still registered. -1. Let |exposed origins| be |tool map|[|tool name|]'s [=tool definition/exposed origins=]. +1. Let |exposed origins| be |tool map|[|tool id|]'s [=tool definition/exposed origins=]. -1. [=map/Remove=] |tool map|[|tool name|]. +1. [=map/Remove=] |tool map|[|tool id|]. - Note: Unregistering a tool does not cancel an execution that has already invoked its - {{ToolExecuteCallback}}, including when the callback itself performs the unregistration. - The registration-time {{ModelContextRegisterToolOptions/signal}} only controls tool - availability, while the execution-time {{ModelContextExecuteToolOptions/signal}} controls the - lifetime of an specific invocation. + Note: Unregistering a tool does not cancel an execution that has already reached the [=invoke the + execute callback=] steps, even when the {{ToolExecuteCallback}} itself performs the + unregistration. The registration-time {{ModelContextRegisterToolOptions/signal}} only controls + tool availability, while the execution-time {{ModelContextExecuteToolOptions/signal}} controls + the lifetime of an specific invocation. 1. Let |targetDocument| be |modelContext|'s [=ModelContext/associated Document|associated Document=]. @@ -729,8 +744,8 @@ The {{ModelContext}} interface provides methods for web applications to register [Exposed=Window, SecureContext] interface ModelContext : EventTarget { Promise registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {}); - Promise> getTools(optional ModelContextGetToolOptions options = {}); - Promise executeTool(RegisteredTool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {}); + Promise> getTools(optional ModelContextGetToolOptions options = {}); + Promise executeTool(Tool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {}); attribute EventHandler ontoolchange; attribute EventHandler ontoolactivated; @@ -768,11 +783,13 @@ is.

Executes a tool on the document it was registered on. Returns a promise that resolves to the stringified result of the tool's execution.

-

tool is a {{RegisteredTool}}, often retrieved by - {{ModelContext/getTools()}}. Callers pass a JavaScript object in as the +

tool is a {{Tool}}, retrieved by {{ModelContext/getTools()}}. It + identifies the exact tool registration that {{ModelContext/getTools()}} returned, so if that + tool has since been unregistered, execution fails, even if a different tool has since been + registered under the same name. Callers pass a JavaScript object in as the {{ModelContext/executeTool(tool)/inputObject}} argument for the tool; it's expected to match the - schema described by the tool's {{RegisteredTool/inputSchema}}. If the argument is omitted, the - tool receives an empty object.

+ schema described by the tool's {{Tool/inputSchema}}. If the argument is omitted, the tool + receives an empty object.

@@ -810,7 +827,8 @@ The registerTool(tool, optionsregisterTool(tool, options. -1. If |tool map|[|tool name|] [=map/exists=], then return [=a promise rejected with=] an +1. If |tool map|'s [=map/values=] [=list/contains=] a [=tool definition=] whose [=tool + definition/name=] is |tool name|, then return [=a promise rejected with=] an {{InvalidStateError}} {{DOMException}}. Note: Similarly, script run while serializing |tool|'s {{ModelContextTool/inputSchema}} can @@ -864,6 +883,8 @@ The registerTool(tool, optionsregisterTool(tool, optionsregisterTool(tool, optionsgetTools(options) method steps 1. [=list/Append=] |parsedURL|'s [=url/origin=] to |from origins|. -1. Let |promise| be [=a new promise=] created in [=this=]'s [=relevant realm=]. +1. Let |realm| be [=this=]'s [=relevant realm=]. + +1. Let |promise| be [=a new promise=] created in |realm|. 1. Run the following steps [=in parallel=]: @@ -988,7 +1014,7 @@ The getTools(options) method steps ModelContext=]'s [=ModelContext/internal context=]'s [=model context/tool map=]. - 1. [=map/For each=] tool name → |tool definition| of |targetToolMap|: + 1. [=list/For each=] |tool definition| of |targetToolMap|'s [=map/values=]: 1. If [=tool is exposed to an origin=] given |targetOrigin|, |tool definition|'s [=tool definition/exposed origins=], and |callerOrigin| returns false, then @@ -999,51 +1025,55 @@ The getTools(options) method steps 1. [=Queue a global task=] on the [=webmcp task source=] given |global| to run the following steps: - 1. Let |tools| be an empty [=list=] of {{RegisteredTool}} dictionaries. + 1. Let |tools| be an empty [=list=] of {{Tool}} objects. 1. [=list/For each=] (|tool definition|, |targetDocument|) of |discoveredTools|: - 1. Let |registeredTool| be a new {{RegisteredTool}} dictionary, with the following fields: + 1. Let |newTool| be a [=new=] {{Tool}} object created in |realm|, whose members are set + as follows: + + : [=Tool/tool id=] + :: |tool definition|'s [=tool definition/tool id=] - : {{RegisteredTool/name}} + : [=Tool/name=] :: |tool definition|'s [=tool definition/name=] - : {{RegisteredTool/title}} + : [=Tool/title=] :: |tool definition|'s [=tool definition/title=] if it is non-null; otherwise the empty string. - Issue(#224): Consider not defaulting to the empty string, and just excluding this - member, which will result in {{undefined}}. + Issue(#224): Consider not defaulting to the empty string. - : {{RegisteredTool/description}} + : [=Tool/description=] :: |tool definition|'s [=tool definition/description=] - : {{RegisteredTool/inputSchema}} - :: the result of [=parse a JSON string to a JavaScript value=] given |tool - definition|'s [=tool definition/input schema=], if |tool definition|'s - [=tool definition/input schema=] is not the empty string; otherwise undefined. + : [=Tool/input schema=] + :: the result of [=parse a JSON string to a JavaScript value=], in |realm|, given |tool + definition|'s [=tool definition/input schema=], if |tool definition|'s [=tool + definition/input schema=] is not the empty string; otherwise null. Note: This will never throw an exception, because the string stored in the tool definition is always a valid JSON string. - : {{RegisteredTool/outputSchema}} - :: the result of [=parse a JSON string to a JavaScript value=] given |tool + : [=Tool/output schema=] + :: the result of [=parse a JSON string to a JavaScript value=], in |realm|, given |tool definition|'s [=tool definition/output schema=], if |tool definition|'s [=tool - definition/output schema=] is not the empty string; otherwise undefined. + definition/output schema=] is not the empty string; otherwise null. Note: This will never throw an exception, because the string stored in the tool definition is always a valid JSON string. - : {{RegisteredTool/window}} + : [=Tool/source=] :: |targetDocument|'s [=relevant global object=] - : {{RegisteredTool/origin}} - :: [=serialization of an origin|serialized=] |targetDocument|'s [=Document/origin=]. + : [=Tool/origin=] + :: |targetDocument|'s [=Document/origin=] - : {{RegisteredTool/annotations}} - :: if |tool definition|'s [=tool definition/annotations=] is not null, a - {{ToolAnnotations}} dictionary whose {{ToolAnnotations/readOnlyHint}} is |tool - definition|'s [=tool definition/annotations=]'s [=annotations/read-only hint=], + : [=Tool/annotations=] + :: null if |tool definition|'s [=tool definition/annotations=] is null. Otherwise, the + result of [=converted to a JavaScript value|converting to a JavaScript value=], in + |realm|, a {{ToolAnnotations}} dictionary whose {{ToolAnnotations/readOnlyHint}} is + |tool definition|'s [=tool definition/annotations=]'s [=annotations/read-only hint=], {{ToolAnnotations/untrustedContentHint}} is |tool definition|'s [=tool definition/annotations=]'s [=annotations/untrusted content hint=], {{ToolAnnotations/consequentialHint}} is |tool definition|'s [=tool @@ -1051,10 +1081,10 @@ The getTools(options) method steps {{ToolAnnotations/debugging}} is |tool definition|'s [=tool definition/annotations=]'s [=annotations/debugging=]. - 1. [=list/Append=] |registeredTool| to |tools|. + 1. [=list/Append=] |newTool| to |tools|. - 1. [=list/Sort in ascending order=] |tools|, with |a| being less than |b| if - |a|["{{RegisteredTool/name}}"] is [=code unit less than=] |b|["{{RegisteredTool/name}}"]. + 1. [=list/Sort in ascending order=] |tools|, with |a| being less than |b| if |a|'s [=Tool/name=] + is [=code unit less than=] |b|'s [=Tool/name=]. 1. [=Resolve=] |promise| with |tools|. @@ -1075,16 +1105,12 @@ The executeTool(tool, inputObjectexecuteTool(tool, inputObjectDocument=] is not [=Document/fully active=], then return [=a + promise rejected with=] an "{{InvalidStateError}}" {{DOMException}}. 1. Let |targetDocument| be |targetWindow|'s [=associated Document|associated Document=]. -1. If |targetDocument|'s [=node navigable=] is null, then return [=a promise rejected with=] an - "{{InvalidStateError}}" {{DOMException}}. - 1. Let |uuid| be a new [=unique internal value=]. 1. If |options|'s {{ModelContextExecuteToolOptions/signal}} [=map/exists=], then: @@ -1137,31 +1164,38 @@ The executeTool(tool, inputObjectModelContext=]'s [=ModelContext/internal context=]'s [=model context/tool map=]. - 1. Let |toolName| be |tool|'s {{RegisteredTool/name}}. + 1. Let |toolId| be |tool|'s [=Tool/tool id=]. - 1. If |targetToolMap|[|toolName|] does not [=map/exist=], then [=queue a global task=] on the + 1. If |targetToolMap|[|toolId|] does not [=map/exist=], then [=queue a global task=] on the [=webmcp task source=] given |callerDocument|'s [=relevant global object=] to [=reject=] |promise| with a "{{NotFoundError}}" {{DOMException}}, and abort these steps. - 1. Let |tool definition| be |targetToolMap|[|toolName|]. + 1. Let |tool definition| be |targetToolMap|[|toolId|]. + + 1. [=Assert=]: |tool definition|'s [=tool definition/name=] is |tool|'s [=Tool/name=]. + + 1. [=Assert=]: |targetOrigin| is [=same origin=] with |expectedTargetOrigin|. + + Note: |tool definition| was registered by |targetDocument|, which is the document whose + [=Document/origin=] |tool|'s [=Tool/origin=] was set to. 1. If [=tool is exposed to an origin=] given |targetOrigin|, |tool definition|'s [=tool definition/exposed origins=], and |callerOrigin| returns false, then [=queue a global task=] on the [=webmcp task source=] given |callerDocument|'s [=relevant global object=] to [=reject=] |promise| with a "{{NotFoundError}}" {{DOMException}}, and abort these steps. - Note: Rejecting with "{{NotFoundError}}" across all three checks above—when |targetOrigin| does - not match |expectedTargetOrigin|, when |toolName| does not exist, and when |tool definition| - is not exposed to |callerOrigin|—prevents a cross-origin caller from using fabricated - {{RegisteredTool}} dictionaries to probe |targetDocument|'s current origin or enumerate - private tools not exposed to |callerOrigin|. + Note: Callers cannot fabricate {{Tool}} objects; they only get them from + {{ModelContext/getTools()}}. But the tools registered in |targetDocument| can change after + {{ModelContext/getTools()}} resolves: for example, the tool can be unregistered, or + unregistered and replaced by a new tool with the same name but a different [=tool + definition/tool id=]. + + Note: Rejecting with "{{NotFoundError}}" across both checks above—when the tool identified by + |toolId| does not exist, and when |tool definition| is not exposed to |callerOrigin|—avoids + revealing to the caller which of these happened. 1. Let |completionSteps| be an algorithm that takes a [=string=]-or-null |result| and a [=tool execution error=]-or-null |error|, and runs the following steps [=in parallel=]: @@ -1205,7 +1239,7 @@ The executeTool(tool, inputObjectexecuteTool(tool, inputObject (object inputObject, ToolExecuteCall
tool["{{ModelContextTool/name}}"]
-

A unique identifier for the tool. This is used by [=agents=] to reference the tool when - making tool calls. +

A name for the tool. This is used by [=agents=] to reference the tool when making tool calls.

tool["{{ModelContextTool/title}}"]
@@ -1384,64 +1417,163 @@ dictionary ModelContextExecuteToolOptions { :: An {{AbortSignal}} that can be used to cancel the execution of the tool.
-

RegisteredTool Dictionary

+

Tool Interface

-The {{RegisteredTool}} dictionary represents a tool that has been registered and is available for -execution. +The {{Tool}} interface represents a tool that has been registered and exposed to a document for +execution. It is obtained by {{ModelContext/getTools()}}, and executed with +{{ModelContext/executeTool()}}. A {{Tool}} is a snapshot of the tool at the time +{{ModelContext/getTools()}} discovered it, and identifies that specific registration of the tool. + +Note: Each call to {{ModelContext/getTools()}} creates new {{Tool}} objects, even for tools that are +still registered, so {{Tool}} objects from different calls are never `===` to each other. -dictionary RegisteredTool { - required DOMString name; +[Exposed=Window, SecureContext] +interface Tool { + readonly attribute 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; - object outputSchema; - required Window window; - required USVString origin; - ToolAnnotations annotations; + readonly attribute DOMString title; + readonly attribute DOMString description; + readonly attribute object? inputSchema; + readonly attribute object? outputSchema; + readonly attribute WindowProxy? source; + readonly attribute USVString origin; + readonly attribute object? annotations; }; +Each {{Tool}} object has the following associated members: + +
+ : tool id + :: a [=unique internal value=]. + + Note: This is the [=tool definition/tool id=] of the [=tool definition=] that this {{Tool}} + represents. It is not exposed to script; {{ModelContext/executeTool()}} uses it to execute + exactly the tool that {{ModelContext/getTools()}} returned. + + : name + :: a [=string=]. + + : title + :: a [=string=]. + + : description + :: a [=string=]. + + : input schema + :: an {{object}}-or-null. + + : output schema + :: an {{object}}-or-null. + + : source + :: a weak reference to a {{Window}}. + + Note: A {{Window}} can only be garbage collected after its associated {{Document}} has been + destroyed, and a destroyed {{Document}} can never again be [=Document/fully active=]. So + whether [=Tool/source=] has been garbage collected is not observable to script, and a {{Tool}} + does not keep the document that registered it alive. + + : origin + :: an [=origin=]. + + : annotations + :: an {{object}}-or-null. +
+ +
+The name getter steps are to return [=this=]'s [=Tool/name=]. +
+ +
+The title getter steps are to return [=this=]'s [=Tool/title=]. +
+ +
+The description getter steps are to return [=this=]'s +[=Tool/description=]. +
+ +
+The inputSchema getter steps are to return [=this=]'s [=Tool/input +schema=]. +
+ +
+The outputSchema getter steps are to return [=this=]'s [=Tool/output +schema=]. +
+ +
+The source getter steps are: + +1. Let |window| be [=this=]'s [=Tool/source=]. + +1. If |window| has been garbage collected, or |window|'s [=associated Document|associated + Document=] is not [=Document/fully active=], then return null. + +1. Return |window|'s [=Window/browsing context=]'s {{WindowProxy}} object. + +Note: This getter returns null, rather than a {{WindowProxy}} whose \[[Window]] is different than +|window|, once the document that registered the tool has been navigated away from or becomes +detached. Unconditionally returning the stored |window|'s [=Window/browsing context=]'s +{{WindowProxy}} would mislead the callers of {{Tool/source}} in those cases, since the proxy would +follow multiple {{Window}} objects that have no relationship with the given tool. Note, however, +a {{WindowProxy}} obtained from this getter is not affected by the checks above, and keeps +following its browsing context's [=browsing context/active window=] like any other {{WindowProxy}}. +
+ +
+The origin getter steps are to return the [=serialization of an +origin|serialization=] of [=this=]'s [=Tool/origin=]. +
+ +
+The annotations getter steps are to return [=this=]'s +[=Tool/annotations=]. +
+
- : tool["{{RegisteredTool/name}}"] + : tool.{{Tool/name}} :: A unique identifier for the tool. It is the same value provided at tool registration, via {{ModelContextTool/name}}. - : tool["{{RegisteredTool/title}}"] + : tool.{{Tool/title}} :: A human-readable label for the tool. It is the same value provided at tool registration, via {{ModelContextTool/title}}. - : tool["{{RegisteredTool/description}}"] + : tool.{{Tool/description}} :: A natural language description of the tool's functionality. It is the same value provided at tool registration, via {{ModelContextTool/description}}. - : tool["{{RegisteredTool/inputSchema}}"] + : tool.{{Tool/inputSchema}} :: A JSON Schema object describing the expected input parameters for the tool - [[!JSON-SCHEMA]]. It is a deep copy of the schema provided at tool registration, via - {{ModelContextTool/inputSchema}}. - - : tool["{{RegisteredTool/outputSchema}}"] - :: A JSON Schema object describing the expected output structure for the tool [[!JSON-SCHEMA]]. - Tool output is expected to conform to the provided schema, and [=agents=] may reject outputs - that do not validate. It is a deep copy of the schema provided at tool registration, via - {{ModelContextTool/outputSchema}}. - - : tool["{{RegisteredTool/window}}"] - :: The {{Window}} of the document that registered the tool. - - : tool["{{RegisteredTool/origin}}"] - :: The origin of the document that registered the tool. This member is only meaningful when the - tool is cross-origin, and the consumer of a tool cannot otherwise get the tool's origin from - its {{RegisteredTool/window}}. For same-origin tools, this is the same as the tool's - {{RegisteredTool/window}}'s {{WindowOrWorkerGlobalScope/origin}}, and the caller's own + [[!JSON-SCHEMA]], or null if the tool was registered without one. It is a deep copy of the + schema provided at tool registration, via {{ModelContextTool/inputSchema}}. + + : tool.{{Tool/outputSchema}} + :: A JSON Schema object describing the expected output structure for the tool [[!JSON-SCHEMA]], + or null if the tool was registered without one. Tool output is expected to conform to the + provided schema, and [=agents=] may reject outputs that do not validate. It is a deep copy of + the schema provided at tool registration, via {{ModelContextTool/outputSchema}}. + + : tool.{{Tool/source}} + :: The {{WindowProxy}} of the document that registered the tool, or null if that document is no + longer [=Document/fully active=], e.g., because it was navigated away from. + + : tool.{{Tool/origin}} + :: The origin of the document that registered the tool. This is only meaningful when the tool is + cross-origin, and the consumer of a tool cannot otherwise get the tool's origin from its + {{Tool/source}}. For same-origin tools, this is the same as the tool's {{Tool/source}}'s + {{WindowOrWorkerGlobalScope/origin}}, and the caller's own {{Window}}.{{WindowOrWorkerGlobalScope/origin}}. - : tool["{{RegisteredTool/annotations}}"] - :: Optional annotations providing metadata about the tool. It matches - {{ModelContextTool/annotations}}. + : tool.{{Tool/annotations}} + :: Annotations providing metadata about the tool, matching {{ModelContextTool/annotations}}, or + null if the tool was registered without any.
@@ -2110,9 +2242,8 @@ remain: untrusted input, and callers must treat cross-origin tool descriptions and return values as untrusted data (see [[#prompt-injection]]). Additionally, because {{ModelContext/getTools()}} aggregates tools across all descendant frames at the [=origin=] level, callers should inspect - {{RegisteredTool/origin}} and {{RegisteredTool/window}} on each {{RegisteredTool}} to - disambiguate tools when multiple subframes or [=origins=] expose tools with the same - {{RegisteredTool/name}}. + {{Tool/origin}} and {{Tool/source}} on each {{Tool}} to disambiguate tools when multiple + subframes or [=origins=] expose tools with the same {{Tool/name}}.
  • Agent-Mediated Cross-Origin State Transfer: Where an external or