ShadowGit MCP Server

Write docs pages

write_docs

DestructiveIdempotent

Creates documentation pages with summaries and linked body paragraphs for code areas and symbols, saving each version to ShadowGit history for later reference.

Instructions

Write the words of docs pages get_docs read, at the head it answered. For each page, an area by its id or overview: true, then a summary, one sentence on what it is for (at most 200 characters), and a body, short paragraphs on how it works (at most 400 words), each paragraph text or pieces, a piece linking a symbol (its file and name, as get_docs and get_code_context name them) or an area by its id, where the text names it. Or holds: true, when the words still hold after the changes get_docs listed: they are kept again at head, unchanged. Describe what the code does and how it works, from the code you read and the facts get_docs gave: a page with no words can start short, and later sessions add to it. Links that name nothing at head are made plain text and named back. A page past these limits is left out, with why; the others are kept. ShadowGit keeps every version in its own history, never in the project's files.

Input Schema

Name	Required	Description
`head`	Yes	The head get_docs answered
`repo`	No	Project name or absolute path. Defaults to the current project.
`pages`	Yes

Output Schema

Name	Required	Description	Default
`head`	Yes
`repo`	Yes
`pages`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.6.1Oct 29, 2026

TDQS

B3.3/5.0

Behavior4/5

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

With destructiveHint=true and idempotentHint=true already declared, the description still adds real substance: partial-failure semantics (pages past limits are left out with a reason, others kept), link rewriting to plain text, holds:true preserving unchanged pages, and the note that ShadowGit versions live in its own history, never in project files. This meaningfully contextualizes the destructive/idempotent annotations, though it never explicitly states that existing page content is replaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire definition is a single dense run-on block in an archaic, inverted style ('at the head it answered', 'named back', 'the words still hold'). Per-field guidance is buried in prose rather than front-loaded or structured, forcing the agent to parse rather than skim. Information density is high, but the packaging actively impedes comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation, and the description covers limits, partial failure, link handling, and versioning. However, for a destructive write tool it never plainly states that existing page content is overwritten, leaving the core mutation effect implicit.

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?

The schema covers head, repo, area, body, holds, summary, and overview, but crucial limits (summary at most 200 characters, body at most 400 words) appear ONLY in the description, not in the schema constraints. The description also clarifies area vs overview and the symbol/area linking inside body pieces — genuine value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening identifies a write operation on docs pages and ties it to the sibling get_docs ('Write the words of docs pages get_docs read'), which does differentiate it from the read tool. But the phrasing is cryptic and grammatically inverted, so the agent must decode the purpose rather than read it directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is substantial guidance on how to construct pages (summary/body structure, holds:true for unchanged pages, links that name nothing become plain text), but no explicit statement of when to use this versus alternatives or when not to call it. Usage is strongly implied by the get_docs pairing rather than stated.

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

Deploy Server