Skip to main content
Glama

insert_paragraph

Destructive

Insert a paragraph before or after an anchor paragraph by ID, with DOCX tracked changes and support for DOCX, ODT, and Google Docs.

Instructions

Insert a paragraph before/after an anchor paragraph by paragraph id. DOCX responses include structural_warnings when the placement may slice a hierarchy, mismatch list levels, or renumber a list. Supports DOCX, ODT, and Google Docs. ODT paragraph ids remain stable within the session; new paragraphs receive monotonically allocated ids, and reopening renumbers stored document order. Surface: revisionable — DOCX insertions emit native OOXML tracked changes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "positional_anchor_node_id": "<positional_anchor_node_id>",
      "new_string": "<new_string>",
      "instruction": "<instruction>"
    },
    "name": "insert_paragraph"
  }
}

Input Schema

NameRequiredDescriptionDefault
positionNo
file_pathNoPath to the DOCX or ODT file.
new_stringYes
instructionYes
google_doc_idNoGoogle Doc ID or URL (alternative to file_path). Extract from URL: docs.google.com/document/d/{ID}/edit
style_source_idNoParagraph anchor to clone formatting (pPr and template run) from instead of the positional anchor. Accepts a `_bk_*` ID, or (DOCX only) any other bookmark name whose w:id-paired range covers exactly that one paragraph. Falls back to anchor with a warning if not found.
positional_anchor_node_idYesAnchor paragraph. 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. Changed2 schema fields changedv0.21.2
    • addedInput schema / properties / positional_anchor_node_id / description
      Added value: +"Anchor paragraph. 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."
    • changedInput schema / properties / style_source_id / description
      Previous value: -"Paragraph _bk_* ID to clone formatting (pPr and template run) from instead of the positional anchor. Falls back to anchor with a warning if not found."New value: +"Paragraph anchor to clone formatting (pPr and template run) from instead of the positional anchor. Accepts a `_bk_*` ID, or (DOCX only) any other bookmark name whose w:id-paired range covers exactly that one paragraph. Falls back to anchor with a warning if not found."
  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

A3.6/5.0
Behavior4/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing that DOCX responses carry structural_warnings for hierarchy slicing, list-level mismatch, and list renumbering. It also explains revision behavior (native OOXML tracked changes) and the ODT id lifecycle (stable in-session, new ids monotonically allocated, renumbering on reopen). It does not cover permissions or failure modes for missing anchors.

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?

Four dense, front-loaded sentences that each carry distinct information, starting with the core action and placement. Some compression into acronyms (OOXML, structural_warnings) and a run-on final sentence cost it the top mark.

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

Completeness3/5

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

Explains return-side warnings despite having no output schema, which is valuable for a 7-parameter mutation tool. But key gaps remain: the purpose of the required 'instruction' parameter and the file_path vs google_doc_id selection rule are unaddressed, leaving an agent unsure how to satisfy the target of the operation.

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 meaning for the anchor id and the before/after placement. It says nothing about the required 'instruction' parameter, style_source_id, or how file_path and google_doc_id relate (neither appears in the required list), so it 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.

Purpose4/5

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

States a specific verb and resource ('Insert a paragraph') plus the mechanism ('before/after an anchor paragraph by paragraph id'), which is concrete enough to distinguish it from formatting or replacement tools. It does not explicitly contrast itself with siblings such as insert_section_break or replace_text, so it falls short of a 5.

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

Usage Guidelines3/5

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

Usage is implied by the description — you anchor to an existing paragraph id and choose a placement side — and the supported surfaces (DOCX, ODT, Google Docs) are named. However, there is no explicit when-to-use/when-not guidance and no routing to alternative insertion or text-replacement tools.

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