Skip to main content
Glama
cubicecho

RAGDown

by cubicecho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Rewrite or append to a document

ragdown_write
Destructive

Create, replace, or append Markdown documents at a chosen path, using a base hash to avoid overwriting unread versions and optional headings for appends.

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.

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. Addedv6.6.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say readOnly=false and destructive=true; the description goes well beyond by disclosing that default text replaces the whole file including frontmatter, that base_hash prevents overwriting an unread version, that a created document gets created_by stamped, and that a changed file results in a no-op. This is exactly the destructive-mutation context an agent needs.

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 purpose and the edit-vs-write routing, and every sentence carries operational content. It is on the dense side, but the length is justified by the number of behavioral facts it must convey for a destructive mutation.

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 6-parameter destructive tool with no output schema and no annotations beyond hints, the description covers conflict handling, hash semantics, frontmatter side effects, and append behavior. Only minor gaps remain, such as the exact shape of the returned hash on create vs replace.

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 83%, so baseline is 3, but the description adds real meaning: base_hash origins from ragdown_read_doc and why it is required, the append+heading interaction (end of document vs end of section), and session_id's role via frontmatter recording of created documents.

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 specific verbs (rewrite, append, create) and the resource (a document) with scope, and explicitly distinguishes itself from sibling ragdown_edit by naming it. An agent can pick between the two without opening a 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?

'To change part of a document, use ragdown_edit' gives an explicit alternative plus the condition that selects it. It also states when base_hash is required and what happens on conflict, leaving little to inference.

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