biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Create System Requirements Specification

create_sysrs

Create a validated System Requirements Specification: assigns a fresh ID, derives filename from H1 title, and writes the document. Returns frontmatter only; fetch full document with get_sysrs.

Instructions

Create a new System Requirements Specification: 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 System Requirements Specification 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. Returns the newly created document's frontmatter only (no body); use the corresponding get_sysrs tool to fetch the full document afterward.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`content`	Yes

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.5/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 richly: it discloses that content validation failure returns a non-raising ValidateResult (valid=False, errors capped at 300 chars) instead of raising, that nothing is written in that case, and that only frontmatter is returned. This is behavior an agent cannot infer from schema or annotations.

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?

Front-loads the main purpose well, but parenthetical citations (feat-110, ADR f14f125e-..., GitHub issue #204, ADR 519d1206) are internal-tracking noise that adds length without helping an agent invoke the tool.

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 so return-value detail is optional, yet the description still notes only frontmatter is returned and points to get_sysrs for the body. For a mutation tool with no annotations, all decision-relevant information an agent needs is present.

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?

Schema coverage is 0% for the single content param, so the description must compensate, and it does: it specifies the value is 'body-only content' and that the H1 title drives filename derivation. Minor gap is that content format (markdown structure, size limits) is not spelled out.

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 (Create) plus resource (System Requirements Specification) and enumerates the internal steps: assigns an id, derives a filename from the H1 title, validates the body, and writes to the base directory. This clearly distinguishes it from sibling creators of other document types and from get_sysrs.

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

Usage Guidelines4/5

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

Explicitly instructs the agent to call get_sysrs afterward to fetch the full document, and indicates the input is body-only content. It stops short of stating exclusions versus the other create_* tools, but the routing context is clear.

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

Deploy Server