Skip to main content
Glama

Edit Document

edit_document
Destructive

Change part of a document you own or can edit with a batch of up to 25 precise operations, applied together as one new version: either all succeed or nothing changes. Operations: replace_text (exact text, must match exactly once unless replace_all), insert_before_heading, insert_after_heading, replace_section, delete_section, append_table_row, set_checkbox. Heading operations take a heading or path such as "Release 2.6 > M3" and work on Markdown only. For a plain find-and-replace, send edits (a list of old_text and new_text pairs) instead of operations: each old_text must appear exactly once, if_match is required, all pairs apply together or none do, and a miss returns the closest passage in the document. Send operations or edits, not both. Pass dry_run: true to see the change without saving it. Pass if_match (revision from a read) to refuse the write if the document changed; with on_conflict: "merge" the edit is combined with newer changes when they touch different sections. Pass an idempotency_key so a retry is safe. Returns a short summary of the change, never the whole document. Respects the owner's per-document AI permission. If the result lists warnings about parts of an HTML page that will not work for viewers, tell the user about them in plain words, skip any technical names, and offer to make the fix. On HTML pages, copying, moving or removing parts and fixing words by reader text are suggestions only: use suggest_document_edit.

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": {
      "slug": "<slug>"
    },
    "name": "edit_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
slugYesThe slug of the document to edit
editsNoFind-and-replace pairs: each `old_text` must appear exactly once. Needs `if_match`. All pairs apply together or none do, and a miss returns the closest passage. Send this or `operations`.
dry_runNoWhen true, show the change without saving it.
if_matchNoRevision (such as "r12") from your last read. If the document has changed since, nothing is written.
operationsNoThe changes to make, applied in order to one copy of the document. All succeed or none do. Send this or `edits`.
on_conflictNoWhen if_match is out of date: "fail" (default) writes nothing; "merge" combines the edit with newer changes if they touch different sections.
idempotency_keyNoAny string up to 128 characters. A retry with the same key returns the original result instead of writing again.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Adds substantial behavior beyond the annotations: full atomicity (all succeed or nothing changes), that the return value is a short summary rather than the document, that a miss returns the closest passage, that if_match fails closed and on_conflict='merge' combines non-overlapping changes, that idempotency_key makes retries safe, and that per-document AI permission is enforced. The idempotency_key guidance is consistent with idempotentHint=false (the tool is not inherently idempotent; safety requires the key). It stops short of stating rate limits or what the warning payloads look like.

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

Conciseness5/5

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

Dense but well ordered: purpose and atomicity first, then the operations catalog, then the edits alternative, then the safety parameters, then the clustered special-case guidance for HTML and permissions. Nearly every clause carries actionable information; the only slight slack is restating atomicity in both the operations and edits clauses.

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

Completeness5/5

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

For a 7-parameter, seven-variant union tool with no output schema, the description covers mutation scope, atomicity, conflict handling, idempotency, return shape, and the HTML escape hatch. An agent has everything needed to choose the right variant and call it safely.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning on top: the mutual exclusivity of `edits` and `operations`, the operational intent behind `if_match` (revision from a read) and `on_conflict` ('merge' only combines when changes touch different sections), and the dry_run preview contract. Some of this overlaps the schema, keeping it below 5.

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 ('Change part of a document you own or can edit') plus the batch model (up to 25 operations as one new version) and enumerates the seven operation types. It also names the sibling it is not (suggest_document_edit for HTML pages), so an agent can distinguish it without opening the schema.

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?

Explicit routing rules: send `edits` for plain find-and-replace, `operations` for structural changes, never both; heading ops are Markdown-only; use get_document mode 'outline' to get exact heading names; use suggest_document_edit for HTML copy/move/remove and reader-text fixes. It also explains when to pass dry_run and when to pass if_match.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.