@pixerate/editor 0.21.0 → 0.23.0

package/dist/agent/index.d.ts

@@ -1,6 +1,8 @@
-import { C as CanvasNode, a as CanvasEdge, X as XYPosition, S as Side } from '../types-DMe0vFB1.js';
+import { C as CanvasNode, b as CanvasEdge, X as XYPosition, S as Side } from '../types-DX4Mh4SL.js';
+import { A as AgentToolProvider } from '../registry-D5-R90p0.js';
+export { a as AgentTool, b as AgentToolHandler, J as JsonSchema, c as JsonSchemaType, M as McpListToolsResult, d as McpToolContent, e as McpToolDefinition, f as McpToolResult, S as SchemaValidationError, T as TOOL_NAMESPACE_SEPARATOR, g as ToolCallContext, h as ToolCallError, i as ToolErrorCode, j as ToolRegistry, k as ToolRegistryError, l as ToolRegistryOptions, m as createToolRegistry, t as toToolResult, v as validateJsonSchema } from '../registry-D5-R90p0.js';
 import { Editor } from '@tiptap/core';
-import { W as SpreadsheetController } from '../controller-OUdxPY-X.js';
+import { S as SpreadsheetController } from '../controller-pePCJLT1.js';
 
 /**
  * Agent presence state for visual multiplayer/agent choreography.
@@ -196,6 +198,14 @@ declare function planToolCall<TNode extends CanvasNode = CanvasNode, TEdge exten
  */
 declare const MCP_TOOL_GET_EDITOR_STATE: {
     readonly name: "get_editor_state";
+    readonly title: "Get editor state";
+    readonly annotations: {
+        readonly title: "Get editor state";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
     readonly description: "Retrieves the current state of the document, variables, selection, and canvas graph (nodes and edges).";
     readonly inputSchema: {
         readonly type: "object";
@@ -213,6 +223,14 @@ declare const MCP_TOOL_GET_EDITOR_STATE: {
 };
 declare const MCP_TOOL_EDIT_CANVAS: {
     readonly name: "edit_canvas";
+    readonly title: "Edit the canvas";
+    readonly annotations: {
+        readonly title: "Edit the canvas";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
     readonly description: "Applies high-level structural operations to the visual canvas (adding nodes, connecting edges, organizing layout, or moving elements).";
     readonly inputSchema: {
         readonly type: "object";
@@ -269,6 +287,14 @@ declare const MCP_TOOL_EDIT_CANVAS: {
 };
 declare const MCP_TOOL_EDIT_PROMPT: {
     readonly name: "edit_prompt";
+    readonly title: "Edit the prompt";
+    readonly annotations: {
+        readonly title: "Edit the prompt";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
     readonly description: "Applies edits to the prompt template document, including inserting text, replacing ranges, and setting variables.";
     readonly inputSchema: {
         readonly type: "object";
@@ -307,6 +333,14 @@ declare const MCP_TOOL_EDIT_PROMPT: {
 };
 declare const MCP_TOOL_VIEW_EDITOR: {
     readonly name: "view_editor";
+    readonly title: "View the editor";
+    readonly annotations: {
+        readonly title: "View the editor";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
     readonly description: "Captures a visual image snapshot (JPEG or PNG) of the editor canvas or viewport for multimodal evaluation. Active agent cursor indicators are automatically excluded from the snapshot.";
     readonly inputSchema: {
         readonly type: "object";
@@ -335,6 +369,14 @@ declare const MCP_TOOL_VIEW_EDITOR: {
 declare const EXPORT_EXCLUDED_SELECTORS: readonly [".pixerate-presence", ".agent-presence", ".ursula-presence"];
 declare const EDITOR_MCP_TOOLS: readonly [{
     readonly name: "get_editor_state";
+    readonly title: "Get editor state";
+    readonly annotations: {
+        readonly title: "Get editor state";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
     readonly description: "Retrieves the current state of the document, variables, selection, and canvas graph (nodes and edges).";
     readonly inputSchema: {
         readonly type: "object";
@@ -351,6 +393,14 @@ declare const EDITOR_MCP_TOOLS: readonly [{
     };
 }, {
     readonly name: "edit_canvas";
+    readonly title: "Edit the canvas";
+    readonly annotations: {
+        readonly title: "Edit the canvas";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
     readonly description: "Applies high-level structural operations to the visual canvas (adding nodes, connecting edges, organizing layout, or moving elements).";
     readonly inputSchema: {
         readonly type: "object";
@@ -406,6 +456,14 @@ declare const EDITOR_MCP_TOOLS: readonly [{
     };
 }, {
     readonly name: "edit_prompt";
+    readonly title: "Edit the prompt";
+    readonly annotations: {
+        readonly title: "Edit the prompt";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        readonly idempotentHint: false;
+        readonly openWorldHint: false;
+    };
     readonly description: "Applies edits to the prompt template document, including inserting text, replacing ranges, and setting variables.";
     readonly inputSchema: {
         readonly type: "object";
@@ -443,6 +501,14 @@ declare const EDITOR_MCP_TOOLS: readonly [{
     };
 }, {
     readonly name: "view_editor";
+    readonly title: "View the editor";
+    readonly annotations: {
+        readonly title: "View the editor";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
     readonly description: "Captures a visual image snapshot (JPEG or PNG) of the editor canvas or viewport for multimodal evaluation. Active agent cursor indicators are automatically excluded from the snapshot.";
     readonly inputSchema: {
         readonly type: "object";
@@ -465,214 +531,6 @@ declare const EDITOR_MCP_TOOLS: readonly [{
     };
 }];
 
-/**
- * JSON-Schema-lite: the subset of JSON Schema used by MCP tool `inputSchema`s,
- * plus a small validator for tool-call arguments. Unknown keywords are ignored.
- */
-type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
-interface JsonSchema {
-    type?: JsonSchemaType | readonly JsonSchemaType[];
-    description?: string;
-    title?: string;
-    enum?: readonly unknown[];
-    const?: unknown;
-    default?: unknown;
-    properties?: {
-        readonly [key: string]: JsonSchema;
-    };
-    required?: readonly string[];
-    additionalProperties?: boolean | JsonSchema;
-    items?: JsonSchema;
-    minItems?: number;
-    maxItems?: number;
-    minimum?: number;
-    maximum?: number;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    [keyword: string]: unknown;
-}
-interface SchemaValidationError {
-    /** JSON-pointer-like path to the offending value, e.g. `/node/id` (`""` is the root). */
-    path: string;
-    message: string;
-}
-/**
- * Validates `value` against `schema` and returns every error found (an empty
- * array means valid). Supports `type` (incl. arrays of types), `enum`, `const`,
- * `properties`, `required`, `additionalProperties`, `items`, `minItems`,
- * `maxItems`, `minimum`, `maximum`, `minLength`, `maxLength` and `pattern`.
- */
-declare function validateJsonSchema(value: unknown, schema: JsonSchema | undefined, path?: string): SchemaValidationError[];
-
-/**
- * MCP-shaped tool definition, as returned by `tools/list`.
- */
-interface McpToolDefinition {
-    name: string;
-    title?: string;
-    description?: string;
-    inputSchema: JsonSchema & {
-        type: 'object';
-    };
-    outputSchema?: JsonSchema;
-    annotations?: {
-        title?: string;
-        readOnlyHint?: boolean;
-        destructiveHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-        [key: string]: unknown;
-    };
-}
-type McpToolContent = {
-    type: 'text';
-    text: string;
-} | {
-    type: 'image';
-    data: string;
-    mimeType: string;
-} | {
-    type: string;
-    [key: string]: unknown;
-};
-/** MCP `tools/call` result. */
-interface McpToolResult {
-    content: McpToolContent[];
-    structuredContent?: Record<string, unknown>;
-    isError?: boolean;
-}
-/** MCP `tools/list` result. */
-interface McpListToolsResult {
-    tools: McpToolDefinition[];
-}
-interface ToolCallContext {
-    /** Name the tool was called by (possibly namespaced). */
-    name: string;
-    /** Id of the provider that owns the tool. */
-    providerId: string;
-    signal?: AbortSignal;
-}
-/**
- * Handler return values are normalized into an {@link McpToolResult}: a full
- * result (`{ content: [...] }`) is passed through, a string becomes a text
- * block, `undefined` becomes an empty result, and anything else is returned
- * as `structuredContent` (plain objects) plus a JSON text block.
- */
-type AgentToolHandler = (args: Record<string, any>, context: ToolCallContext) => unknown | Promise<unknown>;
-interface AgentTool extends McpToolDefinition {
-    handler: AgentToolHandler;
-}
-/**
- * A source of tools, typically one per mounted editor, spreadsheet or canvas.
- */
-interface AgentToolProvider {
-    /** Unique id within a registry, e.g. `doc-1`. Used as the namespace on collisions. */
-    id: string;
-    /** Always prefix this provider's tools with `<namespace>__`. */
-    namespace?: string;
-    /** Tools, or a function returning the current tools (re-read on every `listTools`). */
-    tools: readonly AgentTool[] | (() => readonly AgentTool[]);
-    /** Lets the provider signal that its tool list changed; returns an unsubscribe function. */
-    subscribe?: (notify: () => void) => () => void;
-}
-type ToolErrorCode = 'unknown_tool' | 'invalid_arguments' | 'tool_failed';
-/** Structured error carried in `structuredContent.error` of a failed call. */
-interface ToolCallError {
-    code: ToolErrorCode;
-    message: string;
-    tool: string;
-    details?: SchemaValidationError[];
-}
-declare class ToolRegistryError extends Error {
-    readonly code: 'duplicate_provider' | 'name_collision' | 'invalid_tool';
-    constructor(code: ToolRegistryError['code'], message: string);
-}
-interface ToolRegistryOptions {
-    /**
-     * What to do when two providers contribute the same tool name:
-     * `namespace` (default) exposes every colliding tool as `<providerId>__<name>`;
-     * `error` makes `register` throw.
-     */
-    onCollision?: 'namespace' | 'error';
-    /** Coalescing window for `listChanged` notifications in ms (default 0: same tick). */
-    listChangedDelayMs?: number;
-    /** Validate arguments against `inputSchema` before calling handlers (default `true`). */
-    validateArguments?: boolean;
-}
-/** Separator between namespace and tool name; valid in MCP and LLM tool-name charsets. */
-declare const TOOL_NAMESPACE_SEPARATOR = "__";
-/** Normalizes a handler's return value into an MCP `tools/call` result. */
-declare function toToolResult(value: unknown): McpToolResult;
-/**
- * Transport-agnostic registry of agent tools contributed by live providers.
- *
- * `listTools()` and `callTool()` return MCP `tools/list` / `tools/call`
- * result shapes, and `onListChanged` fires (coalesced) whenever the exposed
- * tool list changes, mirroring MCP's `notifications/tools/list_changed`, so an
- * MCP server can be a thin wrapper around it.
- */
-declare class ToolRegistry {
-    /** MCP server capabilities this registry supports. */
-    readonly capabilities: {
-        readonly tools: {
-            readonly listChanged: true;
-        };
-    };
-    private readonly entries;
-    private readonly listeners;
-    private readonly options;
-    private timer;
-    private lastSignature;
-    constructor(options?: ToolRegistryOptions);
-    /**
-     * Registers a provider and returns a function that unregisters it.
-     * Throws a {@link ToolRegistryError} for a duplicate provider id, an invalid
-     * tool name, or (with `onCollision: 'error'`) a tool name collision.
-     */
-    register(provider: AgentToolProvider): () => void;
-    /** Removes a provider by id or instance. Returns whether it was registered. */
-    unregister(providerOrId: string | AgentToolProvider): boolean;
-    /** Registered provider ids in registration order. */
-    providerIds(): string[];
-    /**
-     * Resolves exposed names. Tools are ordered by provider registration, then
-     * by their order within the provider.
-     */
-    private resolve;
-    /** MCP `tools/list` result for the current providers. */
-    listTools(): McpListToolsResult;
-    /** Whether a tool with this exposed name exists. */
-    hasTool(name: string): boolean;
-    /** Looks up a tool definition by exposed name. */
-    getTool(name: string): McpToolDefinition | undefined;
-    /**
-     * Calls a tool by exposed name and returns an MCP `tools/call` result.
-     * Never rejects: unknown tools, invalid arguments and handler errors come
-     * back as `isError: true` results with a {@link ToolCallError} in
-     * `structuredContent.error` (MCP transports may map `unknown_tool` to a
-     * JSON-RPC `-32602` error instead).
-     */
-    callTool(name: string, args?: Record<string, unknown>, options?: {
-        signal?: AbortSignal;
-    }): Promise<McpToolResult>;
-    /**
-     * Subscribes to tool-list changes. Notifications are coalesced: many
-     * registrations or provider signals within the delay window produce one
-     * call, and none if the exposed list ends up unchanged (e.g. a provider
-     * unmounted and remounted). Returns an unsubscribe function.
-     */
-    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
-    /** Schedules a coalesced `listChanged` check; providers may call it directly. */
-    notifyListChanged(): void;
-    /** Runs a pending `listChanged` check immediately. */
-    flush(): void;
-    private signature;
-    /** Unregisters every provider and listener and cancels pending notifications. */
-    dispose(): void;
-}
-declare function createToolRegistry(options?: ToolRegistryOptions): ToolRegistry;
-
 interface ToolProviderOptions {
     /** Provider id (unique per registry). */
     id: string;
@@ -723,4 +581,4 @@ interface EditorMcpToolProviderOptions<TNode extends CanvasNode = CanvasNode, TE
  */
 declare function createEditorMcpToolProvider<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(options: EditorMcpToolProviderOptions<TNode, TEdge>): AgentToolProvider;
 
-export { type AgentCommand, type AgentPresence, type AgentStep, type AgentTool, type AgentToolHandler, type AgentToolProvider, EDITOR_MCP_TOOLS, EXPORT_EXCLUDED_SELECTORS, type EditorMcpToolProviderOptions, type EditorSnapshot, type JsonSchema, type JsonSchemaType, MCP_TOOL_EDIT_CANVAS, MCP_TOOL_EDIT_PROMPT, MCP_TOOL_GET_EDITOR_STATE, MCP_TOOL_VIEW_EDITOR, type McpListToolsResult, type McpToolContent, type McpToolDefinition, type McpToolResult, type RichTextToolTarget, type SchemaValidationError, TOOL_NAMESPACE_SEPARATOR, type ToolCallContext, type ToolCallError, type ToolErrorCode, type ToolProviderOptions, ToolRegistry, ToolRegistryError, type ToolRegistryOptions, createEditorMcpToolProvider, createRichTextToolProvider, createSpreadsheetToolProvider, createToolRegistry, normalizeSide, planAgentCommand, planToolCall, toToolResult, toolCallToAgentCommand, validateJsonSchema };
+export { type AgentCommand, type AgentPresence, type AgentStep, AgentToolProvider, EDITOR_MCP_TOOLS, EXPORT_EXCLUDED_SELECTORS, type EditorMcpToolProviderOptions, type EditorSnapshot, MCP_TOOL_EDIT_CANVAS, MCP_TOOL_EDIT_PROMPT, MCP_TOOL_GET_EDITOR_STATE, MCP_TOOL_VIEW_EDITOR, type RichTextToolTarget, type ToolProviderOptions, createEditorMcpToolProvider, createRichTextToolProvider, createSpreadsheetToolProvider, normalizeSide, planAgentCommand, planToolCall, toolCallToAgentCommand };

package/dist/agent/index.js

@@ -1,13 +1,16 @@
+import {
+  validateJsonSchema
+} from "../chunk-ARRTP33I.js";
 import {
   getEditorMarkdown,
   getEditorText,
   plainTextToSlice
-} from "../chunk-3TYMNULT.js";
+} from "../chunk-MJZBNWG7.js";
 import {
   colNameToIndex,
   indexToColName,
   isFormulaError
-} from "../chunk-A7DKIA72.js";
+} from "../chunk-QBJ22YZR.js";
 import {
   ensureLayout,
   getLayoutedNodes,
@@ -276,6 +279,14 @@ function planToolCall(name, args, snapshot, options) {
 // src/agent/tools.ts
 var MCP_TOOL_GET_EDITOR_STATE = {
   name: "get_editor_state",
+  title: "Get editor state",
+  annotations: {
+    title: "Get editor state",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   description: "Retrieves the current state of the document, variables, selection, and canvas graph (nodes and edges).",
   inputSchema: {
     type: "object",
@@ -293,6 +304,14 @@ var MCP_TOOL_GET_EDITOR_STATE = {
 };
 var MCP_TOOL_EDIT_CANVAS = {
   name: "edit_canvas",
+  title: "Edit the canvas",
+  annotations: {
+    title: "Edit the canvas",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false
+  },
   description: "Applies high-level structural operations to the visual canvas (adding nodes, connecting edges, organizing layout, or moving elements).",
   inputSchema: {
     type: "object",
@@ -355,6 +374,14 @@ var MCP_TOOL_EDIT_CANVAS = {
 };
 var MCP_TOOL_EDIT_PROMPT = {
   name: "edit_prompt",
+  title: "Edit the prompt",
+  annotations: {
+    title: "Edit the prompt",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false
+  },
   description: "Applies edits to the prompt template document, including inserting text, replacing ranges, and setting variables.",
   inputSchema: {
     type: "object",
@@ -393,6 +420,14 @@ var MCP_TOOL_EDIT_PROMPT = {
 };
 var MCP_TOOL_VIEW_EDITOR = {
   name: "view_editor",
+  title: "View the editor",
+  annotations: {
+    title: "View the editor",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
   description: "Captures a visual image snapshot (JPEG or PNG) of the editor canvas or viewport for multimodal evaluation. Active agent cursor indicators are automatically excluded from the snapshot.",
   inputSchema: {
     type: "object",
@@ -426,103 +461,6 @@ var EDITOR_MCP_TOOLS = [
   MCP_TOOL_VIEW_EDITOR
 ];
 
-// src/agent/schema.ts
-function typeOf(value) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
-  if (typeof value === "string" || typeof value === "boolean" || typeof value === "object") {
-    return typeof value;
-  }
-  return "undefined";
-}
-function matchesType(value, type) {
-  const actual = typeOf(value);
-  if (type === "number") return actual === "number" || actual === "integer";
-  return actual === type;
-}
-var isEqual = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
-function validateJsonSchema(value, schema, path = "") {
-  if (!schema || typeof schema !== "object") return [];
-  const errors = [];
-  const at = path || "/";
-  if (schema.type !== void 0) {
-    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-    if (!types.some((t) => matchesType(value, t))) {
-      errors.push({ path: at, message: `Expected ${types.join(" | ")}, got ${typeOf(value)}.` });
-      return errors;
-    }
-  }
-  if (schema.const !== void 0 && !isEqual(value, schema.const)) {
-    errors.push({ path: at, message: `Expected ${JSON.stringify(schema.const)}.` });
-  }
-  if (schema.enum && !schema.enum.some((option) => isEqual(value, option))) {
-    errors.push({
-      path: at,
-      message: `Expected one of ${schema.enum.map((o) => JSON.stringify(o)).join(", ")}, got ${JSON.stringify(value)}.`
-    });
-  }
-  if (typeof value === "string") {
-    if (schema.minLength !== void 0 && value.length < schema.minLength) {
-      errors.push({ path: at, message: `Must be at least ${schema.minLength} characters.` });
-    }
-    if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
-      errors.push({ path: at, message: `Must be at most ${schema.maxLength} characters.` });
-    }
-    if (schema.pattern !== void 0) {
-      let regex = null;
-      try {
-        regex = new RegExp(schema.pattern, "u");
-      } catch {
-      }
-      if (regex && !regex.test(value)) {
-        errors.push({ path: at, message: `Must match pattern ${schema.pattern}.` });
-      }
-    }
-  }
-  if (typeof value === "number") {
-    if (schema.minimum !== void 0 && value < schema.minimum) {
-      errors.push({ path: at, message: `Must be >= ${schema.minimum}.` });
-    }
-    if (schema.maximum !== void 0 && value > schema.maximum) {
-      errors.push({ path: at, message: `Must be <= ${schema.maximum}.` });
-    }
-  }
-  if (Array.isArray(value)) {
-    if (schema.minItems !== void 0 && value.length < schema.minItems) {
-      errors.push({ path: at, message: `Must have at least ${schema.minItems} items.` });
-    }
-    if (schema.maxItems !== void 0 && value.length > schema.maxItems) {
-      errors.push({ path: at, message: `Must have at most ${schema.maxItems} items.` });
-    }
-    if (schema.items) {
-      value.forEach((item, index) => {
-        errors.push(...validateJsonSchema(item, schema.items, `${path}/${index}`));
-      });
-    }
-  }
-  if (typeOf(value) === "object") {
-    const obj = value;
-    for (const key of schema.required ?? []) {
-      if (obj[key] === void 0) {
-        errors.push({ path: `${path}/${key}`, message: `Missing required property "${key}".` });
-      }
-    }
-    const properties = schema.properties ?? {};
-    for (const [key, child] of Object.entries(obj)) {
-      if (child === void 0) continue;
-      if (key in properties) {
-        errors.push(...validateJsonSchema(child, properties[key], `${path}/${key}`));
-      } else if (schema.additionalProperties === false) {
-        errors.push({ path: `${path}/${key}`, message: `Unknown property "${key}".` });
-      } else if (typeof schema.additionalProperties === "object") {
-        errors.push(...validateJsonSchema(child, schema.additionalProperties, `${path}/${key}`));
-      }
-    }
-  }
-  return errors;
-}
-
 // src/agent/registry.ts
 var ToolRegistryError = class extends Error {
   code;
@@ -773,6 +711,7 @@ function createRichTextToolProvider(target, options) {
   const editor = () => toEditor(target);
   const getText = {
     name: "get_text",
+    title: "Get document text",
     description: "Returns the document content (plain text by default, or HTML / markdown) and the current selection.",
     inputSchema: {
       type: "object",
@@ -785,7 +724,13 @@ function createRichTextToolProvider(target, options) {
       },
       additionalProperties: false
     },
-    annotations: { readOnlyHint: true },
+    annotations: {
+      title: "Get document text",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     handler: ({ format = "text" }) => {
       const ed = editor();
       const content = format === "html" ? ed.getHTML() : format === "markdown" ? getEditorMarkdown(ed) : getEditorText(ed);
@@ -794,6 +739,7 @@ function createRichTextToolProvider(target, options) {
   };
   const insertText = {
     name: "insert_text",
+    title: "Insert text",
     description: "Inserts literal text (newlines start new paragraphs) at a document position, or at the cursor when `at` is omitted.",
     inputSchema: {
       type: "object",
@@ -804,6 +750,13 @@ function createRichTextToolProvider(target, options) {
       required: ["text"],
       additionalProperties: false
     },
+    annotations: {
+      title: "Insert text",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
     handler: ({ text, at }) => {
       const ed = editor();
       const size = ed.state.doc.content.size;
@@ -817,6 +770,7 @@ function createRichTextToolProvider(target, options) {
   };
   const replaceSelection = {
     name: "replace_selection",
+    title: "Replace selection",
     description: "Replaces the selected content with literal text (an empty string deletes the selection).",
     inputSchema: {
       type: "object",
@@ -824,7 +778,13 @@ function createRichTextToolProvider(target, options) {
       required: ["text"],
       additionalProperties: false
     },
-    annotations: { destructiveHint: true },
+    annotations: {
+      title: "Replace selection",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    },
     handler: ({ text }) => {
       const ed = editor();
       const { from, to } = ed.state.selection;
@@ -865,6 +825,7 @@ function createSpreadsheetToolProvider(controller, options) {
   };
   const getRange = {
     name: "get_range",
+    title: "Read cells",
     description: 'Reads a cell range in A1 notation (e.g. "A1:C5" or "B2") and returns computed values, raw input and errors.',
     inputSchema: {
       type: "object",
@@ -874,7 +835,13 @@ function createSpreadsheetToolProvider(controller, options) {
       required: ["range"],
       additionalProperties: false
     },
-    annotations: { readOnlyHint: true },
+    annotations: {
+      title: "Read cells",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     handler: ({ range }) => {
       const [startRef, endRef = startRef] = String(range).split(":");
       const start = parseCell(startRef);
@@ -913,6 +880,7 @@ function createSpreadsheetToolProvider(controller, options) {
   };
   const setCell = {
     name: "set_cell",
+    title: "Set a cell",
     description: 'Sets the raw input of one cell (A1 notation). Values starting with "=" are formulas.',
     inputSchema: {
       type: "object",
@@ -923,6 +891,13 @@ function createSpreadsheetToolProvider(controller, options) {
       required: ["cell", "value"],
       additionalProperties: false
     },
+    annotations: {
+      title: "Set a cell",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     handler: ({ cell, value }) => {
       const { row, col } = parseCell(cell);
       const found = lookup(row, col);