Skip to main content
Glama

Rewrite or append to a document

ragdown_write
Destructive

Create or update Markdown files safely: rewrite a whole document, append text, or add content under a heading, using base_hash to prevent overwriting unread changes.

Instructions

Rewrite or append to an existing document, or create one at a path you choose. To change part of a document, use ragdown_edit, which sends only the passages that change. By default text replaces the whole file (frontmatter included), which for an existing document needs base_hash: the hash ragdown_read_doc returned, so you never overwrite a version you have not read. A document this creates gets created_by: ragdown_write in its frontmatter, so the hash returned is of the file as written, not of text. append: true adds text at the end of the document, or with heading at the end of that section, leaving the rest as it is. If the file changed since base_hash, nothing is written: read it again and redo the 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": {
      "path": "<path>",
      "text": "<text>"
    },
    "name": "ragdown_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesPath of a Markdown file relative to the documents root, e.g. 'projects/alpha.md'
textYesThe document's new Markdown, or with append, what to add
appendNo
headingNoWith append: add to the end of the section under this heading
base_hashNoThe hash from ragdown_read_doc; required to replace an existing document
session_idNoStable id of the conversation, recorded in the frontmatter of a document this creates

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv6.10.0
    • removedInput schema / additionalProperties
      Removed value: -false
  2. Addedv6.6.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: it discloses that whole-file replacement includes frontmatter, that a created file gains created_by: ragdown_write in frontmatter, and that a hash mismatch results in NO write at all. It also clarifies that the returned hash is of the file as written, not of the input text — a non-obvious return-value caveat.

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-loaded with the core action and the sibling alternative before the conditional details. It is dense and slightly run-on in the middle ('so the hash returned is of the file as written, not of text'), but nearly every clause carries operational information and nothing reads as filler.

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 destructive, six-parameter mutation with no output schema, the description covers the safety protocol, append semantics, and frontmatter side effects. Minor gaps remain around what happens if the specified heading does not exist and whether parent directories are created for a new path.

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 high (83%), so the baseline is 3; the description earns above that by explaining the conditional dependency between base_hash and replacing an existing document, and the interaction of append with heading ('at the end of that section, leaving the rest as it is'). It does not explain heading behavior when the heading is absent, leaving one semantic gap.

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?

Names a specific verb pair (rewrite/append) plus the create case, and explicitly contrasts itself with ragdown_edit (partial-change) rather than leaving the agent to infer the split. An agent can route between write, edit, and read_doc without opening any 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?

Gives an explicit alternative ('To change part of a document, use ragdown_edit, which sends only the passages that change') and the condition that forces base_hash for existing documents. It also states the recovery path when the hash is stale ('read it again and redo the edit'), which is the exact decision an agent faces mid-task.

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