Skip to main content
Glama
UseJunior

safe-docx

by UseJunior
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

save

Destructive

Persist an in-memory document session as DOCX, ODT, or Google Docs output, writing clean and/or tracked changes and returning revision checkpoint details.

Instructions

Persist the current in-memory document session. For DOCX: saves clean and/or tracked changes output. For ODT: saves an .odt package. For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX. Surface: revisionable — the save report lists both the AI revisions applied and a non-revision change manifest of any package-level mutations (comment/footnote side parts, relationships) that have no tracked-change wrapper.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_pathNoPath to the DOCX or ODT file.
save_formatNo
google_doc_idNoGoogle Doc ID or URL (alternative to file_path). Extract from URL: docs.google.com/document/d/{ID}/edit
allow_overwriteNo
clean_bookmarksNoControls removal of internal bookmarks from DOCX output. Behavior is intentionally three-way: OMIT (recommended for tracked/persistence saves) preserves the document's own bookmarks — only safe-docx paragraph anchors (`_bk_*`) are removed. Explicit `true` ALSO strips harness edit-span bookmarks (`edit-*`) to produce a clean deliverable; do NOT pass it when the tracked output feeds a redline pipeline, because that reproduces the pre-#609 loss of `edit-*` anchors. `false` keeps all bookmarks. Omitting is NOT equivalent to passing `true` — they differ precisely in whether original `edit-*` bookmarks survive.
save_to_local_pathYes
tracked_changes_authorNo
tracked_changes_engineNoDeprecated and ignored (#126). The redline is now the session's write-time tracked markup, serialized directly — there is no comparison engine to select. Use the compare_documents tool for comparison-based redlines.
fail_on_rebuild_fallbackNoDeprecated and ignored (#126). The default save no longer runs the comparison reconstruction engine, so there is no rebuild fallback to guard against; accepted for backward compatibility only.
tracked_save_to_local_pathNo
allow_discard_preserved_revisionsNoExplicitly allow a clean artifact to auto-accept remaining revisions by the session AI author after accept_ai_edits/reject_ai_edits selectively left revisions unresolved. Default: false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.21.2
    • addedInput schema / properties / allow_discard_preserved_revisions
      Added value: +{
+  "description": "Explicitly allow a clean artifact to auto-accept remaining revisions by the session AI author after accept_ai_edits/reject_ai_edits selectively left revisions unresolved. Default: false.",
+  "type": "boolean"
+}
    • addedInput schema / properties / clean_bookmarks / description
      Added value: +"Controls removal of internal bookmarks from DOCX output. Behavior is intentionally three-way: OMIT (recommended for tracked/persistence saves) preserves the document's own bookmarks — only safe-docx paragraph anchors (`_bk_*`) are removed. Explicit `true` ALSO strips harness edit-span bookmarks (`edit-*`) to produce a clean deliverable; do NOT pass it when the tracked output feeds a redline pipeline, because that reproduces the pre-#609 loss of `edit-*` anchors. `false` keeps all bookmarks. Omitting is NOT equivalent to passing `true` — they differ precisely in whether original `edit-*` bookmarks survive."
  2. Changed2 schema fields changedv0.16.0
    • changedInput schema / properties / fail_on_rebuild_fallback / description
      Previous value: -"When true, return an error instead of a destructive output if the comparison engine falls back to rebuild mode (which destroys table structure). Default: false."New value: +"Deprecated and ignored (#126). The default save no longer runs the comparison reconstruction engine, so there is no rebuild fallback to guard against; accepted for backward compatibility only."
    • addedInput schema / properties / tracked_changes_engine / description
      Added value: +"Deprecated and ignored (#126). The redline is now the session's write-time tracked markup, serialized directly — there is no comparison engine to select. Use the compare_documents tool for comparison-based redlines."
  3. 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."
  4. First observed

TDQS

A3.6/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description goes well beyond that by disclosing the "revisionable" surface and the contents of the save report (AI revisions plus a non-revision change manifest of package-level mutations with no tracked-change wrapper). That is genuine behavioral context an agent could not infer. It omits any warning about the destructive overwrite path despite allow_overwrite existing, which keeps it out of the top tier.

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?

The core purpose is front-loaded in the first sentence, followed by format-specific behavior and then the save-report contract. It is dense and jargon-heavy ("non-revision change manifest of any package-level mutations") but every sentence carries distinct information with little redundancy.

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?

With 11 parameters, no output schema, no title, and only safety annotations, the description does useful work by describing the save report in place of a return schema and covering all three target formats. It still leaves the relationship among file_path, save_to_local_path, tracked_save_to_local_path, and allow_overwrite unresolved, which is a meaningful gap for a destructive write tool with this many inputs.

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 description coverage is 55%, so the schema already carries substantial parameter documentation (notably the very detailed clean_bookmarks field). The description adds only indirect meaning, mapping "clean and/or tracked" to the save_format options, and leaves key parameters like allow_overwrite, file_path vs save_to_local_path vs tracked_save_to_local_path unexplained. Baseline 3 is appropriate for this coverage level.

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?

The description opens with a specific verb+resource ("Persist the current in-memory document session") and then enumerates concrete per-format outcomes for DOCX, ODT, and Google Docs. An agent can tell this writes the session to durable storage rather than merely closing it. It stops short of naming siblings (export, close_file) as alternatives, so it is clear but not sibling-differentiated.

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?

Format-specific behavior is spelled out ("For DOCX: saves clean and/or tracked changes output", "For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX"), which implies when each mode applies. However, there is no explicit when-to-use-vs-alternative guidance in the description itself — the pointer to compare_documents lives in a schema field, not here. Usage is implied rather than stated.

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