Parse feature

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

With no annotations, the description carries the full behavioral burden and does so precisely: parse failures on an existing file return a non-raising ValidateResult (valid=False, single errors[].message capped at 300 chars), whereas an absent/unreadable path still raises the OSError family (FileNotFoundError/PermissionError/OSError) from Path.read_text(). This is exactly the failure-mode disclosure an agent needs.

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

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

Purpose is front-loaded in the first sentence, but the text is dense with ADR UUIDs, GitHub issue numbers, and a parenthetical provenance chain that adds little for an agent deciding whether to call it. Every clause carries some information, but the identifiers make it heavier than needed.

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

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

An output schema exists so return values needn't be re-explained, and the description correctly focuses on the exception/no-exception contract. It is nearly complete, missing only explicit guidance on how this differs from sibling parse_* and get_* tools.

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

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

Single parameter 'path' has 0% schema description coverage, so the description must compensate. It clarifies the path points to a markdown file read from disk via Path.read_text() and what happens if it is missing/unreadable, which gives useful meaning, but it never states expected format or path-relative details beyond that.

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

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

States a specific verb (parse) and resource (feature markdown file with YAML frontmatter + body, from disk into a FeatDocument). It's clear what it does, though it never contrasts itself with the sibling get_feat or the other parse_* tools, so sibling differentiation is inferred rather than stated.

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

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

Usage is only implied by 'from disk' – there is no explicit when-to-use, no statement of when to prefer parsing over get_feat, and no prerequisites. The agent must infer the scenario rather than being routed to it.

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