From 33ebe53c5b5ce7c3cf10b4dfc7a1a9c11eb6d9da Mon Sep 17 00:00:00 2001
From: mlmrx <hr@unifydynamics.com>
Date: Mon, 31 Aug 2026 23:13:05 -0700
Subject: [PATCH] Clarify executeTool input and schema values

---
 index.bs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/index.bs b/index.bs
index 241bb2c..db2961c 100644
--- a/index.bs
+++ b/index.bs
@@ -635,9 +635,29 @@ is a [=model context=] [=struct=] created alongside the {{ModelContext}}.
   <dd>
     <p>Executes a tool on the document it was registered on. Returns a promise that resolves to the
     stringified result of the tool's execution.</p>
+
+    <p><var ignore>tool</var> is a {{RegisteredTool}} returned by {{ModelContext/getTools()}}. Its
+    {{RegisteredTool/inputSchema}} is exposed as a parsed JavaScript object. Callers pass the
+    structured JavaScript value described by that schema as <var ignore>inputObject</var>; the user
+    agent serializes and transfers it to the tool's execution context, so callers do not
+    {{JSON/stringify()}} it first.</p>
   </dd>
 </dl>
 
+<div class=example id=executing-a-discovered-tool>
+  The following discovers a tool and executes it with a JavaScript object:
+
+  ```js
+  const tools = await document.modelContext.getTools();
+  const tool = tools.find(({name}) => name === "example_tool");
+
+  if (tool) {
+    console.log(tool.inputSchema.type); // "object"
+    const result = await document.modelContext.executeTool(tool, {message: "hello"});
+  }
+  ```
+</div>
+
 
 <div algorithm>
 The <dfn method for=ModelContext>registerTool(<var>tool</var>, <var>options</var>)</dfn> method steps are: