diff --git a/README.md b/README.md index 928bd7c..82ebdb0 100644 --- a/README.md +++ b/README.md @@ -347,7 +347,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`, `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 `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. ```js // Discover tools exposed by same-origin frames in the tree (default) @@ -357,6 +357,7 @@ for (const tool of tools) { console.log(`Tool: ${tool.name} (from ${tool.origin})`); console.log(`Description: ${tool.description}`); console.log(`Parameters schema:`, tool.inputSchema); + console.log(`Output schema:`, tool.outputSchema); } // Discover additional tools provided by a cross-origin frame (in addition to @@ -480,8 +481,6 @@ As the WebMCP proposal continues to evolve with community and stakeholder feedba - **Skills Integration**: Determining if the author should expose a higher-level "skill" to help the agent coordinate multiple related tools to fulfill a user journey. See [Issue #161](https://github.com/webmachinelearning/webmcp/issues/161). -- **Output schema**: Supporting structured `outputSchema` contracts (complementing `inputSchema`) to help LLMs reliably reason about the return values of tools. See [Issue #9](https://github.com/webmachinelearning/webmcp/issues/9). - - **User prompting and elicitation**: Exploring a way for a tool to prompt the user for confirmation when tools require explicit user authorization. This could be done by delegating to the agent and its harness, or by invoking native browser permission dialogue outside of the agent loop. See [Issue #165](https://github.com/webmachinelearning/webmcp/issues/165) and [Issue #50](https://github.com/webmachinelearning/webmcp/issues/50) for discussion about the `ModelContextClient` interface. - **Tool progress reporting**: For long-running tasks (e.g., batch processing or generating content), the agent may want a way to track a tool's progress. We are exploring how this intersects with the established [MCP Progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress) specification. diff --git a/index.bs b/index.bs index 69bed7e..9909c78 100644 --- a/index.bs +++ b/index.bs @@ -172,12 +172,21 @@ A tool definition is a [=struct=] with the following [=struct/items=] Note: For tools registered by the imperative form of this API (i.e., {{ModelContext/registerTool()}}), this is the stringified representation of - {{ModelContextTool/inputSchema}}. For tools registered + {{ModelContextTool/inputSchema}}, created by the [=serialize a tool schema=] + algorithm. For tools registered [declaratively](https://github.com/webmachinelearning/webmcp/pull/76), this will be a stringified JSON Schema object created by the [=synthesize a declarative JSON Schema object algorithm=]. [[!JSON-SCHEMA]] + : output schema + :: a [=string=]. + + Note: For tools registered by the imperative form of this API (i.e., + {{ModelContext/registerTool()}}), this is the stringified representation of + {{ModelContextTool/outputSchema}}, created by the [=serialize a tool schema=] + algorithm. + : execute steps :: an algorithm that takes a {{Document}} targetDocument, a [=string=] inputArguments, an algorithm completionSteps that takes a @@ -561,6 +570,31 @@ To unregister a tool given a {{ModelContext}} |mo +
+To serialize a tool schema given a {{ModelContextTool}} |tool|'s +{{ModelContextTool/inputSchema}} or {{ModelContextTool/outputSchema}} |schema|: + +1. If |tool|'s |schema| does not [=map/exist=], then return the empty string. + +1. Return the result of [=serializing a JavaScript value to a JSON string=] given |tool|'s |schema|. + +
+

The [=serialize a JavaScript value to a JSON string=] algorithm throws exceptions in the + following cases:

+ +
    +

  1. Throws a new {{TypeError}} when the backing "JSON.stringify()" + yields undefined, e.g., + "inputSchema: { toJSON() {return HTMLDivElement;}}", or + "outputSchema: { toJSON() {return undefined;}}".

    2. + +

  2. Re-throws exceptions thrown by "JSON.stringify()", e.g., when + |tool|'s |schema| is an object with a circular reference, etc.

    3. +
+
+ +
+

API

@@ -620,7 +654,7 @@ is a [=model context=] [=struct=] created alongside the {{ModelContext}}.

Registers a tool that [=agents=] can invoke. Returns a rejected promise if a tool with the same name is already registered, if the given {{ModelContextTool/name}} or {{ModelContextTool/description}} are empty strings, or if the {{ModelContextTool/inputSchema}} - is invalid.

+ or {{ModelContextTool/outputSchema}} is invalid.

document.{{Document/modelContext}}.{{ModelContext/getTools(options)}}
@@ -674,26 +708,13 @@ The registerTool(tool, options -

The serialization algorithm above throws exceptions in the following cases:

- -
    -

  1. Throws a new {{TypeError}} when the backing "JSON.stringify()" - yields undefined, e.g., - "inputSchema: { toJSON() {return HTMLDivElement;}}", or - "inputSchema: { toJSON() {return undefined;}}".

    2. - -

  2. Re-throws exceptions thrown by "JSON.stringify()", e.g., when - "inputSchema" is an object with a circular reference, etc.

    3. -
- +1. Let |stringified output schema| be the result of [=serializing a tool schema=] + given |tool|'s {{ModelContextTool/outputSchema}}. If this threw an exception, then return [=a + promise rejected with=] that exception. 1. If |options|'s {{ModelContextRegisterToolOptions/signal}} [=map/exists=] and is [=AbortSignal/aborted=], then return [=a promise rejected with=] |options|'s @@ -742,6 +763,9 @@ The registerTool(tool, optionsgetTools(options) method steps 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 + definition|'s [=tool definition/output schema=], if |tool definition|'s [=tool + definition/output schema=] is not the empty string; otherwise undefined. + + Note: This will never throw an exception, because the string stored in the tool + definition is always a valid JSON string. + : {{RegisteredTool/window}} :: |targetDocument|'s [=relevant global object=] @@ -1061,6 +1093,7 @@ dictionary ModelContextTool { USVString title; required DOMString description; object inputSchema; + object outputSchema; required ToolExecuteCallback execute; ToolAnnotations annotations; }; @@ -1102,6 +1135,13 @@ callback ToolExecuteCallback = Promise (object inputObject, ToolExecuteCall

A JSON Schema object describing the expected input parameters for the tool [[!JSON-SCHEMA]]. +

tool["{{ModelContextTool/outputSchema}}"]
+
+

A JSON Schema object describing the expected output structure for the tool [[!JSON-SCHEMA]], + so that [=agents=] may use it to insert an [=implementation-defined=] message to guide the + language model’s behavior. +

+
tool["{{ModelContextTool/execute}}"]

A callback function that is invoked when an [=agent=] calls the tool. The function receives @@ -1205,6 +1245,7 @@ dictionary RegisteredTool { DOMString title; required DOMString description; object inputSchema; + object outputSchema; required Window window; required USVString origin; ToolAnnotations annotations; @@ -1229,6 +1270,12 @@ dictionary RegisteredTool { [[!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]], so + that [=agents=] may use it to insert an [=implementation-defined=] message to guide the + language model’s behavior. 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. diff --git a/security-privacy-questionnaire.md b/security-privacy-questionnaire.md index dc0e7df..6e2d7d0 100644 --- a/security-privacy-questionnaire.md +++ b/security-privacy-questionnaire.md @@ -101,7 +101,7 @@ Note: this behavior is not yet spec'd but is the intended direction. > 20. Does your spec define when and how new kinds of errors should be raised? -Yes. `registerTool()` throws `InvalidStateError` for inactive documents, duplicate names, or invalid name/description; `NotAllowedError` when the `"tools"` Permissions Policy is disallowed; `SecurityError` for non-trustworthy [`exposedTo`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextregistertooloptions-exposedto) origins; and `TypeError` when `inputSchema` serialization fails. These errors only reflect the page's own state and inputs, so they do not leak new information. +Yes. `registerTool()` throws `InvalidStateError` for inactive documents, duplicate names, or invalid name/description; `NotAllowedError` when the `"tools"` Permissions Policy is disallowed; `SecurityError` for non-trustworthy [`exposedTo`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextregistertooloptions-exposedto) origins; and `TypeError` when `inputSchema` or `outputSchema` serialization fails. These errors only reflect the page's own state and inputs, so they do not leak new information. > 21. Does your feature allow sites to learn about the user's use of assistive technology?