biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Parse goal

parse_gol

Parse a goal markdown file with YAML frontmatter and body into a structured GolDocument; invalid files return a validation result without raising parse errors.

Instructions

Parse a goal markdown file (YAML frontmatter + body) from disk into a structured :class:~biz.dfch.specmgr.gol.models.v1.GolDocument. 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 goal base directory: a file in the flat docs/gol/ directory parses canonical (no heading-mapping table); a file in a direct two-letter docs/gol/{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

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.37.0Oct 24, 2026

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

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

First observedv0.36.0Oct 17, 2026

TDQS

A4.2/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 burden and does so thoroughly: an existing-but-invalid file returns a non-raising ValidateResult with valid=False and an errors[].message capped at 300 chars, while an absent or unreadable path still raises the OSError family from Path.read_text(). That is exactly the raise-vs-return distinction an agent needs to write correct error handling.

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?

It is front-loaded and every functional sentence earns its place, but the commit/ADR/issue citations ('feat-110', 'ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204 -- case 5 of the ADR 519d1206 ... chain') add traceability noise an agent cannot act on. The content is also delivered as one dense paragraph rather than separated behavior, error, and language-resolution statements.

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?

An output schema exists, yet the description still characterizes the success and failure return shapes, and it fully covers path-driven language resolution for a single-parameter tool. The remaining gap is minor but real: nothing states what the path is relative to or whether it must include the .md extension.

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 `path` parameter, so the description must compensate, and it does: it explains that language resolution depends on the path's position relative to the goal base directory (flat docs/gol/ = canonical, docs/gol/{language}/ = that language's table, anything else = canonical) and that a missing table yields an actionable ValueError. It stops short of saying whether the path is absolute or relative to the base directory, which is the one ambiguity left.

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 description names a specific verb and resource ('Parse a goal markdown file ... from disk') and states the concrete output type ('structured GolDocument'), which separates it from siblings like get_gol, list_gol, and create_gol without opening any schema. The parenthetical '(YAML frontmatter + body)' further pins down what is being parsed.

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

Usage Guidelines3/5

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

Usage is only implied: an agent can infer this is the tool for turning an on-disk goal file into a model object, but the description never states when to prefer it over get_gol or list_gol, nor any prerequisite such as the file needing to exist. The error-behavior sentences describe outcomes rather than selection criteria.

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

Deploy Server