Skip to main content
Glama

update_doc

DestructiveIdempotent

Edit documents by replacing one section or the whole body with version checks to prevent overwriting concurrent changes, or append text without a read.

Instructions

Edit a document. To change ONE section, pass section= with body=<that section's new text, heading line included>: only that section is replaced and the rest of the document is kept. Without section, body is the WHOLE document — never send back the text of a single section as body (the server refuses a body that halves the document and drops its headings, unless allow_shrink=true). Replacing the body REQUIRES base_version — the version you got from get_doc — and the write is refused with a 409 if anyone changed the document since, so you can never silently overwrite someone else's edit. The append parameter adds to the end: it needs no base_version, cannot conflict, and needs no prior read of the document. The doc argument accepts an old path or a bare slug too; the reply then carries moved_to (the current path). Note the two different 409s: a stale base_version, and an ambiguous bare slug (resolved by the full path or UUID).

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>"
    },
    "name": "update_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
docYesDocument UUID, or a slug path like 'architecture/adr/adr-004' (a path also needs project_id). A path survives the document being moved: the old path still resolves, and so does a bare slug ('adr-004') when exactly one live document in the project has it. When the reference was not the live path, the reply carries moved_to — the document's current path; use that from now on. A bare slug shared by several documents is a 409 ('Ambiguous document slug') listing the full paths: pick one and repeat the call with the full path or the UUID. The UUID never changes.
bodyNoReplacement markdown for the WHOLE document, or for the one section named by section. Requires base_version.
titleNoNew title.
appendNoText to add to the END of the document. No base_version needed. Cannot be combined with body.
sectionNoHeading text or anchor of the one section to replace (as in get_doc section=). body is then that section's new text, heading line included; the rest of the document is untouched.
positionNoNew sort position among siblings.
parent_idNoNew parent document UUID.
project_idNoProject UUID. Required only when doc is a slug path.
allow_shrinkNoOnly for a deliberate whole-document replacement that drops sections: lifts the guard that refuses a body halving the document.
base_versionNoThe version you read from get_doc. Required for any write other than append.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.6
    • addedInput schema / properties / allow_shrink
      Added value: +{
      +  "description": "Only for a deliberate whole-document replacement that drops sections: lifts the guard that refuses a body halving the document.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / body / description
      Previous value: -"Replacement markdown for the WHOLE document. Requires base_version."New value: +"Replacement markdown for the WHOLE document, or for the one section named by section. Requires base_version."
    • addedInput schema / properties / section
      Added value: +{
      +  "description": "Heading text or anchor of the one section to replace (as in get_doc section=). body is then that section's new text, heading line included; the rest of the document is untouched.",
      +  "type": "string"
      +}
  2. First observedv0.1.1

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the annotations: it discloses optimistic-concurrency semantics (409 on stale base_version, 'you can never silently overwrite'), the shrink guard and how allow_shrink lifts it, the second 409 for ambiguous slugs, and that append is conflict-free. destructiveHint=true is only meaningful because the description explains what is destroyed and under what guard.

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 primary distinction (one section vs whole document) and dense with useful content throughout. Slight redundancy in the closing 'two different 409s' sentence, which largely restates slug-ambiguity detail already present in the doc parameter's schema description, but nothing else is padding.

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 10-parameter mutation tool with no output schema, this covers the high-risk paths thoroughly: conflict handling, the shrink guard, reference resolution, and moved_to in the reply. One gap remains — it never says the reply returns the new version, which the caller needs to chain a follow-up write after a successful edit.

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 earns more by explaining parameter interaction rather than restating fields: section+body must be used together, append cannot be combined with body, and base_version's requirement is conditional on the mode. title, position, and parent_id are left entirely to the schema, which is acceptable given full coverage.

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?

Opens with a specific verb+resource ('Edit a document') and immediately decomposes it into three distinct modes (section-replace, whole-body replace, append), which is exactly the distinction an agent needs. A caller can tell this apart from create_doc, get_doc, and comment_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?

Explicitly routes between modes: 'To change ONE section, pass section=... with body=...' versus 'Without section, body is the WHOLE document', plus append's separate rules ('needs no base_version, cannot conflict, and needs no prior read'). It also states a negative case — never send a single section's text as a whole-document body — and names get_doc as the source of base_version.

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