fix(editor): read editor.isEditable reactively in DictationGroup so the mic un-greys after sync (#311)

On an editable page the dictation mic in the byline stayed grey/disabled after
collab finished syncing, until an unrelated re-render (view↔edit toggle,
navigation) happened. DictationGroup read the NON-reactive `editor.isEditable`
field directly in render; `editor` comes from pageEditorAtom (a stable object
reference), so `editor.setEditable(true)` after sync (#218 gate) mutates TipTap
state without changing the atom reference — the byline never re-renders and
disabled=true sticks.

Read editable via `useEditorState` (the same reactive read the editor body
already uses), so the mic re-enables when the body flips editable and disables
again when it loses editable. The #218 pre-sync intent is preserved — just made
reactive. Test flips isEditable false→true and asserts the mic goes
disabled→enabled (fails against the pre-fix raw-field read).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/components/ui/agent-avatar-stack.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import { Provider, createStore } from "jotai";
-import { AgentAvatarStack, agentGlyphBackground } from "./agent-avatar-stack";
+import { AgentAvatarStack } from "./agent-avatar-stack";
 import {
   activeAiChatIdAtom,
   aiChatWindowOpenAtom,
@@ -26,23 +26,6 @@ function renderStack(props: Props) {
   return { store, ...utils };
 }
 
-describe("agentGlyphBackground", () => {
-  it("is deterministic for a given agent name", () => {
-    expect(agentGlyphBackground("Researcher")).toBe(
-      agentGlyphBackground("Researcher"),
-    );
-  });
-
-  it("differs by name and stays a fixed dark shade (readable emoji)", () => {
-    expect(agentGlyphBackground("Researcher")).not.toBe(
-      agentGlyphBackground("Нарратор"),
-    );
-    // Only the hue varies; saturation/lightness are pinned low so the glyph is
-    // always a dark circle.
-    expect(agentGlyphBackground("Нарратор")).toMatch(/^hsl\(\d+, 45%, 24%\)$/);
-  });
-});
-
 describe("AgentAvatarStack", () => {
   it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
     const { container } = renderStack({

apps/client/src/components/ui/agent-avatar-stack.tsx

@@ -23,34 +23,14 @@ export interface LauncherInfo {
   avatarUrl?: string | null;
 }
 
+// Same violet token as the former AiAgentBadge (which used color="violet").
+const AGENT_COLOR = "violet";
 const GLYPH_SIZE = 38;
 const LAUNCHER_SIZE = 22;
-// How far the launcher avatar sticks out past the agent's top-right corner, so
+// How far the launcher avatar sticks out past the agent's bottom-right corner, so
 // the "human behind" reads as behind (lower z-index) yet stays clearly visible.
 const LAUNCHER_OVERHANG = 8;
 
-// Small deterministic string hash (same algorithm as custom-avatar's initials
-// hash) used to pick a stable per-agent glyph color.
-function hashName(input: string): number {
-  let hash = 0;
-  for (let i = 0; i < input.length; i += 1) {
-    hash = (hash << 5) - hash + input.charCodeAt(i);
-    hash |= 0;
-  }
-  return Math.abs(hash);
-}
-
-/**
- * Deterministic DARK background for an emoji/sparkles agent glyph. The hue is
- * derived from the agent-name hash so distinct agents get distinct circles;
- * saturation and lightness are pinned low ("shifted into darkness") so a bright
- * emoji or the white sparkles icon stays legible on top (#300).
- */
-export function agentGlyphBackground(name: string): string {
-  const hue = hashName(name) % 360;
-  return `hsl(${hue}, 45%, 24%)`;
-}
-
 /**
  * The front avatar. Image-source priority (#300):
  *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
@@ -68,18 +48,9 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
     );
   }
 
-  // Emoji/sparkles glyphs sit on a per-agent dark circle (hashed from the agent
-  // name) so different agents are visually distinct, while the dark background
-  // keeps the emoji / white sparkles icon readable.
-  const bg = agentGlyphBackground(agent.name);
-  const glyphStyles = {
-    root: { background: bg },
-    placeholder: { background: bg, color: "var(--mantine-color-white)" },
-  };
-
   if (agent.emoji) {
     return (
-      <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
+      <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
         <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
           {agent.emoji}
         </span>
@@ -88,7 +59,7 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
   }
 
   return (
-    <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
+    <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
       <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
     </Avatar>
   );
@@ -185,7 +156,7 @@ export function AgentAvatarStack({
         : {})}
     >
       {launcher && (
-        <Box pos="absolute" top={0} right={0} style={{ zIndex: 0 }}>
+        <Box pos="absolute" bottom={0} right={0} style={{ zIndex: 0 }}>
           <CustomAvatar
             size={LAUNCHER_SIZE}
             avatarUrl={launcher.avatarUrl}
@@ -194,8 +165,8 @@ export function AgentAvatarStack({
           />
         </Box>
       )}
-      {/* The agent glyph keeps its own size (flex-centered in the container); the
-          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
+      {/* Pin the agent glyph to the top-left at its own size; the launcher then
+          overhangs it by LAUNCHER_OVERHANG at the bottom-right and stays visible. */}
       <Box
         style={{
           position: "relative",

apps/client/src/features/ai-chat/components/reasoning-block.test.tsx

@@ -1,7 +1,14 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 
+// Spy on the markdown renderer so we can assert it is NOT called while the block
+// is collapsed (the #302 fix) and IS called once on expand. The count/fallback
+// tests don't depend on real markdown, so a light stub is safe.
+vi.mock("@/features/ai-chat/utils/markdown.ts", () => ({
+  renderChatMarkdown: vi.fn((md: string) => `<p>${md}</p>`),
+}));
+
 // Stub react-i18next so `t` returns the key with `{{count}}` interpolated. This
 // keeps the assertions on the component's OWN count logic (authoritative vs
 // estimate) rather than on translation, and mirrors the t-mock pattern used by
@@ -17,6 +24,7 @@ vi.mock("react-i18next", () => ({
 
 import ReasoningBlock from "./reasoning-block";
 import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
 
 // matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
 
@@ -62,4 +70,18 @@ describe("ReasoningBlock", () => {
     // either way the text is present in the document.
     expect(screen.getByText(/reasoning/)).toBeDefined();
   });
+
+  it("does not parse the reasoning markdown while collapsed; parses on expand (#302)", () => {
+    const renderSpy = vi.mocked(renderChatMarkdown);
+    renderSpy.mockClear();
+    renderBlock({ text: "**bold** reasoning", tokens: 5 });
+    // Collapsed is the default. The expensive markdown parse (marked + DOMPurify)
+    // must NOT run for the hidden body — that O(n^2) re-parse on every streamed
+    // delta is exactly what froze the chat (#302). The collapsed body shows the
+    // cheap raw-text fallback instead.
+    expect(renderSpy).not.toHaveBeenCalled();
+    // Expanding parses the current text exactly once (a user-initiated click).
+    fireEvent.click(screen.getByRole("button"));
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+  });
 });

apps/client/src/features/ai-chat/components/reasoning-block.tsx

@@ -34,15 +34,19 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  // Memoize the markdown render so toggling `open` (or a parent re-render caused
-  // by an unrelated streamed delta) does not re-parse the reasoning text; it
-  // recomputes only when the reasoning text itself changes (while it streams in).
-  // collapseBlankLines collapses the blank-line gaps the model emits between every
-  // list item / paragraph so the reasoning renders compactly (tight lists, joined
-  // paragraphs) — ONLY here, not in the normal answer.
+  // Parse the reasoning markdown ONLY while the block is expanded. Collapsed is the
+  // default and the common case during a long "thinking" stream: reasoning text
+  // streams in and grows with every throttled delta (~20Hz), so a `[trimmed]`-only
+  // memo re-parses the whole, ever-growing text (marked + DOMPurify) on every delta
+  // — an O(n²) storm that pins the main thread and freezes the chat, all for a block
+  // the user isn't even looking at (the html is only shown inside <Collapse in={open}>
+  // below). Gating on `open` skips that hidden parsing entirely; expanding parses the
+  // current text once (an instant, user-initiated click), and further streaming while
+  // open is the normal per-delta append render, like the answer.
   const html = useMemo(
-    () => (trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : ""),
-    [trimmed],
+    () =>
+      open && trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : "",
+    [open, trimmed],
   );
 
   return (

apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.test.tsx

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from "vitest";
+import { useEffect, useState } from "react";
+import { render, act } from "@testing-library/react";
+
+// Regression test for #311: on a page the user can edit, the byline mic stayed
+// stuck disabled until an unrelated re-render happened, because DictationGroup
+// read the non-reactive field `editor.isEditable` directly. The fix reads it via
+// `useEditorState`, which subscribes to the editor's own events.
+//
+// The mock below mirrors the real `useEditorState` contract: it runs the
+// selector, and re-runs it (re-rendering the consumer) whenever the editor emits
+// an event. This is what makes the test faithful — with the pre-fix code
+// (`disabled={!editor.isEditable}`) DictationGroup never subscribes, so emitting
+// an event would NOT re-render and the mic would stay disabled.
+vi.mock("@tiptap/react", () => ({
+  useEditorState: ({ editor, selector }: any) => {
+    const [value, setValue] = useState(() => selector({ editor }));
+    useEffect(() => {
+      const handler = () => setValue(selector({ editor }));
+      editor.on("update", handler);
+      return () => editor.off("update", handler);
+    }, [editor, selector]);
+    return value;
+  },
+}));
+
+// The mic only cares about the workspace's streaming flag; return a stable stub.
+vi.mock("jotai", () => ({
+  useAtomValue: () => ({ settings: { ai: { dictationStreaming: false } } }),
+}));
+vi.mock("@/features/user/atoms/current-user-atom.ts", () => ({
+  workspaceAtom: {},
+}));
+
+// Detectable stand-in that surfaces the `disabled` prop the component computes.
+vi.mock("@/features/dictation/components/mic-button", () => ({
+  MicButton: ({ disabled }: any) => (
+    <button data-testid="mic" disabled={disabled} />
+  ),
+}));
+
+import { DictationGroup } from "./dictation-group";
+
+// Minimal editor stand-in: a mutable `isEditable` field plus a tiny event
+// emitter, matching the surface DictationGroup + the mocked useEditorState use.
+function makeFakeEditor(isEditable: boolean) {
+  const listeners = new Set<() => void>();
+  return {
+    isEditable,
+    isDestroyed: false,
+    state: { selection: { from: 0, to: 0 }, doc: { content: { size: 0 } } },
+    on: (_event: string, cb: () => void) => listeners.add(cb),
+    off: (_event: string, cb: () => void) => listeners.delete(cb),
+    emit: () => listeners.forEach((cb) => cb()),
+  } as any;
+}
+
+describe("DictationGroup editable reactivity (#311)", () => {
+  it("re-enables the mic when the editor flips isEditable false -> true", () => {
+    const editor = makeFakeEditor(false);
+    const { getByTestId } = render(<DictationGroup editor={editor} />);
+
+    // Pre-sync: not editable yet, so the mic is disabled (preserves #218 intent).
+    expect(getByTestId("mic").hasAttribute("disabled")).toBe(true);
+
+    // Collab sync flips the editor editable via editor.setEditable(true), which
+    // mutates the field and emits — the mic must react and enable itself.
+    act(() => {
+      editor.isEditable = true;
+      editor.emit();
+    });
+
+    expect(getByTestId("mic").hasAttribute("disabled")).toBe(false);
+  });
+});

apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.tsx

@@ -1,5 +1,5 @@
 import { FC, useRef } from "react";
-import type { Editor } from "@tiptap/react";
+import { Editor, useEditorState } from "@tiptap/react";
 import { useAtomValue } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { MicButton } from "@/features/dictation/components/mic-button";
@@ -22,6 +22,14 @@ export const DictationGroup: FC<Props> = ({ editor, color, iconSize }) => {
   // end so the NEXT segment appends right after it, contiguously, regardless of
   // where the user's caret currently is. Null until the first segment lands.
   const insertPosRef = useRef<number | null>(null);
+  // editor.isEditable is a mutable, non-reactive field — read it via
+  // useEditorState so the mic re-enables when the body flips to editable after
+  // collab sync (otherwise it stays stuck disabled). Mirrors the body's own
+  // reactive read.
+  const isEditable = useEditorState({
+    editor,
+    selector: (ctx) => ctx.editor?.isEditable ?? false,
+  });
 
   const handleStart = () => {
     const { from, to } = editor.state.selection;
@@ -80,7 +88,7 @@ export const DictationGroup: FC<Props> = ({ editor, color, iconSize }) => {
       streaming={streamingDictation}
       onStart={handleStart}
       onText={handleText}
-      disabled={!editor.isEditable}
+      disabled={!isEditable}
       color={color}
       iconSize={iconSize}
     />

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -173,6 +173,11 @@ export class AiChatToolsService {
       });
 
     return {
+      // INTENTIONAL per-transport divergence (not in the shared registry): this
+      // in-app search runs a semantic + keyword hybrid (RRF) with in-process
+      // access control and a tuned schema (limit 1-20); the standalone MCP
+      // `search` is a plain REST full-text search (limit up to 100). Different
+      // behaviour AND schema, so kept per-layer.
       searchPages: tool({
         description:
           'Search the wiki for pages relevant to a query. Combines exact ' +
@@ -432,6 +437,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // INTENTIONAL per-transport divergence (not shared): the description is
+      // tuned for the in-app agent (e.g. "retry with a corrected EXACT selection"
+      // and "Reversible via the comment UI"); the standalone MCP `create_comment`
+      // keeps its own wording. Kept per-layer.
       createComment: tool({
         description:
           'Add an INLINE comment to a page, or reply to an existing top-level ' +
@@ -519,6 +528,10 @@ export class AiChatToolsService {
         async () => await client.getSpaces(),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): keeps the `tree:true`
+      // hierarchy mode but is worded for the in-app agent; the standalone MCP
+      // `list_pages` carries its own wording. Kept per-layer so each side tunes
+      // its own guidance.
       listPages: tool({
         description:
           'List the most recent pages, optionally scoped to a single space. ' +
@@ -692,85 +705,25 @@ export class AiChatToolsService {
         async ({ pageId }) => await client.stashPage(pageId),
       ),
 
-      patchNode: tool({
-        description:
-          'Replace a single content block (by id) with a new ProseMirror ' +
-          'node; the replacement keeps the same nodeId. Example node: a ' +
-          'paragraph {"type":"paragraph","content":[{"type":"text","text":"Hello"}]} ' +
-          'or a heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible: ' +
-          'the previous version is kept in page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          nodeId: z
-            .string()
-            .describe('The block id to replace (from getOutline/getPageJson).'),
-          node: z
-            .any()
-            .describe(
-              'The replacement ProseMirror node, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-        }),
-        execute: async ({ pageId, nodeId, node }) => {
-          // Parity with the standalone MCP server (index.ts patch_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Schema + description from the shared registry (identical across both
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
+      // the model sometimes serializes the node as a JSON string, and we parse it
+      // before the client's typeof-object guard rejects it (parity with the
+      // standalone MCP server, index.ts patch_node).
+      patchNode: sharedTool(
+        sharedToolSpecs.patchNode,
+        async ({ pageId, nodeId, node }) => {
           const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
-      }),
+      ),
 
-      insertNode: tool({
-        description:
-          'Insert a ProseMirror node relative to an anchor, or append it at ' +
-          'the top level. For before/after you MUST provide EXACTLY ONE of ' +
-          'anchorNodeId or anchorText. Example node: a paragraph ' +
-          '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-          'heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible ' +
-          'via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          node: z
-            .any()
-            .describe(
-              'The ProseMirror node to insert, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-          position: z
-            .enum(['before', 'after', 'append'])
-            .describe('Where to insert relative to the anchor.'),
-          anchorNodeId: z
-            .string()
-            .optional()
-            .describe('Anchor block id (for before/after).'),
-          anchorText: z
-            .string()
-            .optional()
-            .describe(
-              'Anchor text fragment (for before/after), matched against the ' +
-                "block's literal rendered plain text (no markdown). " +
-                'Markdown/emoji are tolerated as a fallback; prefer plain text ' +
-                'or anchorNodeId.',
-            ),
-        }),
-        execute: async ({
-          pageId,
-          node,
-          position,
-          anchorNodeId,
-          anchorText,
-        }) => {
-          // Parity with the standalone MCP server (index.ts insert_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Shared registry schema + description; execute retains parseNodeArg on the
+      // incoming node (parity with the standalone MCP server, index.ts
+      // insert_node).
+      insertNode: sharedTool(
+        sharedToolSpecs.insertNode,
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
           const parsedNode = parseNodeArg(node);
           return await client.insertNode(pageId, parsedNode, {
             position,
@@ -778,7 +731,7 @@ export class AiChatToolsService {
             anchorText,
           });
         },
-      }),
+      ),
 
       deleteNode: sharedTool(
         sharedToolSpecs.deleteNode,
@@ -821,6 +774,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // NOT in the shared registry: this layer names the table argument
+      // `tableRef`, while the standalone MCP tool names it `table` (index.ts).
+      // Sharing one buildShape would rename a model-facing parameter on one
+      // transport, so the table row/cell tools stay per-layer by design.
       tableInsertRow: tool({
         description:
           'Insert a row of plain-text cells into a table. Reversible via ' +
@@ -841,6 +798,8 @@ export class AiChatToolsService {
           await client.tableInsertRow(pageId, tableRef, cells, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableDeleteRow: tool({
         description:
           'Delete a table row at a 0-based index. Reversible via page history.',
@@ -855,6 +814,8 @@ export class AiChatToolsService {
           await client.tableDeleteRow(pageId, tableRef, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableUpdateCell: tool({
         description:
           'Set the plain-text content of a table cell at [row, col] (0-based). ' +
@@ -884,6 +845,10 @@ export class AiChatToolsService {
           await client.importPageMarkdown(pageId, markdown),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): adds a security
+      // confirmation framing ("Only share when the user explicitly asked, since
+      // this exposes the page to anyone with the link") for the in-app agent; the
+      // standalone MCP `share_page` keeps the plain public-URL wording.
       sharePage: tool({
         description:
           'Make a page PUBLICLY accessible and return its public URL. ' +
@@ -910,6 +875,10 @@ export class AiChatToolsService {
         async ({ historyId }) => await client.restorePageVersion(historyId),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): deliberately omits the
+      // `deleteComments` schema field (comment-deletion guardrail) and carries a
+      // much shorter description; the standalone MCP `docmost_transform` exposes
+      // the full helper catalogue. Different schema, so kept per-layer.
       transformPage: tool({
         description:
           'Run a sandboxed JS transform of the form `(doc, ctx) => doc` over a ' +

apps/server/src/core/ai-chat/tools/shared-tool-specs.contract.spec.ts

@@ -113,9 +113,15 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
       const expectedKeys = Object.keys(shape).sort();
       expect(actualKeys).toEqual(expectedKeys);
 
-      // A non-.optional() field must surface as required in the advertised schema.
+      // A field that was NOT wrapped in `.optional()` must surface as required in
+      // the advertised schema. We test for the ZodOptional wrapper rather than
+      // `isOptional()`: `z.any()`/`z.unknown()` accept `undefined` and so report
+      // `isOptional() === true`, yet z.toJSONSchema still lists them under
+      // `required` (they carry no `.optional()`). Matching on the wrapper is what
+      // the emitted JSON schema actually does, so it stays correct for the
+      // registry's `node: z.any()` fields (patchNode/insertNode).
       const expectedRequired = Object.entries(shape)
-        .filter(([, field]) => !(field as z.ZodTypeAny).isOptional?.())
+        .filter(([, field]) => !(field instanceof z.ZodOptional))
         .map(([k]) => k)
         .sort();
       expect((json.required ?? []).slice().sort()).toEqual(expectedRequired);

packages/mcp/build/index.js

@@ -76,6 +76,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(spaces);
     });
     // Tool: list_pages
+    // INTENTIONAL per-transport divergence (not in the shared registry): this
+    // transport exposes a `tree:true` mode that returns the full nested hierarchy;
+    // the in-app copy keeps the same tree option but is worded for the in-app agent.
+    // Kept per-layer so each side can tune its own guidance.
     server.registerTool("list_pages", {
         description: "List most recent pages in a space ordered by updatedAt (descending). " +
             "Returns a bounded list (default 50, max 100) — use search for lookups " +
@@ -143,6 +147,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_insert_row
+    // NOT in the shared registry: this transport names the table argument `table`,
+    // while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
+    // one buildShape would rename a public MCP parameter, so the table row/cell
+    // tools stay per-transport by design.
     server.registerTool("table_insert_row", {
         description: "Insert a row of plain-text cells into a table. `table` = `#<index>` or " +
             "a block id inside it. `cells` = text per column (padded to the table's " +
@@ -159,6 +167,8 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_delete_row
+    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+    // divergence as table_insert_row.
     server.registerTool("table_delete_row", {
         description: "Delete the row at 0-based `index` from a table (`table` = `#<index>` or " +
             "a block id inside it). Refuses to delete the table's only row. An " +
@@ -174,6 +184,8 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_update_cell
+    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+    // divergence as table_insert_row.
     server.registerTool("table_update_cell", {
         description: "Set the plain-text content of cell [row,col] (0-based) in a table " +
             "(`table` = `#<index>` or a block id inside it). Replaces the cell's " +
@@ -317,62 +329,17 @@ export function createDocmostMcpServer(config) {
             },
         };
     });
-    // Tool: patch_node
-    server.registerTool("patch_node", {
-        description: "Replaces a single block identified by its attrs.id WITHOUT resending the " +
-            "whole document. Get the block id from get_page_json, then pass a " +
-            "ProseMirror node to put in its place. Example node: a paragraph " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            "JSON object or a JSON string (both accepted). Cheaper and safer than " +
-            "update_page_json for one-block structural edits.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            nodeId: z.string().min(1),
-            node: z
-                .any()
-                .describe("ProseMirror node to put in place of the node with this id, e.g. " +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                "JSON object or JSON string both accepted."),
-        },
-    }, async ({ pageId, nodeId, node }) => {
+    // Tool: patch_node — schema + description from the shared registry (identical
+    // across both transports). The execute body keeps its own parseNodeArg
+    // normalization (the model sometimes serializes `node` as a JSON string).
+    registerShared(SHARED_TOOL_SPECS.patchNode, async ({ pageId, nodeId, node }) => {
         const parsedNode = parseNodeArg(node);
         const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
         return jsonContent(result);
     });
-    // Tool: insert_node
-    server.registerTool("insert_node", {
-        description: "Insert a block before/after another block (by attrs.id or anchor text) " +
-            "or append at the end. Get anchor block ids from get_page_json. Avoids " +
-            "resending the whole document. Can also insert table structure: to add a " +
-            "tableRow, pass a tableRow node with position before/after and anchor " +
-            "INSIDE the target table — anchorNodeId of any block/cell in it, or " +
-            "anchorText matching the table; to add a tableCell/tableHeader, use " +
-            "anchorNodeId of a block inside the target row (anchorText only resolves " +
-            "top-level blocks, so it cannot target a row). `anchorText` is matched " +
-            "against the block's literal rendered plain text (no markdown); " +
-            "markdown/emoji are tolerated as a fallback; prefer plain text or " +
-            "anchorNodeId. Note: append is top-level " +
-            "only and rejects structural table nodes. Example node: a paragraph " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            "JSON object or a JSON string (both accepted).",
-        inputSchema: {
-            pageId: z.string().min(1),
-            node: z
-                .any()
-                .describe("ProseMirror node to insert, e.g. " +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                "JSON object or JSON string both accepted."),
-            position: z.enum(["before", "after", "append"]),
-            anchorNodeId: z.string().optional(),
-            anchorText: z.string().optional(),
-        },
-    }, async ({ pageId, node, position, anchorNodeId, anchorText }) => {
+    // Tool: insert_node — schema + description from the shared registry. As with
+    // patch_node, the execute body retains parseNodeArg on the incoming node.
+    registerShared(SHARED_TOOL_SPECS.insertNode, async ({ pageId, node, position, anchorNodeId, anchorText }) => {
         const parsedNode = parseNodeArg(node);
         const result = await docmostClient.insertNode(pageId, parsedNode, {
             position,
@@ -453,6 +420,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: share_page
+    // INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
+    // security-confirmation framing ("only share when the user explicitly asked,
+    // since this exposes the page to anyone with the link") tuned for the in-app
+    // agent; this transport keeps the plain public-URL wording.
     server.registerTool("share_page", {
         description: "Make a page publicly accessible (idempotent) and return its public " +
             "URL. The URL format is <app>/share/<key>/p/<slugId>.",
@@ -539,6 +510,9 @@ export function createDocmostMcpServer(config) {
         return jsonContent(comments);
     });
     // Tool: create_comment
+    // INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
+    // guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
+    // and "Reversible via the comment UI"); this transport keeps its own wording.
     server.registerTool("create_comment", {
         description: "Create a new comment on a page. The comment is ALWAYS inline and is " +
             "anchored to (highlights) its `selection` text — there are no page-level " +
@@ -652,6 +626,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: search
+    // INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
+    // runs a semantic + keyword hybrid (RRF) with in-process access control and a
+    // different schema (limit 1-20); this transport is a plain REST full-text search
+    // (limit up to 100). Different behaviour AND schema, so kept per-layer.
     server.registerTool("search", {
         description: "Search for pages and content. Results are bounded by `limit` " +
             "(default applied by the client, max 100).",
@@ -672,6 +650,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: docmost_transform
+    // INTENTIONAL per-transport divergence (not shared): the in-app `transformPage`
+    // deliberately omits the `deleteComments` schema field (comment-deletion
+    // guardrail) and carries a much shorter description; this transport exposes the
+    // full helper catalogue. Different schema, so kept per-layer.
     server.registerTool("docmost_transform", {
         description: "Edit a page by running an arbitrary JS transform `(doc, ctx) => doc` " +
             "against its LIVE ProseMirror document, with a diff preview and page " +

packages/mcp/build/tool-specs.js

@@ -80,6 +80,86 @@ export const SHARED_TOOL_SPECS = {
             nodeId: z.string().min(1),
         }),
     },
+    // --- single-block structural write (patch / insert) ---
+    //
+    // CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
+    // the whole document" + "cheaper/safer than a full-document replace" guidance
+    // AND the in-app copy's "keeps the same node id" + "Reversible via page
+    // history" framing — nothing either side conveyed is dropped. Sibling tools are
+    // named in transport-neutral prose ("the page-JSON view", "a full-document
+    // replace") to match the rest of the registry, since the two layers expose
+    // those siblings under different (snake_case vs camelCase) identifiers.
+    patchNode: {
+        mcpName: 'patch_node',
+        inAppKey: 'patchNode',
+        description: 'Replace a single content block identified by its attrs.id with a new ' +
+            'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
+            'keeps the same node id. Get the block id from the page-JSON view, then ' +
+            'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+            'heading {"type":"heading","attrs":{"level":2},"content":' +
+            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+            'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
+            'replacing the whole document for one-block structural edits. Reversible: ' +
+            'the previous version is kept in page history.',
+        buildShape: (z) => ({
+            pageId: z.string().min(1).describe('ID of the page containing the block'),
+            nodeId: z
+                .string()
+                .min(1)
+                .describe('attrs.id of the block to replace (from the page outline or ' +
+                'page-JSON view)'),
+            node: z
+                .any()
+                .describe('ProseMirror node to put in place of the node with this id, e.g. ' +
+                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+                'JSON object or JSON string both accepted.'),
+        }),
+    },
+    insertNode: {
+        mcpName: 'insert_node',
+        inAppKey: 'insertNode',
+        description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
+            'or append it at the end (top level). For before/after you MUST provide ' +
+            'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
+            'page-JSON view. Avoids resending the whole document. Can also insert ' +
+            'table structure: to add a tableRow, pass a tableRow node with position ' +
+            'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
+            'block/cell in it, or anchorText matching the table; to add a ' +
+            'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
+            '(anchorText only resolves top-level blocks, so it cannot target a row). ' +
+            "`anchorText` is matched against the block's literal rendered plain text " +
+            '(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
+            'text or anchorNodeId. Note: append is top-level only and rejects ' +
+            'structural table nodes. Example node: a paragraph ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+            'heading {"type":"heading","attrs":{"level":2},"content":' +
+            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+            'JSON object or a JSON string (both accepted). Reversible via page history.',
+        buildShape: (z) => ({
+            pageId: z.string().min(1),
+            node: z
+                .any()
+                .describe('ProseMirror node to insert, e.g. ' +
+                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+                'JSON object or JSON string both accepted.'),
+            position: z
+                .enum(['before', 'after', 'append'])
+                .describe('Where to insert relative to the anchor.'),
+            anchorNodeId: z
+                .string()
+                .optional()
+                .describe('Anchor block id (for before/after).'),
+            anchorText: z
+                .string()
+                .optional()
+                .describe("Anchor text fragment (for before/after), matched against the " +
+                "block's literal rendered plain text (no markdown). Markdown/emoji " +
+                'are tolerated as a fallback; prefer plain text or anchorNodeId.'),
+        }),
+    },
     // --- share management ---
     unsharePage: {
         mcpName: 'unshare_page',

packages/mcp/src/index.ts

@@ -105,6 +105,10 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
   });
 
 // Tool: list_pages
+// INTENTIONAL per-transport divergence (not in the shared registry): this
+// transport exposes a `tree:true` mode that returns the full nested hierarchy;
+// the in-app copy keeps the same tree option but is worded for the in-app agent.
+// Kept per-layer so each side can tune its own guidance.
 server.registerTool(
   "list_pages",
   {
@@ -195,6 +199,10 @@ server.registerTool(
 );
 
 // Tool: table_insert_row
+// NOT in the shared registry: this transport names the table argument `table`,
+// while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
+// one buildShape would rename a public MCP parameter, so the table row/cell
+// tools stay per-transport by design.
 server.registerTool(
   "table_insert_row",
   {
@@ -222,6 +230,8 @@ server.registerTool(
 );
 
 // Tool: table_delete_row
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
 server.registerTool(
   "table_delete_row",
   {
@@ -243,6 +253,8 @@ server.registerTool(
 );
 
 // Tool: table_update_cell
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
 server.registerTool(
   "table_update_cell",
   {
@@ -445,32 +457,11 @@ server.registerTool(
   },
 );
 
-// Tool: patch_node
-server.registerTool(
-  "patch_node",
-  {
-    description:
-      "Replaces a single block identified by its attrs.id WITHOUT resending the " +
-      "whole document. Get the block id from get_page_json, then pass a " +
-      "ProseMirror node to put in its place. Example node: a paragraph " +
-      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-      'heading {"type":"heading","attrs":{"level":2},"content":' +
-      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-      "JSON object or a JSON string (both accepted). Cheaper and safer than " +
-      "update_page_json for one-block structural edits.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      nodeId: z.string().min(1),
-      node: z
-        .any()
-        .describe(
-          "ProseMirror node to put in place of the node with this id, e.g. " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-            "JSON object or JSON string both accepted.",
-        ),
-    },
-  },
+// Tool: patch_node — schema + description from the shared registry (identical
+// across both transports). The execute body keeps its own parseNodeArg
+// normalization (the model sometimes serializes `node` as a JSON string).
+registerShared(
+  SHARED_TOOL_SPECS.patchNode,
   async ({ pageId, nodeId, node }) => {
     const parsedNode = parseNodeArg(node);
     const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
@@ -478,42 +469,10 @@ server.registerTool(
   },
 );
 
-// Tool: insert_node
-server.registerTool(
-  "insert_node",
-  {
-    description:
-      "Insert a block before/after another block (by attrs.id or anchor text) " +
-      "or append at the end. Get anchor block ids from get_page_json. Avoids " +
-      "resending the whole document. Can also insert table structure: to add a " +
-      "tableRow, pass a tableRow node with position before/after and anchor " +
-      "INSIDE the target table — anchorNodeId of any block/cell in it, or " +
-      "anchorText matching the table; to add a tableCell/tableHeader, use " +
-      "anchorNodeId of a block inside the target row (anchorText only resolves " +
-      "top-level blocks, so it cannot target a row). `anchorText` is matched " +
-      "against the block's literal rendered plain text (no markdown); " +
-      "markdown/emoji are tolerated as a fallback; prefer plain text or " +
-      "anchorNodeId. Note: append is top-level " +
-      "only and rejects structural table nodes. Example node: a paragraph " +
-      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-      'heading {"type":"heading","attrs":{"level":2},"content":' +
-      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-      "JSON object or a JSON string (both accepted).",
-    inputSchema: {
-      pageId: z.string().min(1),
-      node: z
-        .any()
-        .describe(
-          "ProseMirror node to insert, e.g. " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-            "JSON object or JSON string both accepted.",
-        ),
-      position: z.enum(["before", "after", "append"]),
-      anchorNodeId: z.string().optional(),
-      anchorText: z.string().optional(),
-    },
-  },
+// Tool: insert_node — schema + description from the shared registry. As with
+// patch_node, the execute body retains parseNodeArg on the incoming node.
+registerShared(
+  SHARED_TOOL_SPECS.insertNode,
   async ({ pageId, node, position, anchorNodeId, anchorText }) => {
     const parsedNode = parseNodeArg(node);
     const result = await docmostClient.insertNode(pageId, parsedNode, {
@@ -619,6 +578,10 @@ server.registerTool(
 );
 
 // Tool: share_page
+// INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
+// security-confirmation framing ("only share when the user explicitly asked,
+// since this exposes the page to anyone with the link") tuned for the in-app
+// agent; this transport keeps the plain public-URL wording.
 server.registerTool(
   "share_page",
   {
@@ -746,6 +709,9 @@ server.registerTool(
 );
 
 // Tool: create_comment
+// INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
+// guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
+// and "Reversible via the comment UI"); this transport keeps its own wording.
 server.registerTool(
   "create_comment",
   {
@@ -911,6 +877,10 @@ server.registerTool(
 );
 
 // Tool: search
+// INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
+// runs a semantic + keyword hybrid (RRF) with in-process access control and a
+// different schema (limit 1-20); this transport is a plain REST full-text search
+// (limit up to 100). Different behaviour AND schema, so kept per-layer.
 server.registerTool(
   "search",
   {
@@ -937,6 +907,10 @@ server.registerTool(
 );
 
 // Tool: docmost_transform
+// INTENTIONAL per-transport divergence (not shared): the in-app `transformPage`
+// deliberately omits the `deleteComments` schema field (comment-deletion
+// guardrail) and carries a much shorter description; this transport exposes the
+// full helper catalogue. Different schema, so kept per-layer.
 server.registerTool(
   "docmost_transform",
   {

packages/mcp/src/tool-specs.ts

@@ -119,6 +119,98 @@ export const SHARED_TOOL_SPECS = {
     }),
   },
 
+  // --- single-block structural write (patch / insert) ---
+  //
+  // CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
+  // the whole document" + "cheaper/safer than a full-document replace" guidance
+  // AND the in-app copy's "keeps the same node id" + "Reversible via page
+  // history" framing — nothing either side conveyed is dropped. Sibling tools are
+  // named in transport-neutral prose ("the page-JSON view", "a full-document
+  // replace") to match the rest of the registry, since the two layers expose
+  // those siblings under different (snake_case vs camelCase) identifiers.
+  patchNode: {
+    mcpName: 'patch_node',
+    inAppKey: 'patchNode',
+    description:
+      'Replace a single content block identified by its attrs.id with a new ' +
+      'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
+      'keeps the same node id. Get the block id from the page-JSON view, then ' +
+      'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
+      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+      'heading {"type":"heading","attrs":{"level":2},"content":' +
+      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+      'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
+      'replacing the whole document for one-block structural edits. Reversible: ' +
+      'the previous version is kept in page history.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('ID of the page containing the block'),
+      nodeId: z
+        .string()
+        .min(1)
+        .describe(
+          'attrs.id of the block to replace (from the page outline or ' +
+            'page-JSON view)',
+        ),
+      node: z
+        .any()
+        .describe(
+          'ProseMirror node to put in place of the node with this id, e.g. ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+            'JSON object or JSON string both accepted.',
+        ),
+    }),
+  },
+
+  insertNode: {
+    mcpName: 'insert_node',
+    inAppKey: 'insertNode',
+    description:
+      'Insert a block before/after another block (by attrs.id or anchor text) ' +
+      'or append it at the end (top level). For before/after you MUST provide ' +
+      'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
+      'page-JSON view. Avoids resending the whole document. Can also insert ' +
+      'table structure: to add a tableRow, pass a tableRow node with position ' +
+      'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
+      'block/cell in it, or anchorText matching the table; to add a ' +
+      'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
+      '(anchorText only resolves top-level blocks, so it cannot target a row). ' +
+      "`anchorText` is matched against the block's literal rendered plain text " +
+      '(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
+      'text or anchorNodeId. Note: append is top-level only and rejects ' +
+      'structural table nodes. Example node: a paragraph ' +
+      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+      'heading {"type":"heading","attrs":{"level":2},"content":' +
+      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+      'JSON object or a JSON string (both accepted). Reversible via page history.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1),
+      node: z
+        .any()
+        .describe(
+          'ProseMirror node to insert, e.g. ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+            'JSON object or JSON string both accepted.',
+        ),
+      position: z
+        .enum(['before', 'after', 'append'])
+        .describe('Where to insert relative to the anchor.'),
+      anchorNodeId: z
+        .string()
+        .optional()
+        .describe('Anchor block id (for before/after).'),
+      anchorText: z
+        .string()
+        .optional()
+        .describe(
+          "Anchor text fragment (for before/after), matched against the " +
+            "block's literal rendered plain text (no markdown). Markdown/emoji " +
+            'are tolerated as a fallback; prefer plain text or anchorNodeId.',
+        ),
+    }),
+  },
+
   // --- share management ---
 
   unsharePage: {

packages/mcp/test/unit/tool-specs.test.mjs

@@ -83,6 +83,63 @@ test("getNode builder produces exactly { pageId, nodeId }", () => {
   assert.deepEqual(Object.keys(shape).sort(), ["nodeId", "pageId"]);
 });
 
+test("patchNode spec exists, merges BOTH descriptions, builds { pageId, nodeId, node }", () => {
+  const spec = SHARED_TOOL_SPECS.patchNode;
+  assert.ok(spec, "patchNode spec missing");
+  assert.equal(spec.mcpName, "patch_node");
+  assert.equal(spec.inAppKey, "patchNode");
+
+  // The canonical description must carry the key guidance from BOTH originals:
+  //  - MCP-only: "WITHOUT resending the whole document" + the cheaper/safer note.
+  //  - in-app-only: "keeps the same node id" + the "Reversible ... page history"
+  //    framing the MCP copy lacked.
+  assert.match(spec.description, /WITHOUT resending the whole document/);
+  assert.match(spec.description, /Cheaper and safer/);
+  assert.match(spec.description, /keeps the same node id/i);
+  assert.match(spec.description, /Reversible/i);
+  assert.match(spec.description, /page history/i);
+
+  const shape = spec.buildShape(z);
+  assert.deepEqual(Object.keys(shape).sort(), ["node", "nodeId", "pageId"]);
+  // A minimal valid input parses (node accepts an arbitrary object via z.any()).
+  const parsed = z.object(shape).parse({
+    pageId: "p1",
+    nodeId: "n1",
+    node: { type: "paragraph" },
+  });
+  assert.equal(parsed.pageId, "p1");
+  assert.equal(parsed.nodeId, "n1");
+});
+
+test("insertNode spec exists, merges BOTH descriptions, builds the full anchor shape", () => {
+  const spec = SHARED_TOOL_SPECS.insertNode;
+  assert.ok(spec, "insertNode spec missing");
+  assert.equal(spec.mcpName, "insert_node");
+  assert.equal(spec.inAppKey, "insertNode");
+
+  // Canonical description must keep BOTH sides' nuance:
+  //  - in-app-only: "EXACTLY ONE of anchorNodeId or anchorText" + "Reversible".
+  //  - MCP-only: the table-structure (tableRow/tableCell) insertion guidance.
+  assert.match(spec.description, /EXACTLY ONE of anchorNodeId or anchorText/);
+  assert.match(spec.description, /tableRow/);
+  assert.match(spec.description, /append is top-level only/);
+  assert.match(spec.description, /Reversible via page history/);
+
+  const shape = spec.buildShape(z);
+  assert.deepEqual(
+    Object.keys(shape).sort(),
+    ["anchorNodeId", "anchorText", "node", "pageId", "position"],
+  );
+  // before/after/append are the only accepted positions; anchors are optional.
+  const schema = z.object(shape);
+  assert.doesNotThrow(() =>
+    schema.parse({ pageId: "p1", node: { type: "paragraph" }, position: "append" }),
+  );
+  assert.throws(() =>
+    schema.parse({ pageId: "p1", node: {}, position: "sideways" }),
+  );
+});
+
 test("no-arg specs (getWorkspace/listSpaces/listShares) omit buildShape", () => {
   for (const key of ["getWorkspace", "listSpaces", "listShares"]) {
     assert.equal(SHARED_TOOL_SPECS[key].buildShape, undefined, `${key} should be no-arg`);