Skip to main content
Glama
Sign In
biz.dfch.SpecMgr

biz.dfch.SpecMgr

by dfch
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Parse requirement

parse_req

Parse a requirement markdown file with YAML frontmatter and body into a structured ReqDocument; existing unparseable files return structured validation errors, while missing paths raise file-access errors.

Instructions

Parse a requirement markdown file (YAML frontmatter + body) from disk into a structured :class:~biz.dfch.specmgr.req.models.v1.ReqDocument. An existing file that fails to parse 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/yaml.YAMLError (ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204 -- case 5 of the ADR 519d1206 non-raising-structured-result workaround chain); a truly-absent or unreadable path still raises the OSError-family file-access error (FileNotFoundError/PermissionError/OSError) from Path.read_text(). The file's language is derived from its path position relative to the requirement base directory: a file in the flat docs/req/ directory parses canonical (no heading-mapping table); a file in a direct two-letter docs/req/{language}/ subdirectory parses through that language's table (an actionable ValueError when no table exists for the language); any other location parses canonical.

Input Schema

NameRequiredDescriptionDefault
pathYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.37.0
    • changedOutput schema / $defs / Level / properties / value / description
      Previous value: -"Single-line value giving the requirement's obligation strength (e.g. \"MUST\")."New value: +"Single-line value giving the requirement's obligation strength (e.g. \"MUST\"). One of `MUST`, `SHOULD`, `MUST NOT`, `SHOULD NOT`, `MAY` (RFC 2119)."
    • addedOutput schema / $defs / ReqFrontmatter / properties / status / enum
      Added value: +[
+  "accepted",
+  "deprecated",
+  "draft",
+  "implemented",
+  "proposed",
+  "rejected",
+  "superseded"
+]
  2. First observedv0.36.0

TDQS

B3.2/5.0
Behavior4/5

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

No annotations are provided, and the description carries much of that burden. It spells out error semantics: a non-raising ValidateResult on parse failure, a 300-char error cap, and OSError-family raises for missing or unreadable paths. It also explains how language is resolved from path position, including the ValueError case. It does not explicitly state that the tool is read-only and has no side effects, though 'parse' strongly implies that.

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

Conciseness2/5

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

The text is a dense run-on sprinkled with internal references (ADR UUIDs, GitHub issue #204, feat-110, 'case 5 of the ADR 519d1206 ... workaround chain') that add nothing for an agent. The purpose is front-loaded, but much of the rest is noise mixed in with useful behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool that has an output schema, it covers the return types, the error paths and the language-resolution logic thoroughly. The main gaps are differentiation from siblings and the format or base of the path.

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

Parameters3/5

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

Schema coverage is 0%, and the single 'path' parameter has no schema description. The description compensates partly by saying it is a file on disk and by explaining how its location under docs/req/ or docs/req/{language}/ affects parsing. It leaves unclear whether the path is absolute or relative and what it is relative to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a specific verb and resource: it parses a requirement markdown file (YAML frontmatter + body) from disk into a structured ReqDocument. It does not say how this differs from siblings like get_req or validate, which likely overlap.

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

Usage Guidelines2/5

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

There is no guidance on when to use parse_req instead of get_req, which probably fetches by ID, or validate. The error-handling detail implies some use, but it never gives explicit when or when-not guidance.

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

Deploy Server

Other Tools