biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Create requirement

create_req

Creates a new requirement by assigning a fresh ID, validating the submitted body, and writing the document; non-default languages add a translation under an existing ID.

Instructions

Create a new requirement: assigns a fresh id, derives a filename from the body's H1 title, validates the submitted body-only content, and writes the new document to the requirement base directory. A content-validation failure of the submitted body returns a non-raising ValidateResult (valid=False, a single errors[].message capped at 300 chars as the generic validate tool caps it, feat-110) instead of raising AssertionError/pydantic.ValidationError (ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204 -- case 5 of the ADR 519d1206 non-raising-structured-result workaround chain); nothing is written in that case. The structure reference is the get_req_schema tool (the generated JSON Schema); the get_req_template/get_req_example tools return the authoring template and a complete sample. Returns the newly created document's frontmatter only (no body); use the corresponding get_req tool to fetch the full document afterward. The optional language parameter (default 'en', feat-197-i18n) selects the language to create the document in: omitted/'en' = a new flat docs/req/ document with a fresh id, exactly the default behavior (id must then be omitted); a non-default ISO 639-1-shaped lowercase two-letter code (e.g. 'de') creates a TRANSLATION of an existing requirement instead: id -- the shared id of the existing EN source document -- is then required (no fresh id is assigned; the variant carries the same id), the EN source must exist (else ReqNotFoundError), and the variant is written to docs/req/{language}/ under the EN source's exact file name with status draft; content is validated through that language's heading-mapping table (translated headings are accepted) and persisted verbatim. An existing variant of that id and language is never overwritten (FileExistsError). A malformed language, one with no packaged heading-mapping table, a missing id for a non-default language, or an id given for the default language is a ValueError raised before any file access.

Input Schema

Name	Required	Default
`id`	No
`content`	Yes
`language`	No	en

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.38.0Nov 2, 2026

addedInput schema / properties / id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Id"
+}

addedInput schema / properties / language

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

Changed1 schema field changedv0.37.0Oct 24, 2026

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

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

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 supplied, the description carries the full behavioral burden and does so thoroughly: the non-raising ValidateResult path (valid=False, one errors[].message capped at 300 chars), the guarantee that nothing is written on validation failure, FileExistsError for existing variants, ReqNotFoundError for a missing EN source, and ValueError raised before any file access for malformed input. It also discloses the partial return shape (frontmatter only, no body).

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 is front-loaded in the first clause, which is good, but the remainder is a single dense block punctuated by internal identifiers (feat-110, feat-197-i18n, ADR UUID f14f125e..., GitHub issue #204, ADR 519d1206 case 5) that add noise an invoking agent cannot act on. The behavioral facts are valuable; the provenance citations and nested parentheticals make it harder to scan than necessary.

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 3-parameter mutation tool with an output schema and no annotations, this covers everything an agent needs: preconditions, error taxonomy, whether files are written or overwritten, the translation-mode branch, and confirmation that only frontmatter is returned with a pointer to get_req for the body. Nothing material is left for the caller to infer.

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 it does: `language` is defined as a lowercase ISO 639-1-shaped code defaulting to 'en' with a large behavioral fork (flat docs/req/ vs docs/req/{language}/ translation with status draft), `id` is described as either forbidden or required depending on that fork and as shared with the EN source, and `content` is described as body-only content validated against the language's heading-mapping table and persisted verbatim. This adds meaning well beyond bare type declarations.

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 and resource ('Create a new requirement') and immediately enumerates the concrete side effects: fresh id assignment, filename derivation from the body H1, validation, and write to the requirement base directory. It also names sibling tools (get_req_schema, get_req_template, get_req) that serve adjacent purposes, so an agent can distinguish it from list_req/parse_req/validate 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?

States explicitly what to do afterward ('use the corresponding get_req tool to fetch the full document') and where to get structure guidance (get_req_schema vs get_req_template/get_req_example). It also gives conditional routing rules: omit `id` with default language, supply `id` only when creating a translation in a non-default language. Exclusions and required preconditions are spelled out rather than implied.

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

Deploy Server