The docx-mcp-server provides 40 local tools for reading, editing, formatting, structuring, reviewing, and managing Word (.docx) documents — no file uploads required.
Reading & Inspection
Read document content with block indices, styles, and formatting hints
Get document metadata (paragraph count, headings, table count, comment status)
Search text with context snippets; list embedded images; inspect paragraph formatting
Read headers/footers, table structure, footnotes, comments (with threaded replies), and page layout
Editing
Find & replace text across the document (including headers/footers), in batch
Edit, insert, or delete paragraphs by index or stable anchor
Edit, insert, or delete paragraphs inside table cells; replace whole cell content across multiple tables in one pass
Formatting
Apply character formatting (bold, italic, underline, strikethrough, font, size, color, highlight) to matching text
Set paragraph-level formatting (alignment, spacing, indentation) for multiple paragraphs at once
Convert paragraphs to headings (levels 1–9) in batch
Document Structure
Insert tables with optional cell data
Create new DOCX files with optional title, content, and style preset
Apply document-wide style presets to existing documents
Track Changes
All editing tools support tracked changes (recorded as Word revisions with author and timestamp)
Accept all tracked changes (insertions become permanent, deletions removed) or reject all (insertions removed, deleted text restored)
Comments & Review
Add single or multiple comments anchored to specific text
Reply to comments for threaded conversations; delete comments by ID
Page Layout
Get or set page size (A3–B5, Letter, Legal, or custom mm), margins (presets or custom mm), and orientation (portrait/landscape)
Stable Anchors
Assign stable w14:paraId anchors to all paragraphs so multi-step edits can target paragraphs without re-reading after each index shift
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docx-mcp-server find 'action items' in meeting_notes.docx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local MCP server for reading and editing Word (.docx) documents. Works with Claude Code, Cursor, and any MCP-compatible client.
40 tools for document content, formatting, comments, page layout, and track changes — all running locally via stdio with no file uploads.
Category | Tools |
Read |
|
Edit |
|
Format |
|
Structure |
|
Review |
|
Track changes |
|
Page layout |
|
Headers/footers |
|
Tables |
|
Footnotes |
|
The editing tools (replace_texts, edit_paragraphs, insert_paragraphs, delete_paragraphs) support tracked changes — edits are recorded as Word revisions (w:ins/w:del) with author and timestamp, so reviewers can accept or reject them in Word.
Track changes is on by default. Pass track_changes: false to make direct edits.
Use read_document with show_revisions: true to see tracked changes annotated as [-deleted-] and [+inserted+]. The default view shows accepted text only.
Use accept_all_changes / reject_all_changes to finalize or revert all pending revisions.
Paragraphs are normally addressed by integer block index, but every insert/delete shifts the indices of later blocks — so a multi-step edit has to re-read after each change. Anchors fix this: an anchor is a stable id (Word's w14:paraId) that stays attached to its paragraph across index shifts.
Run ensure_anchors once to assign anchors to every paragraph and get the full index→anchor map (most Word-authored documents already carry anchors; the call is idempotent).
search_text returns each match's anchor, and read_document with show_anchors: true prints them inline.
The edit tools (edit_paragraphs, delete_paragraphs, set_paragraph_formats, set_headings, insert_paragraphs) accept an anchor (or anchors) as an alternative to paragraph_index. Editing also auto-assigns an anchor to each touched/inserted paragraph and insert_paragraphs returns the new anchors, so a pipeline can keep editing without re-reading.
v1 anchors cover top-level (direct-body) paragraphs; paragraphs inside tables or content controls are not anchored.
get_page_layout / set_page_layout support:
Page size presets: A3, A4, A5, B4, B5, Letter, Legal
Margin presets: Normal, Narrow, Wide, JP Court 25mm, JP Court 30/20mm
Custom values in millimeters for page size and individual margins
Orientation (portrait / landscape)
Related MCP server: docx-mcp
npm install -g @knorq/docx-mcp-serverThen add to your MCP config (see Configuration below).
Just add the config — npx downloads and runs it automatically:
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm link # makes `docx-mcp-server` available globallyAdd to your project's .mcp.json (per-project) or ~/.claude/settings.json (global):
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}Add to your MCP server configuration in Cursor settings:
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}If you built from source and ran npm link:
{
"mcpServers": {
"docx-editor": {
"command": "docx-mcp-server"
}
}
}Or reference the built file directly:
{
"mcpServers": {
"docx-editor": {
"command": "node",
"args": ["/absolute/path/to/docx-mcp-server/dist/index.js"]
}
}
}npm publishRecipients install with:
npm install -g @knorq/docx-mcp-serverOr skip the install entirely — just share the .mcp.json config with the npx setup above and it works out of the box.
Share the repository. Recipients run:
git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm linkThen add the config above.
read_document — Read content with block indices, styles, and formatting hints. Use show_revisions to see tracked changes.
file_path, start_paragraph?, end_paragraph?, show_revisions?get_document_info — Paragraph count, heading outline, table count, comment status.
file_pathsearch_text — Search with context snippets.
file_path, query, case_sensitive?list_images — List all embedded images with filenames, dimensions, alt text, and block indices.
file_pathget_paragraph_format — Introspect a paragraph's formatting (style, heading level, alignment, numbering, indentation in twips, spacing in points). Use it to find a copy_format_from source or debug why two paragraphs render differently. Values match the units set_paragraph_formats accepts.
file_path, paragraph_indexensure_anchors — Assign a stable anchor (w14:paraId) to every top-level paragraph that lacks one and return the index→anchor map. Idempotent. See Stable anchors.
file_pathAll editing tools accept track_changes (default true) and author (default "Claude"). The paragraph tools below accept an anchor (or anchors) in place of paragraph_index for index-shift-proof targeting — see Stable anchors.
replace_texts — Apply one or more find/replace operations in a single open/save cycle. Handles text spanning multiple runs.
Under track_changes: false, items are applied sequentially: a later item can match text produced by an earlier item.
Under track_changes: true (default), the engine rejects overlapping items where item N's search shares text with any earlier item M's replace (in either direction). Tracked sequential replacement cannot safely chain overlapping items — nested w:ins/w:del does not round-trip through reject_all_changes. Workaround: issue separate replace_texts calls (one per item) or use track_changes: false with allow_untracked_edit: true.
file_path, items (array of {search, replace, case_sensitive?}), track_changes?, author?, include_headers_footers?edit_paragraphs — Replace the text content of one or more paragraphs in a single open/save cycle. Target each by paragraph_index or anchor. A \n in new_text is a paragraph break: untracked edits split it into separate paragraphs (each inheriting the original numbering/indentation), tracked edits keep one paragraph and render \n as a soft line break.
file_path, edits (array of {paragraph_index? | anchor?, new_text}), track_changes?, author?insert_paragraphs — Insert one or more paragraphs in one operation. Place each by position (block index) or anchor + placement ("before"/"after"); returns the new paragraphs' anchors. A \n in text is a paragraph break (untracked: one paragraph per line; tracked: soft line break). When several paragraphs share the same position, they land in the document in the reverse of array order — list them back-to-front or use separate calls (anchor placement preserves array order).
file_path, paragraphs (array of {text, position? | (anchor + placement), style?, num_id?, num_level?, copy_format_from?, copy_format_from_anchor?}), track_changes?, author?delete_paragraphs — Delete one or more paragraphs or table blocks in one operation. Target by paragraph_indices (paragraph or table) and/or anchors (paragraph only).
file_path, paragraph_indices?, anchors?, track_changes?, author?format_text — Apply bold, italic, underline, font, size, color, highlight to matching text.
file_path, search, bold?, italic?, underline?, strikethrough?, highlight_color?, font_name?, font_size?, font_color?, case_sensitive?set_paragraph_formats — Apply alignment, spacing, indentation to one or more paragraphs in one operation. Each group targets paragraphs by indices and/or anchors and bundles the formatting to apply to them.
file_path, groups (array of {indices?, anchors?, alignment?, space_before?, space_after?, line_spacing?, indent_left?, indent_right?, first_line_indent?, hanging_indent?})highlight_text — Highlight matching text with a color.
file_path, search, color?, case_sensitive?set_headings — Convert one or more paragraphs to headings (level 1-9) in one operation. Target each by paragraph_index or anchor.
file_path, headings (array of {paragraph_index? | anchor?, level})insert_table — Insert a table with optional cell data.
file_path, position, rows, cols, data?create_document — Create a new .docx file with optional title, content, and style preset.
file_path, title?, content?, preset?By default create_document keeps the generated document generic. If you want a Japanese business-document starting point, pass preset: "ja-business" to seed styles.xml with Yu Gothic body text, 11pt sizing, roomier paragraph spacing, and less cramped heading spacing.
apply_document_preset — Apply a document-wide style preset in one pass by updating styles.xml.
file_path, presetUse this when you want to restyle an existing document without repeated format_text calls per paragraph. The preset rewrites docDefaults and the Heading 1–Heading 3 styles; an existing Normal style and other custom styles are preserved.
add_comment — Anchor a comment to specific text.
file_path, anchor_text, comment_text, author?add_comments — Add multiple comments in one operation. Supports partial success.
file_path, comments (array of {anchor_text, comment_text, author?}), default_author?read_comments — List all comments with IDs, authors, text, and threaded replies.
file_pathreply_to_comment — Reply to an existing comment, creating a threaded conversation.
file_path, parent_comment_id, comment_text, author?delete_comment — Remove a comment by ID.
file_path, comment_idaccept_all_changes — Accept all tracked changes. Insertions become permanent, deletions are removed.
file_pathreject_all_changes — Reject all tracked changes. Insertions are removed, deleted text is restored.
file_pathget_page_layout — Read page size, margins, orientation.
file_pathset_page_layout — Set page size, margins, orientation by preset or custom mm values.
file_path, page_size_preset?, orientation?, width_mm?, height_mm?, margin_preset?, top_mm?, right_mm?, bottom_mm?, left_mm?, header_mm?, footer_mm?, gutter_mm?read_header_footer — Read the text content of all headers and footers.
file_pathread_table_structure — Inspect a table without reading the whole document: row/column dimensions and a short preview of every cell, plus each cell's merge info (gridSpan / vMerge). Indices are physical w:tc positions, matching read_table_cell / edit_table_cells.
file_path, block_indexread_table_cell — Read a single cell's paragraphs (text + style/alignment/numbering) and merge info, without reading the whole document.
file_path, block_index, row_index, col_indexedit_table_cells — Replace the text content of one or more table cells in a single open/save cycle. Cells can span different tables. A \n in new_text is a paragraph break: untracked edits replace the whole cell, turning each line into its own paragraph (so re-editing leaves no stale lines); tracked edits diff-replace the cell's first paragraph and render \n as a soft line break.
file_path, edits (array of {block_index, row_index, col_index, new_text}), track_changes?, author?edit_table_paragraphs — Edit one specific paragraph inside a cell (cell-local paragraph_index) without replacing the whole cell. For surgically changing a single line of a multi-paragraph cell (e.g. one numbered-list item).
file_path, edits (array of {block_index, row_index, col_index, paragraph_index, new_text}), track_changes?, author?delete_table_paragraphs — Delete one specific paragraph inside a cell. Keeps a blank paragraph if the deleted one was the cell's last (so the cell stays valid); real Word numbering renumbers the rest automatically.
file_path, targets (array of {block_index, row_index, col_index, paragraph_index}), track_changes?, author?insert_table_paragraphs — Insert a paragraph inside a cell at a cell-local position (-1/out-of-range appends). Supports num_id/num_level and copy_format_from (a paragraph index within the same cell).
file_path, inserts (array of {block_index, row_index, col_index, position, text, style?, num_id?, num_level?, copy_format_from?}), track_changes?, author?read_footnotes — Read all footnotes with their IDs and text content.
file_pathAI agents can manipulate DOCX via raw Python (python-docx), but MCP tools are significantly more token-efficient:
Metric | MCP tools | Raw Python |
Output tokens per operation | 65–95% less | Baseline (agent must generate full code) |
Cost per operation | 55–90% less | Baseline |
Break-even | 3–5 operations | — |
Debug iterations | None (validated inputs) | ~1.5 retries/task on average |
Task | MCP | Python (python-docx) | Savings |
Read paragraphs 0–20 | ~18 | ~52 (open, iterate, print) | 65% |
Search and replace text | ~16 | ~67 (iterate paragraphs, run traversal) | 76% |
Add tracked change (insert) | ~32 | ~326 (build w:ins/w:del XML, datetime, author, run properties) | 90% |
Add comment anchored to text | ~26 | ~575 (comment part, anchor markers, relationship, XML manipulation) | 95% |
Format text (bold + color) | ~20 | ~478 (find runs, split at boundaries, apply rPr) | 96% |
Set paragraph format (3 paragraphs) | ~30 | ~80 (load, resolve indices, set properties, save) | 63% |
Composite: read → search → edit → comment | ~120 | ~1,000 | 88% |
The savings are especially large for tracked changes, comments, and run-level formatting — python-docx has no built-in API for track changes or comments, and text formatting requires complex run-splitting logic. The agent must generate raw OOXML manipulation code (~300–575 output tokens per operation). MCP tools handle this internally with a simple parameter call.
Simple read and paragraph-format operations see smaller savings (~63–76%) since python-docx has clean APIs for these.
Output tokens cost 5× more than input tokens, so eliminating code generation has an outsized cost impact. The one-time schema overhead (~2,500 tokens for 40 tools) pays for itself in 3–5 operations.
Node.js 20+
MIT
Accept all tracked changes in the document. Insertions become permanent text, deletions are removed.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the behavioral outcome (insertions become permanent, deletions removed) but lacks details on irreversibility, permissions, or side effects. Without annotations, the description carries the burden but is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core action. However, it could include a brief usage hint without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essential effects on insertions and deletions. Missing is mention of error conditions or prerequisite (file must have changes), but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage for the only parameter (file_path), the description adds no extra meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Accept all tracked changes in the document.' It specifies the effects on insertions and deletions, making it distinct from sibling tools like reject_all_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., document must have tracked changes) or exclusions (e.g., not for selective acceptance).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to specific text in the document. The comment is anchored to the first occurrence of the anchor text.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| anchor_text | Yes | Text to attach the comment to (must exist in the document) | |
| comment_text | Yes | The comment content | |
| author | No | Comment author name | Claude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden for behavioral disclosure. It reveals one key behavior (anchoring to first occurrence) but omits others such as mutability, error handling (if anchor not found), and whether comments are inline or separate. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no redundant words. The core action and unique behavior are front-loaded in the first sentence, making it immediately clear. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the basic purpose but lacks completeness about return values, error scenarios, and prerequisites. A sentence about what the tool returns or what happens if anchor_text lacks would make it more complete. As is, it is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description is not required to explain parameters. It adds minimal extra context about 'anchoring' which relates to anchor_text, but the schema already describes anchor_text as 'Text to attach the comment to'. Thus, the description provides no significant added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment') and the specific target ('to specific text in the document'), and includes a unique behavior ('anchored to the first occurrence of the anchor text'). This distinguishes it from siblings like 'add_comments' and 'reply_to_comment', which may have different anchoring or scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'add_comments' (plural) or 'reply_to_comment'. There is no mention of prerequisites (e.g., document must exist) or scenarios where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add multiple comments to a document in a single operation. Opens and saves the file only once. Supports partial success: comments with unfound anchors are reported as failures without blocking the rest.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| comments | Yes | Array of comments to add | |
| default_author | No | Default author name for comments without an explicit author | Claude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses key behaviors: batched operation (open/save once) and partial success handling for unfound anchors. Without annotations, this transparency is essential and well-provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences with no superfluous words. Every sentence adds value: purpose, optimization, and failure handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers the essential return behavior (partial success reporting). It fully explains the tool's operation for a batch comment-adding tool with no missing critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage). The description adds no additional semantic meaning to the parameters; it focuses on behavioral aspects. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds multiple comments in a single operation, distinguishing it from the sibling 'add_comment' tool that likely adds one comment at a time. The verb 'add' and resource 'comments' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for adding multiple comments efficiently, but does not explicitly state when to use it versus 'add_comment' or other alternatives. It provides context on batch behavior and partial success, which aids decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a named document style preset in one pass by updating styles.xml. Use this instead of repeated paragraph-level formatting when you want a document-wide baseline.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| preset | Yes | Preset name. 'ja-business' applies Yu Gothic body defaults plus roomier paragraph and heading spacing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'in one pass by updating styles.xml', implying modification of document styles but doesn't disclose side effects like overwriting existing styles or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with action and purpose, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers purpose, usage, and preset details adequately. No gaps given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds value by explaining the 'preset' parameter with specific details (e.g., 'ja-business' applies Yu Gothic body defaults plus spacing) beyond the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Apply a named document style preset' and explicitly distinguishes from siblings like set_paragraph_formats by recommending it 'instead of repeated paragraph-level formatting' for 'document-wide baseline'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance to use instead of repeated paragraph-level formatting for document-wide baseline. Could be improved by noting when not to use (e.g., selective formatting), but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new DOCX file. Optionally provide initial content and title.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path where the new .docx file will be created | |
| title | No | Document title (added as Heading 1) | |
| content | No | Initial text content. Use newlines to separate paragraphs. | |
| preset | No | Optional style preset. 'ja-business' applies Japanese business-document defaults such as Yu Gothic body text and roomier paragraph spacing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states 'create' (write operation) but fails to disclose whether existing files are overwritten, required permissions, or any side effects, leaving the agent uninformed about critical behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 12 words, efficiently conveys core purpose and optional parameters. Slightly more structure (e.g., listing optional params) could improve readability, but current form is adequate and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (1 required) and no output schema, the description is minimally complete for basic usage but lacks details on return values, error handling, or file overwrite behavior. Provides enough for simple creation but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% parameter description coverage, so baseline is 3. The description merely echoes 'initial content and title' from schema without adding new context. The optionality is implied but schema already specifies file_path as required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates a new DOCX file and optionally accepts initial content and title. It distinguishes from sibling tools that are primarily editing, commenting, or formatting operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. While it is the only creation tool among siblings, the description does not provide context on prerequisites, when not to use it, or alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment by its ID. Also removes range markers from the document.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| comment_id | Yes | Comment ID to delete (from read_comments) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions the side effect of removing range markers, but lacks details on permanence, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no wasted words. Information is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description covers the main action and a side effect. But it lacks information about success/failure outcomes and potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds minimal value beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a comment by its ID' with verb and resource, and mentions a specific side effect. Distinguishes from sibling tools like read_comments and add_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The description implies deletion, but does not differentiate from rejecting all changes or other tools that may affect comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple paragraphs or table blocks by their indices in one operation. Handles index reordering internally.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| paragraph_indices | Yes | Array of block indices to delete | |
| track_changes | No | Record deletions as tracked changes instead of removing the paragraphs. Default true. | |
| author | No | Author name for tracked changes | Claude |
| allow_untracked_edit | No | Capability flag required to disable tracked changes. When track_changes is false, this must also be true or the call fails with UNTRACKED_EDIT_NOT_ALLOWED. Default false. This is a safety guard against prompt injection or long-context drift in regulated-industry use — silent edits to legal/regulated documents must be opted into with two independent flags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses internal index reordering but omits details about permissions, error handling, or side effects. The mention of tracked changes in parameter descriptions is present but not in the main description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with action and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations. Description hints at batch deletion and index reordering but misses return values, error cases, and when to prefer tracked vs untracked mode. Adequate but incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by noting 'handles index reordering internally' which is not in the schema, and implies batch operation. However, it doesn't elaborate beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes multiple paragraphs or table blocks by indices in one operation, with specific verb (delete) and resource (paragraphs or table blocks). It distinguishes from sibling tools like edit_paragraphs by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like edit_paragraphs or insert_paragraphs. It lacks when-not-to-use or explicit alternative naming, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the text content of multiple paragraphs in one operation. Opens and saves the file only once. Paragraph indices remain stable because edits don't change paragraph count.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| edits | Yes | Array of paragraph edits | |
| track_changes | No | Record edits as tracked changes (w:del/w:ins). Default true. | |
| author | No | Author name for tracked changes | Claude |
| allow_untracked_edit | No | Capability flag required to disable tracked changes. When track_changes is false, this must also be true or the call fails with UNTRACKED_EDIT_NOT_ALLOWED. Default false. This is a safety guard against prompt injection or long-context drift in regulated-industry use — silent edits to legal/regulated documents must be opted into with two independent flags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the file is opened and saved only once and that indices remain stable. However, it does not mention error conditions, permission requirements, or confirmation that edits are saved. The behavioral traits are minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, both front-loaded with key information: the operation type and a critical behavioral detail (index stability). Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers the essential operational context (batch, stability). It does not explain default parameters or order of edits, but given the schema richness, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no new parameter semantics beyond summarizing the operation. The schema already documents parameters like track_changes and allow_untracked_edit in detail, so the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replaces text content of multiple paragraphs in one operation, with a specific verb and resource. It distinguishes itself from siblings by emphasizing batch operation and stable indices, which is unique among sibling tools like edit_table_cells or replace_texts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the benefit of batch operation and index stability, implying when to use it (for multiple paragraph replacements). However, it does not explicitly state when not to use it or mention alternatives like insert_paragraphs or delete_paragraphs for altering paragraph count.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the text content of multiple table cells in one operation. Cells can span different tables. Opens and saves the file only once.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| edits | Yes | Array of cell edits | |
| track_changes | No | Record edits as tracked changes. Default true. | |
| author | No | Author name for tracked changes | Claude |
| allow_untracked_edit | No | Capability flag required to disable tracked changes. When track_changes is false, this must also be true or the call fails with UNTRACKED_EDIT_NOT_ALLOWED. Default false. This is a safety guard against prompt injection or long-context drift in regulated-industry use — silent edits to legal/regulated documents must be opted into with two independent flags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially addresses behavior by mentioning the open/save optimization. However, it omits details on error handling, permissions, or side effects beyond replacing text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Every sentence adds value with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description covers the main behavior but lacks context on use cases, tracked changes behavior beyond schema, and comparison to sibling tools for similar tasks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 is appropriate. The description does not add meaning beyond the schema's parameter descriptions; it only summarizes the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (replace text), the resource (multiple table cells), and the efficiency benefit (one operation, opens/saves once). It distinguishes from siblings like edit_paragraphs or replace_texts by specifying table cells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies efficiency for bulk edits across tables but does not explicitly state when to use this tool over alternatives or when not to use it. No exclusions or comparisons to sibling tools provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply character formatting (bold, italic, underline, highlight, font, size, color) to all runs matching the search text.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| search | Yes | Text to find and format | |
| bold | No | Set bold (true/false) | |
| italic | No | Set italic (true/false) | |
| underline | No | Set underline (true/false) | |
| strikethrough | No | Set strikethrough (true/false) | |
| highlight_color | No | Highlight color: yellow, green, cyan, magenta, blue, red, etc. | |
| font_name | No | Font family name | |
| font_size | No | Font size in points (e.g. 12) | |
| font_color | No | Font color as hex (e.g. 'FF0000' for red) | |
| case_sensitive | No | Case-sensitive text matching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It lacks details on side effects (overwriting existing formatting), scope (global vs selection), and return behavior. For a complex tool with 11 parameters, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. No wasted words, but could be slightly more descriptive (e.g., specifying 'all instances' explicitly). Concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, no output schema, and no annotations, the description is too brief. It fails to explain behavior, error conditions, or return value. Not complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The tool description lists formatting options but adds no extra meaning beyond the schema. Baseline 3 is appropriate; marginal value from listing types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool applies character formatting (bold, italic, underline, etc.) to all runs matching search text. It uses specific verbs and resource (formatting text runs) and distinguishes from siblings like set_paragraph_formats (paragraph-level) and replace_texts (replacement).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for formatting specific text occurrences but does not provide explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. Sibling tools exist (e.g., highlight_text), but no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata and structure overview of a DOCX file — paragraph count, headings outline, tables, comment count.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the tool retrieves data without mentioning side effects or behavioral traits. Basic transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key info, no wasted words. Highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the return values adequately (paragraph count, headings, tables, comment count). Slight lack of completeness but sufficient for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for file_path. Description does not add meaning beyond what schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'get' and resource 'metadata and structure overview of a DOCX file', listing specific outputs like paragraph count, headings outline, tables, and comment count. It distinguishes from siblings like read_document and other analytical tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like read_document or search_text. The description implies usage for structure overview but misses direct when-to-use or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get page size, margins, and orientation of a DOCX file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states what the tool does but does not disclose behavioral traits like being read-only (non-destructive) or any side effects. The behavior is straightforward but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant information, and directly conveys the tool's purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool returns (page size, margins, orientation) for a DOCX file. However, lacking an output schema, it could specify the format or units of the returned values. Still, for a simple tool, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for file_path. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and specifies the resources: 'page size, margins, and orientation' of a DOCX file, which distinguishes it from sibling tools like set_page_layout and read_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving layout properties, but does not provide explicit guidance on when to use this tool vs alternatives (e.g., it is read-only, while set_page_layout writes). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Highlight all occurrences of text with a specified color.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| search | Yes | Text to highlight | |
| color | No | Highlight color: yellow, green, cyan, magenta, blue, red, etc. | yellow |
| case_sensitive | No | Case-sensitive matching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states it highlights text but does not disclose that it modifies the file (destructive action), potential side effects, or any performance implications. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity (4 params, 2 required), the description is too brief. It does not mention default behaviors (color default 'yellow'), that all occurrences are highlighted, or any return value. Incomplete for informed agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 100% and all parameters are described in the schema, baseline is 3. The description adds no extra meaning beyond the schema, merely summarizing the action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Highlight'), the resource ('all occurrences of text'), and the parameter ('with a specified color'). It effectively distinguishes from siblings like 'replace_texts' or 'format_text'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'search_text' or 'format_text'. It does not mention prerequisites (e.g., file must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert multiple paragraphs in one operation. Handles index shifting internally by processing in reverse order. Opens and saves the file only once. Supports numbering (num_id/num_level) and format copying (copy_format_from).
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| paragraphs | Yes | Array of paragraphs to insert | |
| track_changes | No | Record insertions as tracked changes. Default true. | |
| author | No | Author name for tracked changes | Claude |
| allow_untracked_edit | No | Capability flag required to disable tracked changes. When track_changes is false, this must also be true or the call fails with UNTRACKED_EDIT_NOT_ALLOWED. Default false. This is a safety guard against prompt injection or long-context drift in regulated-industry use — silent edits to legal/regulated documents must be opted into with two independent flags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It discloses index shifting via reverse order processing, single open/save optimization, and behavior of parameters like copy_format_from overriding style/num_id/num_level. It also explains the allow_untracked_edit safety guard against prompt injection. Minor omissions: no mention of error cases or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. First sentence states purpose, second details internal behavior, third lists supported features. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the tool is an insert operation so return is likely success/failure. Description covers key aspects: insertion behavior, indexing, parameter interactions, and safety features. For a tool with 5 parameters, it addresses critical points. Could mention return value, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaningful context beyond the schema: it explains that copy_format_from overrides style/num_id/num_level, and that allow_untracked_edit is a safety guard against prompt injection. It also clarifies internal index shifting. This adds value over the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool inserts multiple paragraphs in one operation, with specifics about index shifting, single open/save, and supported features like numbering and format copying. It distinguishes itself from sibling tools like delete_paragraphs or edit_paragraphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (insert multiple paragraphs) and internal handling (reverse order), but does not provide explicit when-not-to-use guidance or mention alternatives like edit_paragraphs for modifications. Sibling tools exist but no comparison is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a table at a specific position in the document.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| position | Yes | Block index to insert before (-1 for end) | |
| rows | Yes | Number of rows | |
| cols | Yes | Number of columns | |
| data | No | Optional 2D array of cell values, e.g. [['A1','B1'],['A2','B2']] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether the table overwrites existing content, shifting of text, permissions required, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, but lacks any structured detail. Could benefit from a second sentence explaining the position parameter or data usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 5 parameters, the description is too minimal. It doesn't explain the return value, how the position index works, or how data is used. Not complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema (only 'at a specific position' is slightly redundant with the position parameter description).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a table at a specific position in a document, using a specific verb and resource. It distinguishes from siblings like edit_table_cells or insert_paragraphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like insert_paragraphs or edit_table_cells. No conditions or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all images embedded in a DOCX file. Returns filename, dimensions, alt text, and block index for each image.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as error handling (e.g., file not found, no images), whether it modifies the file, or any permissions needed. It only states what it returns, leaving behavior largely unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff, front-loading the action and result. Every word is necessary and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description provides a complete picture of purpose and return data. Minor gaps like edge-case behavior are expected but do not significantly detract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (file_path description is clear). The tool description adds no additional meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all images in a DOCX file and specifies the return fields (filename, dimensions, alt text, block index). This distinguishes it from sibling tools that focus on editing, comments, or text extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when or when not to use this tool versus alternatives like read_document or search_text. The context of siblings implies its specific purpose, but no exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all comments in a DOCX file. Shows threaded replies indented under parent comments when available.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses showing threaded replies and implies read-only behavior, but lacks details on side effects, permissions, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Every word serves a purpose: the action, the resource, and a key behavioral detail (threaded replies).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with one parameter, no output schema, and many siblings, the description adequately covers purpose and key feature. It could mention that it does not modify the document, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'file_path'. The description adds no additional meaning beyond the schema's description ('Absolute path to the .docx file'), so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read all comments'), the resource ('a DOCX file'), and adds distinguishing detail about threaded replies. This differentiates it from siblings like add_comment and reply_to_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., read_document, search_text). There are no mentions of prerequisites, when not to use, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a DOCX file. Returns paragraphs with indices, styles, and formatting hints. Use start_paragraph/end_paragraph for large documents. Use show_revisions to see tracked changes annotations.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| start_paragraph | No | Start reading from this block index (inclusive) | |
| end_paragraph | No | Stop reading at this block index (exclusive) | |
| show_revisions | No | Show tracked changes with annotations: [-deleted-] and [+inserted+]. Default false shows accepted text only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return format (paragraphs with indices, styles, formatting hints) and behavior of optional parameters. No annotations exist, so description carries the burden; it adequately discloses non-destructive, read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words: first sets purpose and return format, second and third give essential usage tips. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description covers main function, return format, and optional parameters' purpose. Could mention output format (e.g., JSON) but sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover 100% of parameters clearly. The description adds usage context (e.g., 'for large documents') beyond the schema, enhancing understanding of when to use optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a DOCX file and returns structured paragraph data, distinguishing it from sibling tools that modify or manage documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using start_paragraph/end_paragraph for large documents and show_revisions for tracked changes, providing clear when-to-use guidance for optional parameters. Does not contrast with sibling read tools, but still helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all footnotes in a DOCX file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether endnotes are included, how empty files are handled, or the format of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, but could be slightly more structured (e.g., adding a note about return value).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally adequate. However, it lacks details about what 'read all footnotes' returns (e.g., text, formatting), which siblings like read_comments might provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (file_path is described). The description does not add additional meaning beyond the schema, but baseline 3 is appropriate given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'read' and the resource 'footnotes within a DOCX file', distinguishing it from siblings like read_comments and read_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., read_comments for comments, read_document for body text). No 'when not to use' advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reject all tracked changes in the document. Insertions are removed, deletions are restored to normal text.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses basic behavior (removing insertions, restoring deletions) but lacks details on irreversibility, prerequisites (e.g., tracked changes must exist), or side effects. Without annotations, the description should provide more depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action and immediately explain the effects. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a simple purpose and no output schema, the description is adequate but could mention that it only applies to documents with tracked changes and that the action is irreversible. The lack of such context slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'file_path' is fully described in the schema (100% coverage). The description adds no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (reject all tracked changes) and specifies the effects on insertions and deletions, distinguishing it from the sibling 'accept_all_changes'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'accept_all_changes' or other document editing tools. The agent must infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply one or more find/replace operations in a single open/save cycle. Use a one-element items array for a single substitution; use multiple items to batch many substitutions efficiently. Items are applied sequentially in the given order.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| items | Yes | Array of find/replace pairs, applied sequentially in the given order. Under track_changes=false, a later item can match against text produced by an earlier item (e.g. alpha→beta then beta→gamma yields gamma). Under track_changes=true, the engine rejects overlapping items (where item N's search matches item M's replace, M<N) with INVALID_PARAMETER — issue separate replace_texts calls instead. | |
| track_changes | No | Record edits as tracked changes (w:del/w:ins). Default true. | |
| author | No | Author name for tracked changes | Claude |
| allow_untracked_edit | No | Capability flag required to disable tracked changes. When track_changes is false, this must also be true or the call fails with UNTRACKED_EDIT_NOT_ALLOWED. Default false. This is a safety guard against prompt injection or long-context drift in regulated-industry use — silent edits to legal/regulated documents must be opted into with two independent flags. | |
| include_headers_footers | No | Also replace text in headers and footers. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses sequential application, interaction with track_changes, overlapping item rejection, and the safety guard for allow_untracked_edit, which is critical for regulated industries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with main purpose, followed by usage details. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no output schema, the description covers all behavioral aspects: track_changes options, sequential application, headers/footers, and safety flag. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds meaning by explaining the sequential application logic for items and the safety guard for allow_untracked_edit, going beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Apply one or more find/replace operations'. It clearly distinguishes from sibling tools like search_text (which only searches) and format_text (which formats).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on using a one-element vs multiple items, and explains sequential application and overlapping item handling with track_changes. Lacks explicit alternatives but provides clear context for efficient batching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an existing comment, creating a threaded conversation. The reply appears under the parent comment in Word's comment pane.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| parent_comment_id | Yes | ID of the parent comment to reply to (from read_comments) | |
| comment_text | Yes | The reply content | |
| author | No | Reply author name | Claude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the reply appears under the parent comment and creates a threaded conversation, but it does not disclose other behavioral traits such as whether the document is auto-saved, if the reply is immediately visible, or any side effects. Since no annotations are provided, the description carries the full burden and could be more detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short, front-loaded sentences. Every word adds value, explaining exactly what the tool does and where the result appears. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the basic purpose and behavior but omits details about the return value (e.g., success indication or reply ID), error conditions, or prerequisite state (e.g., document must be open). It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all 4 parameters (100% coverage). The description adds no additional semantic value beyond the schema's own descriptions, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reply to an existing comment') and the resource ('comment'). It explains the result ('creating a threaded conversation', 'appears under the parent comment') and distinguishes from siblings like 'add_comment' (which likely adds a new top-level comment) and 'read_comments'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for replying to an existing comment (i.e., you need a parent comment ID), but it does not explicitly state when to use this tool versus alternatives like 'add_comment' for new top-level comments or 'delete_comment'. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for text in a DOCX file. Returns matching blocks with context.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| query | Yes | Text to search for | |
| case_sensitive | No | Case-sensitive search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only vaguely states 'Returns matching blocks with context', without specifying whether the tool is read-only, what 'blocks' refer to, or any side effects. More behavioral detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (12 words, one sentence). It is front-loaded with the core purpose. However, it could include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 3 parameters and no output schema, the description hints at the return value but is vague ('blocks with context'). It is adequate but not fully complete, as it does not describe the format or granularity of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what is already in the parameter descriptions. No param-specific clarifications are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'text in a DOCX file', and the output 'matching blocks with context'. It distinguishes from siblings like read_document or highlight_text, as those are not search-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives (e.g., reading the whole document or using highlight_text). Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert multiple paragraphs to headings in one operation. Opens and saves the file only once.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| headings | Yes | Array of heading assignments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It reveals the tool opens and saves the file automatically, implying mutation. This is good transparency, though it could mention error handling or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The core action is front-loaded. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or error handling mentioned. The agent knows input parameters but not return value or failure modes. For a mutation tool with two params, it's minimally adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds minimal value beyond the schema—only emphasizing 'multiple paragraphs' which is already an array in the schema. No extra constraints or clarifications are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts multiple paragraphs to headings in one operation. It is specific about the action (convert to headings) and distinguishes itself from sibling tools like edit_paragraphs that might edit content but not specifically set headings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over alternatives. The description implies batch efficiency but does not mention prerequisites or cases where one should avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set page size, margins, and orientation. Use presets (A4, LETTER, NARROW, etc.) or custom values in millimeters.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| page_size_preset | No | Page size preset: A3, A4, A5, B4, B5, LETTER, LEGAL | |
| orientation | No | Page orientation | |
| width_mm | No | Custom page width in millimeters (overrides preset) | |
| height_mm | No | Custom page height in millimeters (overrides preset) | |
| margin_preset | No | Margin preset: NORMAL, NARROW, WIDE, JP_COURT_25, JP_COURT_30_20 | |
| top_mm | No | Top margin in mm | |
| right_mm | No | Right margin in mm | |
| bottom_mm | No | Bottom margin in mm | |
| left_mm | No | Left margin in mm | |
| header_mm | No | Header distance in mm | |
| footer_mm | No | Footer distance in mm | |
| gutter_mm | No | Gutter margin in mm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states the tool 'sets' layout properties, implying overwriting, but does not disclose side effects, permission needs, or behavior when partial parameters are provided. The description is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action and key details. No extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters and no output schema, the description adequately covers the main purpose but omits practical details like optionality of parameters (except file_path), precedence of custom values over presets, and return value. It is sufficient for a simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds marginal value by clarifying that presets apply to page size and margins and that custom values are in millimeters, but it does not elaborate on interactions between presets and custom parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'page size, margins, and orientation', effectively distinguishing the tool as a write operation for page layout. It also mentions both presets and custom values, providing clarity on capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning presets and custom values, but it does not explicitly specify when to use this tool versus alternatives like apply_document_preset. No exclusions or comparative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply alignment, spacing, and indentation to one or more paragraphs in a single open/save cycle. Each group bundles a list of paragraph indices with the formatting to apply to them.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| groups | Yes | Array of formatting groups, each with indices and format options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It mentions 'single open/save cycle' implying efficiency, but it does not disclose whether existing formatting is overwritten or merged, nor does it discuss error handling, permission requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each carrying essential information: the action and the grouping mechanism. There is no redundancy or extraneous text, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is minimally sufficient for a file modification tool. However, it lacks context about file prerequisites (e.g., file must exist, be openable) and what the tool returns upon success or failure, leaving some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter's meaning. The description adds no new semantic details about parameters beyond the schema, but it does contextualize the 'groups' structure. This meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies alignment, spacing, and indentation to paragraphs, and introduces the concept of groups with indices. This makes the purpose specific and distinct from siblings like 'edit_paragraphs' or 'format_text' which operate on individual paragraphs or text runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. For example, it does not specify that this should be used for batch formatting or when you need efficiency via a single open/save cycle, nor does it mention when to prefer 'edit_paragraphs' for finer-grained control.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.1.0accept_all_changesadd_commentadd_commentsapply_document_presetcreate_documentdelete_commentdelete_paragraphsedit_paragraphsedit_table_cellsformat_textget_document_infoget_page_layouthighlight_textinsert_paragraphsinsert_tablelist_imagesread_commentsread_documentread_footnotesread_header_footerreject_all_changesreplace_textsreply_to_commentsearch_textset_headingsset_page_layoutset_paragraph_formatsScored across 27 tools
Each tool targets a distinct operation on the document—creating, reading, editing paragraphs/tables, formatting, comments, changes, footnotes, headers/footers, and images. There is no functional overlap; even similarly named tools like format_text and highlight_text apply different types of formatting.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_document, edit_paragraphs, set_page_layout). Minor plural/singular variation (add_comment vs. add_comments) is clear and intentional, not a deviation.
With 27 tools, the server is on the high end for an MCP server. While each tool serves a distinct purpose for a comprehensive document editor, the count exceeds the typical 3-15 range and falls into the 'heavy' category, warranting a borderline score.
The server covers major areas: document creation, reading, editing paragraphs/tables, formatting, comments (CRUD plus threading), changes (accept/reject), search/replace, images, footnotes, and headers/footers. Minor gaps exist: footnotes and headers/footers are read-only, and there is no image insertion or deletion.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
MCP server for manus documentation, generated by doc2mcp.
MCP server for opencode documentation, generated by doc2mcp.
