biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Set document status

set_status

Replace an existing specification document's status and bump its updated timestamp while leaving the body untouched; invalid statuses return the allowed values instead of raising.

Instructions

Replace the status of an existing document across every domain (type is one of adr, req, uc, tsk, qa, prb, gol, rsk, dec, sop, feat, vcr, sysrs), also bumping updated (the whole-body domains) and leaving the body untouched. When status (or, for type="adr" with superseded_by given, the composed "superseded by X" value) already equals the document's current status, this is a no-op -- no write, no updated bump -- and still returns the same value shape a changed-status call would (issue #109). The new status must be one of the domain's own closed vocabulary values (see the domain's XFrontmatter.status field); an out-of-vocabulary status does NOT raise -- it returns a structured, non-raising InvalidStatusResult ({valid: false, type, status, allowed_values, message}) instead, so the allowed-values detail survives MCP clients that truncate error content. superseded_by is accepted only for type="adr" -- it composes the status as "superseded by {superseded_by}"; with any other type it is a ValueError. A document that exists but fails to parse returns a ParseFailureResult (error/path/id) instead of raising the domain's not-found error (a truly-absent id still raises, and the out-of-vocabulary-status InvalidStatusResult check above still runs first, pre-lock/pre-load) -- 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; ADR b8c9bfea-6dcf-4158-bfc5-4ec17abb842f, GitHub issue #170 -- case 4 of the ADR 519d1206 non-raising-structured-result workaround chain). Neither create_* nor the generic update tool accepts a status argument at all -- this is the sole status-change entry point. 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, except for the unchanged adr branch) 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
`status`	Yes
`superseded_by`	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.8/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so extensively: no-op semantics when status is unchanged, the `updated` bump behavior, non-raising `InvalidStatusResult` for out-of-vocabulary status, `ValueError` for a bad `id` before any file access, `ParseFailureResult` for unparseable documents, and exactly what is returned (frontmatter only). This is far beyond what a structured field would convey.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is one very dense paragraph packed with parentheticals, ADR UUIDs, GitHub issue numbers, and byte-identity guarantees that an agent does not need to invoke the tool. Every core fact earns its place, but the reference-bookkeeping clutter and lack of paragraphing hurt readability.

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?

For a mutation tool with zero annotation coverage and 0% schema description coverage, the description supplies everything needed: preconditions, failure modes, no-op semantics, and return shape (with an output schema also present). Nothing an agent needs to call it correctly is missing.

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 coverage is 0%, yet all four parameters are given meaning: `id` (invalid format or path injection raises `ValueError`), `type` (the 13 domain enum, mirroring the schema), `status` (must be the domain's own closed vocabulary, out-of-vocab does not raise), and `superseded_by` (accepted only for `adr`, composes 'superseded by X'). The description fully compensates for the absent schema documentation.

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 opening sentence gives a specific verb and resource ('Replace the status of an existing document across every domain') and enumerates the domains via `type`. It explicitly distinguishes itself from siblings by stating that neither `create_*` nor `update` accepts a `status` argument, so an agent can identify this as the sole status-change entry point without opening another 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?

It states the exclusive role ('this is the sole status-change entry point') and names the alternatives that cannot do this job (`create_*`, generic `update`), plus the correct follow-up tool (`get_<d>`) for retrieving the full document. It also scopes `superseded_by` to `type="adr"` only, so the conditions for correct invocation are explicit.

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

Deploy Server