biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Set document classification

set_classification

Replace or clear the free-text classification frontmatter field of an existing specification document, bump its updated timestamp, and leave the body and other metadata unchanged.

Instructions

Replace the free-text classification frontmatter field of an existing document across the whole-body domains (type is one of req, uc, tsk, qa, prb, gol, rsk, dec, sop, feat, vcr, sysrs, txt; adr is not supported), also bumping updated and leaving the body and every other frontmatter field untouched. classification is fully free-text -- no closed vocabulary; a blank or whitespace-only value clears it back to None/absent. No create_* tool accepts a classification argument at all -- this is the sole classification-change entry point. 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) -- 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). An invalid id (path-injection attempt or wrong format for type) or an unknown type is a ValueError raised before any file access; type="adr" passes the id validation (a well-formed UUID id) and raises the plain KeyError inherited from the dispatch-table lookup instead. Returns the updated frontmatter only (no body) on success; use the corresponding get_<d> tool to fetch the full document afterward. The optional language parameter (default 'en', feat-197-i18n) selects the language variant to act on: omitted/'en' = the flat default-language document, exactly the default behavior; a non-default ISO 639-1-shaped lowercase two-letter code (e.g. 'de') = that language's variant at docs//{language}/ (found by id-scan of that subdirectory), acting on that file ONLY -- the EN file's content and updated timestamp stay untouched. Every whole-body type except feat supports a non-default language; for feat (always English) a non-default language raises a ValueError, as does a malformed language or one with no packaged heading-mapping table -- all raised before any file access.

Input Schema

Name	Required	Default
`id`	Yes
`type`	Yes
`language`	No	en
`classification`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.38.0Nov 2, 2026

addedInput schema / properties / language

Added value: +{
+  "default": "en",
+  "title": "Language",
+  "type": "string"
+}

changedInput schema / properties / type / enum

Previous value: -[
-  "req",
-  "uc",
-  "tsk",
-  "qa",
-  "prb",
-  "gol",
-  "rsk",
-  "dec",
-  "sop",
-  "feat",
-  "vcr",
-  "sysrs"
-]New value: +[
+  "req",
+  "uc",
+  "tsk",
+  "qa",
+  "prb",
+  "gol",
+  "rsk",
+  "dec",
+  "sop",
+  "feat",
+  "vcr",
+  "sysrs",
+  "txt"
+]

addedOutput schema / $defs / TxtFrontmatter

Added value: +{
+  "description": "Free-Form Text (TXT) frontmatter: `MarkdownFrontmatter` narrowed for the ``txt`` document type.\n\nParameters\n----------\ntype:\n    Fixed discriminator, always ``\"txt\"``. Narrows the base's mandatory,\n    default-less ``str`` field to a ``Literal[\"txt\"] = \"txt\"``, so a document\n    omitting ``type`` entirely still parses as a free-form text document.\nstatus:\n    One of ``\"draft\"``, ``\"progress\"``, ``\"done\"``. Narrows the base's\n    free-form ``str = \"draft\"`` default to this closed three-value set.\n    Blank/absent still defaults to ``\"draft\"`` (inherited from the base's\n    ``_default_blank_status_to_draft`` validator, which runs before this\n    one).\nversion:\n    The ``models.md`` schema major.minor.patch version this document's\n    frontmatter was written with. DO NOT CHANGE!\n\nAll other fields (``id``, ``created``, ``updated``, ``version``,\n``classification``) are inherited unchanged from\n:class:`MarkdownFrontmatter`.",
+  "properties": {
+    "classification": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Classification"
+    },
+    "created": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}:\\d{2}\\.\\d{3}(?:Z|[+-]\\d{2}:\\d{2})$",
+      "title": "Created"
+    },
+    "id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Id"
+    },
+    "status": {
+      "default": "draft",
+      "enum": [
+        "done",
+        "draft",
+        "progress"
+      ],
+      "title": "Status",
+      "type": "string"
+    },
+    "type": {
+      "const": "txt",
+      "default": "txt",
+      "title": "Type",
+      "type": "string"
+    },
+    "updated": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}:\\d{2}\\.\\d{3}(?:Z|[+-]\\d{2}:\\d{2})$",
+      "title": "Updated"
+    },
+    "version": {
+      "default": "1.0.0",
+      "title": "Version",
+      "type": "string"
+    }
+  },
+  "title": "TxtFrontmatter",
+  "type": "object"
+}

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "$ref": "#/$defs/ReqFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/UcFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/TskFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/QaFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/PrbFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/GolFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/RskFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/DecFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/FeatFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/SopFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/VcrFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/SysrsFrontmatter"
-  },
-  {
-    "$ref": "#/$defs/ParseFailureResult"
-  }
-]New value: +[
+  {
+    "$ref": "#/$defs/ReqFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/UcFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/TskFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/QaFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/PrbFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/GolFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/RskFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/DecFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/FeatFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/SopFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/VcrFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/SysrsFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/TxtFrontmatter"
+  },
+  {
+    "$ref": "#/$defs/ParseFailureResult"
+  }
+]

Changed12 schema fields changedv0.37.0Oct 24, 2026

addedOutput schema / $defs / DecFrontmatter / properties / status / enum

Added value: +[
+  "accepted",
+  "deprecated",
+  "draft",
+  "proposed",
+  "rejected",
+  "superseded"
+]

addedOutput schema / $defs / FeatFrontmatter / properties / status / enum

Added value: +[
+  "done",
+  "planning",
+  "progress",
+  "review"
+]

addedOutput schema / $defs / GolFrontmatter / properties / status / enum

Added value: +[
+  "accepted",
+  "deprecated",
+  "draft",
+  "implemented",
+  "proposed",
+  "rejected",
+  "superseded"
+]

addedOutput schema / $defs / PrbFrontmatter / properties / status / enum

Added value: +[
+  "active",
+  "cancelled",
+  "draft",
+  "resolved"
+]

addedOutput schema / $defs / QaFrontmatter / properties / status / enum

Added value: +[
+  "active",
+  "cancelled",
+  "done",
+  "draft"
+]

addedOutput schema / $defs / ReqFrontmatter / properties / status / enum

Added value: +[
+  "accepted",
+  "deprecated",
+  "draft",
+  "implemented",
+  "proposed",
+  "rejected",
+  "superseded"
+]

addedOutput schema / $defs / RskFrontmatter / properties / status / enum

Added value: +[
+  "accepted",
+  "closed",
+  "dropped",
+  "mitigating",
+  "occurred",
+  "open"
+]

addedOutput schema / $defs / SopFrontmatter / properties / status / enum

Added value: +[
+  "active",
+  "approved",
+  "draft",
+  "retired",
+  "review"
+]

addedOutput schema / $defs / SysrsFrontmatter / properties / status / enum

Added value: +[
+  "active",
+  "approved",
+  "draft",
+  "retired",
+  "review"
+]

addedOutput schema / $defs / TskFrontmatter / properties / status / enum

Added value: +[
+  "active",
+  "cancelled",
+  "done",
+  "draft"
+]

addedOutput schema / $defs / UcFrontmatter / properties / status / enum

Added value: +[
+  "accepted",
+  "deprecated",
+  "draft",
+  "proposed",
+  "superseded"
+]

addedOutput schema / $defs / VcrFrontmatter / properties / status / enum

Added value: +[
+  "approved",
+  "complete",
+  "draft",
+  "progress"
+]

First observedv0.36.0Oct 17, 2026

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and mostly discharges it: it discloses the `updated` bump, that body and other frontmatter are untouched, that blank clears to `None`, the ParseFailureResult-vs-not-found asymmetry, and that ValueError fires before any file access. It loses a point for over-specifying internals (ADR UUIDs, GitHub issue numbers, 'byte-identical error text ... trailing pydantic documentation line') that obscure rather than sharpen the behavioral picture.

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 core action and domain restriction are front-loaded in the first clause, which is good. But the remainder is a single dense paragraph bloated with internal references (ADR UUIDs, issue #170, 'case 4 of the ADR 519d1206 ... workaround chain') that no selecting agent needs and that bury the genuinely useful `language` guidance mid-paragraph.

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?

An output schema exists, yet the description still clarifies the success payload ('returns the updated frontmatter only, no body') and enumerates the failure surfaces. For a mutation tool with four parameters and no annotations, nothing material is missing: id validation, type support, language variants, and parse-failure behavior are all covered.

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%, so the description must compensate and does: `classification` is documented as fully free-text with blank/whitespace meaning clear, `type` is enumerated with `adr` called out as unsupported, `id` failure modes (path injection, wrong format) are stated, and `language` gets default, path layout, and per-type exceptions. Every one of the four parameters gains meaning beyond the bare 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?

States a precise verb+resource ('Replace the free-text `classification` frontmatter field of an existing document') and bounds the scope to the whole-body domains, explicitly excluding `adr`. It also distinguishes itself from the entire `create_*` family by declaring itself the sole classification-change entry point, so an agent can separate it from `update_frontmatter`/`update` siblings 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?

Gives explicit when-to-use ('this is the sole classification-change entry point'), when-not ('`adr` is not supported', `create_*` takes no classification argument), and a follow-up alternative ('use the corresponding `get_<d>` tool to fetch the full document afterward'). The `language` paragraph adds further conditional routing (default vs. variant, `feat` excluded).

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

Deploy Server