Skip to main content
Glama

Change a passage of a document

edit_doc
Destructive

Replaces a passage in a document by exact text or by section/line range without reading the rest; keeps prior content for restore and refuses unsafe edits.

Instructions

Replace one passage of a document, named by its text in old or by place with section or from and to, which needs no reading of the rest. What it said is kept first for restore_doc, or the edit is refused. The answer's grew should be close to what you sent. A task's page too, by its own name: its boxes are the task's steps.

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": {
      "doc": "<doc>",
      "new": "<new>"
    },
    "name": "edit_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoLast line; left out, to the end. Only with `from`
docYesThe document's id from `docs`, not its title
newYesWhat takes its place; empty takes the passage out
oldNoThe passage as written now, from `read_doc`, matching one place only; take in a line around it if needed. Not with `section` or lines
echoNoHand back the lines around the change, instead of reading again
fromNoFirst line to replace, from 1. Needs `print`
printNoThe `print` from `read_doc` or `outline_doc`, for `section` or lines only. If anyone wrote since, nothing changes: ask `outline_doc` again
sectionNoA heading and all under it, by its `at` in the `outline` of `outline_doc`, from 0. Needs `print`
keep_compactionNoOnly on the person's word: `rules` «tidying»

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.47.0
    • changedInput schema / properties / keep_compaction / description
      Previous value: -"The person told you in this conversation to keep the compaction awaiting their word"New value: +"Only on the person's word: `rules` «tidying»"
  2. Changed9 schema fields changedv1.43.2
    • changedInput schema / properties / doc / description
      Previous value: -"The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title"New value: +"The document's id from `docs`, not its title"
    • changedInput schema / properties / echo / description
      Previous value: -"Hand back the lines around the change as well, instead of reading the document again to see it"New value: +"Hand back the lines around the change, instead of reading again"
    • changedInput schema / properties / from / description
      Previous value: -"First line to replace, counting from 1. Needs `print`"New value: +"First line to replace, from 1. Needs `print`"
    • changedInput schema / properties / keep_compaction / description
      Previous value: -"Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead"New value: +"The person told you in this conversation to keep the compaction awaiting their word"
    • changedInput schema / properties / new / description
      Previous value: -"What takes its place. Empty takes the passage out"New value: +"What takes its place; empty takes the passage out"
    • changedInput schema / properties / old / description
      Previous value: -"The passage as it is written now, copied from `read_doc`, matching one place only — take in the lines around it if a short one would fit twice. Leave it out when naming a `section` or a line range"New value: +"The passage as written now, from `read_doc`, matching one place only; take in a line around it if needed. Not with `section` or lines"
    • changedInput schema / properties / print / description
      Previous value: -"The print the document read at, from `read_doc` or `outline_doc`. It goes with `section` or a line range and nothing else uses it: an edit named by `old` is matched against the text itself. If anyone wrote since you took it, nothing is changed and you are told to ask `outline_doc` where the passage sits now"New value: +"The `print` from `read_doc` or `outline_doc`, for `section` or lines only. If anyone wrote since, nothing changes: ask `outline_doc` again"
    • changedInput schema / properties / section / description
      Previous value: -"One heading and everything under it, named by its number and not by its words: the `at` of a heading in the `outline` `outline_doc` hands back, counting from 0. Needs `print`"New value: +"A heading and all under it, by its `at` in the `outline` of `outline_doc`, from 0. Needs `print`"
    • changedInput schema / properties / to / description
      Previous value: -"Last line to replace. Left out, it runs to the end. It goes with `from`: on its own it names no place and the edit is refused"New value: +"Last line; left out, to the end. Only with `from`"
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already flag destructive=true and non-idempotent, but the description adds genuinely non-derivable behavior: prior text is retained for `restore_doc` or the edit is refused outright, and a stale `print` causes a no-op rather than a partial write. It also surfaces a return signal (`grew` should approximate the sent size) that lets the caller validate the result. No permissions model or failure-mode detail beyond those is given, so it falls short of a 5.

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 short sentences, front-loaded with the verb and the two addressing modes, with no filler. The telegraphic phrasing ('What it said is kept first for `restore_doc`') and the trailing note about task pages are terse to the point of being cryptic, which costs some first-read clarity.

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?

For a 9-parameter destructive mutation with no output schema, the description covers addressing modes, staleness refusal, restore-ability, the optional `keep_compaction` caveat, and hints at the return field `grew`. That is close to sufficient to call the tool safely; only the sibling-selection rationale and full error semantics are absent.

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 100%, so every parameter is already documented, and the description largely restates the addressing scheme rather than adding syntax or format detail. Its only extra semantic value is the interaction rule tying `print` freshness to the write and the note that `grew` reflects the sent size. Baseline 3 is appropriate where the schema carries the parameter load.

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 states a specific verb and scope: 'Replace one passage of a document', and explains both addressing modes (by `old` text or by place with `section`/`from`+`to`). It also notes it works on a task's page, which broadens the resource scope usefully. It stops short of contrasting with near-siblings like `write_doc` or `append_doc`, so the agent must infer why a passage-level edit is preferred over a whole-document write.

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

Usage Guidelines4/5

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

It gives concrete operating conditions: `old` must match one place only (take in a surrounding line if needed), `section`/lines require `print`, and if anyone wrote since the token, nothing changes and you must re-run `outline_doc`. It also explicitly restricts `keep_compaction` to 'only on the person's word' and points restoration at `restore_doc`. What's missing is an explicit rule for choosing this over rewrite-oriented siblings such as `write_doc` or `edit_table`.

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