Skip to main content
Glama
UseJunior

safe-docx

by UseJunior
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

replace_text

Destructive

Replace or delete text in a specific paragraph using its ID, preserving formatting across DOCX, ODT, and Google Docs. Tracks changes for review.

Instructions

Replace text in a paragraph by provider paragraph id, preserving formatting where supported. Supports DOCX, ODT, and Google Docs. To delete an ordinary DOCX body paragraph, pass its complete visible text as old_string and an empty new_string; a clean save removes the paragraph and a tracked save keeps the deletion for review. Do not use this shortcut for paragraphs that carry section properties, are structurally required by a table cell, or own bookmark/comment anchors without inspecting the structure first. Surface: revisionable — DOCX edits emit native OOXML tracked changes (w:ins/w:del/w:rPrChange).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_pathNoPath to the DOCX or ODT file.
new_stringYes
old_stringYes
instructionYes
google_doc_idNoGoogle Doc ID or URL (alternative to file_path). Extract from URL: docs.google.com/document/d/{ID}/edit
normalize_firstNoMerge format-identical adjacent runs before searching. Useful when text is fragmented across runs.
target_paragraph_idYesParagraph anchor. Accepts a safe-docx `_bk_*` id, or (DOCX only) any other bookmark name — e.g. a host application's own stable paragraph bookmark — whose w:id-paired range covers exactly this one paragraph. Exact name match; a point bookmark or a multi-paragraph range is refused.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.21.2
    • addedInput schema / properties / target_paragraph_id / description
      Added value: +"Paragraph anchor. Accepts a safe-docx `_bk_*` id, or (DOCX only) any other bookmark name — e.g. a host application's own stable paragraph bookmark — whose w:id-paired range covers exactly this one paragraph. Exact name match; a point bookmark or a multi-paragraph range is refused."
  2. Changed1 schema field changedv0.12.1
    • changedInput schema / properties / file_path / description
      Previous value: -"Path to the DOCX file."New value: +"Path to the DOCX or ODT file."
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: revisionable surface with native OOXML tracked changes (w:ins/w:del/w:rPrChange), the clean-save-deletes vs tracked-save-retains distinction, and the structural hazards that make deletion unsafe. This is exactly the added value annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and supported formats, then layers the deletion shortcut and its caveats, then the revisionable surface note. Dense but every sentence carries operational information; the warning sentence is long but justified by its safety content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description conveys the key post-call behavior (tracked vs clean save outcomes) and the formats supported. It does not describe the response payload shape, which is a minor gap for a mutation tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 57%, and the description adds semantics for old_string/new_string in the deletion shortcut (complete visible text) and mentions the paragraph-id acceptance. However instruction, normalize_first, file_path, and google_doc_id are left to the schema, so the description only partially compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Replace text in a paragraph by provider paragraph id' — plus the scope (formatting preservation, supported formats DOCX/ODT/Google Docs). This clearly distinguishes it from insert_paragraph or batch_edit without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance (replace text by paragraph id), an alternative mechanism (empty new_string to delete a DOCX body paragraph), and explicit when-not-to warnings (section properties, table cell structural paragraphs, bookmark/comment anchors). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools