Skip to main content
Glama
rgdevment

Tisty

by rgdevment
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Change a passage of a document

edit_doc

Replace a specific passage in a document by matching its text, section, or line range; preserve prior content and refuse unsafe edits.

Instructions

Replace one passage of a document with another, named either by what it says with old or by where it sits with section or a line range — which let you change a part of a document you never read. What it said before is kept first, and if that cannot be done the edit is refused rather than made; restore_doc puts it back. The answer says how many characters the document grew by, which is worth reading: an edit should not change the size by much more than what you sent.

Input Schema

NameRequiredDescriptionDefault
toNoLast 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
docYesThe document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title
newYesWhat takes its place. Empty takes the passage out
oldNoThe 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
echoNoHand back the lines around the change as well, instead of reading the document again to see it
fromNoFirst line to replace, counting from 1. Needs `print`
printNoThe 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
sectionNoOne 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`
keep_compactionNoOnly 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

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does it well: prior content is preserved first, the edit is refused rather than partially applied if that fails, concurrent writes cause a no-op with guidance to call outline_doc, and keep_compaction gates a pending compaction. It also warns to sanity-check the returned `grew` delta.

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 the core action and the addressing options, and every clause carries information (atomicity, rollback path, grew check). The prose is somewhat baroque ('which let you change a part of a document you never read'), costing a bit of scanability.

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?

No output schema exists, yet the description explains the return signal (`grew` and the `echo` alternative), the failure modes, and the concurrency guard. For a 9-parameter mutation tool this is comprehensive.

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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: the three mutually exclusive addressing modes and the conflict semantics tied to `print` and the positional fields. It reinforces rather than merely repeats the schema.

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 one passage of a document) and immediately enumerates the three addressing modes (old text, section, line range). It clearly differentiates itself from siblings like write_doc/append_doc (partial vs full replacement) and restore_doc (rollback).

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?

Explains the useful scenario for positional addressing ('change a part of a document you never read') and routes rollback to restore_doc. It does not explicitly state when to prefer write_doc/append_doc instead, so alternatives are implied rather than enumerated.

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