From 17e8af18c3f090e139305c759b3c93717dcc21c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Beaufort?= <beaufort.francois@gmail.com>
Date: Mon, 17 Aug 2026 15:37:00 +0200
Subject: [PATCH] feat: add executeTool() method

---
 index.d.ts      | 17 +++++++++++++++++
 index.test-d.ts | 25 +++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/index.d.ts b/index.d.ts
index 22396b4..4045620 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -148,6 +148,16 @@ namespace WebMCP {
         fromOrigins?: string[];
     }
 
+    /**
+     * Options for executing a tool.
+     */
+    interface ModelContextExecuteToolOptions {
+        /**
+         * An AbortSignal that can be used to cancel the execution of the tool.
+         */
+        signal?: AbortSignal;
+    }
+
     /**
      * Represents a tool that has been registered and is available for execution.
      */
@@ -208,6 +218,13 @@ namespace WebMCP {
          * @param options Filtering options.
          */
         getTools(options?: ModelContextGetToolOptions): Promise<RegisteredTool[]>;
+        /**
+         * Executes a tool on the document it was registered on.
+         * @param tool The tool to execute.
+         * @param inputObject The input parameters for the tool.
+         * @param options Execution options.
+         */
+        executeTool(tool: RegisteredTool, inputObject?: object, options?: ModelContextExecuteToolOptions): Promise<string>;
         /**
          * Event handler for the toolchange event.
          */
diff --git a/index.test-d.ts b/index.test-d.ts
index 5850627..1a208a7 100644
--- a/index.test-d.ts
+++ b/index.test-d.ts
@@ -162,3 +162,28 @@ test('supports tool annotations', () => {
     expectTypeOf<WebMCP.ModelContextTool['annotations']>().toEqualTypeOf<WebMCP.ToolAnnotations | undefined>();
     expectTypeOf<WebMCP.RegisteredTool['annotations']>().toEqualTypeOf<WebMCP.ToolAnnotations | undefined>();
 });
+
+declare const registeredTool: WebMCP.RegisteredTool;
+
+test('supports executeTool', async () => {
+    const controller = new AbortController();
+
+    if (document.modelContext) {
+        const result = await document.modelContext.executeTool(registeredTool);
+        expectTypeOf(result).toEqualTypeOf<string>();
+
+        await document.modelContext.executeTool(registeredTool, { query: 'test' });
+        await document.modelContext.executeTool(registeredTool, [1, 2, 3]);
+        await document.modelContext.executeTool(registeredTool, {}, { signal: controller.signal });
+
+        // @ts-expect-error inputObject must be an object.
+        await document.modelContext.executeTool(registeredTool, 'invalid');
+        // @ts-expect-error inputObject must be an object.
+        await document.modelContext.executeTool(registeredTool, 123);
+    }
+
+    expectTypeOf<WebMCP.ModelContextExecuteToolOptions>().toEqualTypeOf<{
+        signal?: AbortSignal;
+    }>();
+});
+