biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Edit document

edit

Replace an exact string in a specification document's body while leaving YAML frontmatter unchanged. The result is validated as a whole and saved only if matching and validation succeed.

Instructions

Surgical, exact-match string replacement of an existing document's frontmatter-stripped body across the whole-body domains (type is one of req, uc, tsk, qa, prb, gol, rsk, dec, sop, feat, vcr, sysrs; adr is not supported -- an explicit pre-dispatch ValueError, unlike update's inherited KeyError). Read the current body via the corresponding get_<d>(id, raw=True) first -- the read-before-edit step is a client convention, not server-enforced. Use edit for a surgical string replacement within an existing body; use the generic update tool for a whole-body or line-range replacement instead. The YAML frontmatter is never addressable (body only). The edit is 2-fold: stage 1 requires old_str to match the on-disk body byte-exactly -- uniquely, unless replace_all is true, in which case every exact occurrence is rewritten -- and stage 2 validates the edited body as a whole document; the document is written to disk only if both stages pass, and nothing is written on any failure (the file stays byte-unchanged). An empty new_str is a pure deletion (legal iff stage 2 validates). Matching is pure byte-exact with no line-ending normalization (an old_str containing \n will not match a CRLF body), no BOM handling, and no fuzzy/regex fallback. A document that exists but fails to parse returns a ParseFailureResult (error/path/id) instead of raising the domain's not-found error -- its error text is byte-identical to the domain's list_<d> failed row's error for the same file (identical field path and cause, including the trailing pydantic documentation line; ADR 9080b37c-82b3-4f63-81f1-79641d0bf14c) -- and a truly-absent id still raises the domain's not-found error. A stage-2 content-validation failure on the post-edit result returns a non-raising ValidateResult (valid=False, errors=[{message}]) with the message capped at 300 chars as the generic validate tool caps it, instead of raising AssertionError/pydantic.ValidationError (ADR b8c9bfea-6dcf-4158-bfc5-4ec17abb842f, GitHub issue #170 -- case 4 of the ADR 519d1206 non-raising-structured-result workaround chain). Stage-1's not-found/multiple-matches guards and every caller-usage ValueError (invalid id shape, unknown or adr type, identical input, empty old_str) still raise. An invalid id (path-injection attempt or wrong format for type) is a ValueError raised before any file access. Returns the updated frontmatter only (no body; updated bumped) on success; use the corresponding get_<d> tool to fetch the full document afterward.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes
`type`	Yes
`new_str`	Yes
`old_str`	Yes
`replace_all`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.36.0Oct 17, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so thoroughly: two-stage matching/validation, atomic disk write with byte-unchanged file on failure, non-raising ParseFailureResult and ValidateResult vs. raised ValueErrors/not-found errors, and explicit byte-exact rules (no line-ending normalization, no BOM, no fuzzy/regex fallback). This is exceptional behavioral disclosure for an unannotated mutation tool.

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-loads the core purpose and the update-vs-edit distinction before diving into mechanics, and every clause arguably carries needed behavior (atomicity, error taxonomy, matching rules). It is nonetheless a dense single block that is far longer than typical, bordering on overwhelming, which is the only structural weakness.

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?

Fully complete for a 5-param mutation tool: success return ('updated frontmatter only, no body, `updated` bumped'), all failure modes, atomicity guarantees, and guidance to fetch the full document via get_<d> afterwards. Even though an output schema exists, the description still rounds out the operational picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and it does: `old_str` must match byte-exactly and uniquely unless `replace_all` is true, `new_str` empty means pure deletion, `replace_all` rewrites every occurrence, `id` shape is validated before any file access, and `type` enumerates the supported domains while excluding `adr`.

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 a precise verb+resource ('surgical, exact-match string replacement of an existing document's frontmatter-stripped body') and immediately names the sibling it is not ('the generic `update` tool for a whole-body or line-range replacement'). An agent can distinguish edit from update without opening either 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 names the alternative tool (`update`) and the condition that selects it, plus the read-before-edit step via the corresponding `get_<d>(id, raw=True)` and the caveat that it is a client convention, not server-enforced. When-to-use and when-not-to-use are both stated.

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

Deploy Server