mazarbul

Overview Schema Source Related Servers Discussions Admin

editDocument

Replace exact text in a document to create a new revision while preserving history and re-resolving wikilink edges.

Instructions

Edit a document by exact string replacement (Claude-Code Edit semantics): oldString must match the current body exactly and be unique unless replaceAll. The result is ingested as a new revision (history kept; wikilink edges re-resolved; removed links forgotten) and the vault file refreshes. Use writeDocument to replace a whole body. Result counts (edges, unresolved) are whole-document snapshots after the edit.

Input Schema

Name	Required	Description
`path`	Yes	Vault-relative path of the document to edit.
`scope`	No	Disambiguates when the same path exists in more than one scope. Omit when the path is unambiguous. An edit never changes a document's scope; it is preserved.
`newString`	Yes	Replacement text. Must differ from oldString.
`oldString`	Yes	Exact text to replace. Must match the current body exactly (including whitespace) and, unless replaceAll, be unique in it.
`replaceAll`	No	Replace every occurrence instead of requiring oldString to be unique.

Output Schema

Name	Required	Description
`file`	No	Absolute path of the materialized vault file.
`name`	Yes	entities/{uid} resource name of the document-as-entity.
`path`	Yes
`edges`	No	Total resolved wikilink and frontmatter edges the whole document holds after this write (snapshot, not a delta — counts all [[links]] in the current body that resolved, regardless of how many were already in the graph).
`changed`	Yes	False when the content matched the latest revision (no-op).
`warnings`	No	Non-fatal advisory messages — e.g. a title-collision warning when the document's display name shadows a non-document entity. Does not affect the written content; the document body is stored byte-for-byte as supplied. Omitted when empty.
`reconciled`	No	Count of wikilinks in OTHER vault documents that this write newly made resolvable (cross-document reconcile pass; separate from the document's own edge snapshot above).
`unresolved`	No	Count of [[wikilinks]] left dangling in the whole document after this write (snapshot, not a delta).
`documentUid`	Yes
`pendingEdit`	No	True when the vault file holds an un-ingested manual edit and was left untouched.
`revisionUid`	No
`unresolvedTargets`	No	The dangling wikilink targets by name (text inside [[…]] that matched nothing) — fix a typo or create the target. Omitted when none dangle.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that edits create a new revision, history is kept, wikilink edges are re-resolved, removed links are forgotten, and the vault file refreshes. It also explains that edges and unresolved counts are whole-document snapshots after the edit.

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?

The description is front-loaded with the core operation and then layers behavioral consequences and the sibling alternative in only three sentences. Every sentence adds distinct information without waste.

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?

Although annotations are absent, the description explains the side effects an agent most needs to know for a mutation: revision history, link re-resolution, and refresh behavior. Because an output schema exists, it need not fully describe return values, and its note about result counts is sufficient context.

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 description coverage is 100%, so all five parameters already carry their own documentation in the input schema. The description repeats the key oldString uniqueness rule and replaceAll behavior but does not add syntax or format detail beyond 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?

The description states a specific verb and resource: editing a document by exact string replacement. It immediately distinguishes this from whole-body replacement by naming writeDocument in the next sentence, so an agent can select it without opening schemas.

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?

It explicitly contrasts the tool with writeDocument, giving the alternative and the condition that selects it: use writeDocument to replace a whole body. The uniqueness and replaceAll rules further clarify when the edit will be accepted.

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