Agent Tool Catalog for DOCX Editing — docx-editor Docs

Fourteen tools work against either bridge. Schemas are OpenAI function-calling format. Anthropic, Vercel AI SDK, and anything else that takes that shape accepts them as-is.

Locate, then mutate

Locate tools return paragraphs tagged with a stable paraId. Mutate tools accept that paraId. paraIds survive concurrent edits and tool-loop iterations; ordinal paragraph indices do not.

This mirrors the addressing model Office.js uses for Range, made JSON-serializable so it survives tool calls and MCP transports. See Word JS API parity for the full mapping.

Catalog

Group	Tool	Purpose
Locate	`read_document`	Return paragraphs with their `paraId`s.
Locate	`read_selection`	Read the user's current cursor / selection.
Locate	`read_page`	Return paragraphs on a single page.
Locate	`read_pages`	Return paragraphs across a page range.
Locate	`find_text`	Locate text. Returns one handle per matching paragraph.
Locate	`read_comments`	List existing comments and replies.
Locate	`read_changes`	List existing tracked changes.
Mutate	`add_comment`	Add a comment, anchored to a paragraph.
Mutate	`suggest_change`	One tool, three modes via empty-string semantics. Replacement: both non-empty. Deletion: `replaceWith=""`. Insertion: `search=""` appends to the paragraph.
Mutate	`apply_formatting`	Apply character formatting (bold, italic, color, font) to a range.
Mutate	`set_paragraph_style`	Set a paragraph style (Heading 1, Quote, etc.).
Mutate	`reply_comment`	Reply to an existing comment thread.
Mutate	`resolve_comment`	Mark a comment thread as done.
Navigate	`scroll`	Scroll the editor to a paragraph. Headless bridge: no-op.

Loading the schemas

import { getToolSchemas } from '@eigenpal/docx-editor-agents';
 
const schemas = getToolSchemas(); // OpenAI function-calling format

For Vercel AI SDK callers, use the wrapper that returns the AI SDK shape directly:

import { getAiSdkTools } from '@eigenpal/docx-editor-agents/ai-sdk/server';
 
const tools = getAiSdkTools(); // { [name]: Tool } shape, ready for streamText({ tools }).

The React hook returns the same schemas plus an executor:

import { useDocxAgentTools } from '@eigenpal/docx-editor-agents/react';
 
const { tools, executeToolCall } = useDocxAgentTools({ editorRef });

Restricting the surface

useDocxAgentTools accepts include and exclude allow/block lists. A read-only review agent is one line:

useDocxAgentTools({
  editorRef,
  include: ['read_document', 'find_text', 'read_comments'],
});

Comment-only (no edits or formatting):

useDocxAgentTools({
  editorRef,
  exclude: ['suggest_change', 'apply_formatting', 'set_paragraph_style'],
});

Adding custom tools

Custom tools merge with the built-ins. Same-name tools replace the built-in.

useDocxAgentTools({
  editorRef,
  tools: {
    fetch_clause: {
      name: 'fetch_clause',
      description: 'Fetch a clause template by name from your library.',
      inputSchema: {
        type: 'object',
        properties: { name: { type: 'string' } },
        required: ['name'],
      },
      handler: async (input) => ({
        success: true,
        data: await fetchTemplate(input.name as string),
      }),
    },
  },
});