fix(app): registerTool edge cases + example tool correctness

App.registerTool:
- Skip outputSchema validation when result.isError (matches AppToolResult type)
- Pin callback arity to original config.inputSchema; only the validation schema is mutable via update()
- Default missing tools/call arguments to {}
- remove() is a no-op if the handle is stale (re-registered or already removed)
- Gate list_changed notifications on the listChanged capability

Examples:
- threejs: propagate executeThreeCode failures to onSceneError/onSceneRendering; catch updateModelContext rejection
- wiki-explorer: search-article preserves graph on no-match
- budget-allocator: fix category/stage values in tool descriptions

Author: ochafik

examples/budget-allocator-server/src/mcp-app.ts

@@ -685,7 +685,7 @@ app.registerTool(
       categoryId: z
         .string()
         .describe(
-          "Category ID (e.g., 'rd', 'sales', 'marketing', 'ops', 'ga')",
+          "Category ID (e.g., 'marketing', 'engineering', 'operations', 'sales', 'rd')",
         ),
       percent: z
         .number()
@@ -795,7 +795,7 @@ app.registerTool(
   {
     title: "Set Company Stage",
     description:
-      "Set the company stage for benchmark comparison (seed, series_a, series_b, growth)",
+      "Set the company stage for benchmark comparison (e.g., 'Seed', 'Series A', 'Series B', 'Growth')",
     inputSchema: z.object({
       stage: z.string().describe("Company stage ID"),
     }),

examples/threejs-server/src/mcp-app-wrapper.tsx

@@ -272,19 +272,21 @@ function McpAppWrapper() {
 
     // Send errors to model context for awareness
     if (sceneError && appRef.current) {
-      appRef.current.updateModelContext({
-        content: [
-          {
-            type: "text" as const,
-            text: `Three.js Scene Error: ${sceneError}`,
+      void appRef.current
+        .updateModelContext({
+          content: [
+            {
+              type: "text" as const,
+              text: `Three.js Scene Error: ${sceneError}`,
+            },
+          ],
+          structuredContent: {
+            type: "scene_error",
+            error: sceneError,
+            timestamp: new Date().toISOString(),
           },
-        ],
-        structuredContent: {
-          type: "scene_error",
-          error: sceneError,
-          timestamp: new Date().toISOString(),
-        },
-      });
+        })
+        .catch(() => {});
     }
   }, []);
 

examples/threejs-server/src/threejs-app.tsx

@@ -321,12 +321,18 @@ export default function ThreeJSApp({
       w,
       h,
       animControllerRef.current.visibilityAwareRAF,
-    ).catch((e) => setError(e instanceof Error ? e.message : "Unknown error"));
+    ).catch((e) => {
+      const msg = e instanceof Error ? e.message : "Unknown error";
+      setError(msg);
+      onSceneError(msg);
+      onSceneRendering(false);
+    });
 
     return () => {
       canvas.removeEventListener("touchstart", preventDefault);
       canvas.removeEventListener("touchmove", preventDefault);
       animControllerRef.current?.cleanup();
+      onSceneRendering(false);
     };
   }, [code, height, containerWidth, isFullscreen, hostHeight]);
 

examples/wiki-explorer-server/src/mcp-app.ts

@@ -425,12 +425,11 @@ app.registerTool(
       arguments: { url: searchUrl },
     });
 
-    // Clear existing graph and start fresh with this article
-    graphData.nodes = [];
-    graphData.links = [];
-
     const response = result.structuredContent as unknown as ToolResponse;
     if (response && response.page) {
+      // Clear existing graph and start fresh with this article
+      graphData.nodes = [];
+      graphData.links = [];
       initialUrl = response.page.url;
       addNode(response.page.url, response.page.title, "default", {
         x: 0,

src/app-bridge.test.ts

@@ -692,8 +692,11 @@ describe("App <-> AppBridge integration", () => {
 
   describe("App tool registration", () => {
     beforeEach(async () => {
-      // App needs tool capabilities to register tools
-      app = new App(testAppInfo, { tools: {} }, { autoResize: false });
+      app = new App(
+        testAppInfo,
+        { tools: { listChanged: true } },
+        { autoResize: false },
+      );
       await bridge.connect(bridgeTransport);
     });
 
@@ -799,6 +802,46 @@ describe("App <-> AppBridge integration", () => {
       expect(receivedExtra.signal).toBeInstanceOf(AbortSignal);
     });
 
+    it("isError result skips output schema validation", async () => {
+      await app.connect(appTransport);
+      app.registerTool(
+        "errs",
+        { outputSchema: z.object({ ok: z.boolean() }) },
+        async () => ({
+          content: [{ type: "text" as const, text: "boom" }],
+          isError: true,
+        }),
+      );
+      const res = await bridge.callTool({ name: "errs", arguments: {} });
+      expect(res.isError).toBe(true);
+      expect(res.structuredContent).toBeUndefined();
+    });
+
+    it("stale handle remove() does not delete a re-registered tool", async () => {
+      const t1 = app.registerTool("phoenix", {}, async () => ({ content: [] }));
+      t1.remove();
+      app.registerTool("phoenix", {}, async () => ({ content: [] }));
+      t1.remove();
+      await app.connect(appTransport);
+      const list = await bridge.listTools({});
+      expect(list.tools.map((t) => t.name)).toContain("phoenix");
+    });
+
+    it("host omitting arguments defaults to empty object", async () => {
+      await app.connect(appTransport);
+      let received: unknown;
+      app.registerTool(
+        "noargs2",
+        { inputSchema: z.object({}) },
+        async (args) => {
+          received = args;
+          return { content: [] };
+        },
+      );
+      await bridge.callTool({ name: "noargs2" });
+      expect(received).toEqual({});
+    });
+
     it("update({inputSchema}) is honored by handler validation", async () => {
       await app.connect(appTransport);
       const tool = app.registerTool(

src/app.ts

@@ -400,8 +400,13 @@ export class App extends ProtocolWithEvents<
     }
     const app = this;
     const notify = () => {
-      if (app.transport) void app.sendToolListChanged();
+      if (app.transport && app._capabilities.tools?.listChanged) {
+        void app.sendToolListChanged();
+      }
     };
+    // Arity is fixed at registration time even if inputSchema is later
+    // update()d, since cb's signature can't change.
+    const cbTakesArgs = config.inputSchema !== undefined;
     const registeredTool: RegisteredAppTool = {
       title: config.title,
       description: config.description,
@@ -423,6 +428,7 @@ export class App extends ProtocolWithEvents<
         notify();
       },
       remove() {
+        if (app._registeredTools[name] !== registeredTool) return;
         delete app._registeredTools[name];
         notify();
       },
@@ -431,12 +437,15 @@ export class App extends ProtocolWithEvents<
           throw new Error(`Tool ${name} is disabled`);
         }
         let result: CallToolResult;
-        if (registeredTool.inputSchema) {
-          const parsedArgs = await validateStandardSchema(
-            registeredTool.inputSchema,
-            rawArgs,
-            `Invalid input for tool ${name}: `,
-          );
+        if (cbTakesArgs) {
+          const schema = registeredTool.inputSchema;
+          const parsedArgs = schema
+            ? await validateStandardSchema(
+                schema,
+                rawArgs ?? {},
+                `Invalid input for tool ${name}: `,
+              )
+            : (rawArgs ?? {});
           result = await (
             cb as AppToolCallback<StandardSchemaV1, StandardSchemaV1>
           )(parsedArgs, extra);
@@ -445,7 +454,7 @@ export class App extends ProtocolWithEvents<
             extra,
           );
         }
-        if (registeredTool.outputSchema) {
+        if (registeredTool.outputSchema && !result.isError) {
           result.structuredContent = (await validateStandardSchema(
             registeredTool.outputSchema,
             result.structuredContent,