biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Create feature

create_feat

Create a new feature record: assigns an ID, validates the body content, and writes the document to the feature base directory.

Instructions

Create a new feature: assigns a fresh id (caller-chosen via the optional 'id' parameter, or defaulted to feat-0- when omitted -- no max+1 auto-generation), derives a filename from the body's H1 title, validates the submitted body-only content, and writes the new document to the feature 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. Content validation runs BEFORE the id-shape ValueError and already-existing-id/folder FileExistsError guards, so a compound failure (invalid content + a malformed or already-existing id) returns the ValidateResult and the guard never runs in that call; each guard still raises whenever the content is valid. Returns the newly created document's frontmatter only (no body); use the corresponding get_feat tool to fetch the full document afterward.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No
`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.3/5.0

Behavior5/5

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

With no annotations, the description fully carries the behavioral burden and then some: it discloses that ids are NOT max+1 auto-generated, that validation failures return a non-raising ValidateResult and write nothing, that validation runs BEFORE the id-shape and FileExistsError guards, and that a compound failure short-circuits the guards. This is unusually rich pre-call context for an agent.

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 core action is front-loaded, but the single mega-sentence is bloated with internal traceability an agent cannot use: ADR UUIDs (f14f125e-..., 519d1206), issue numbers (#204, feat-110), and 'case 5 of the ... workaround chain'. This noise crowds out the actionable content and makes the definition hard to parse.

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 tool with real complexity (non-raising validation, guard ordering, frontmatter-only return), the description covers creation semantics, error behavior, and the follow-up read tool well. Since an output schema exists it need not document the return shape in detail, and it does not need to; a minor gap is that no permissions/auth context is given.

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% and the schema gives only bare 'Id'/'Content' titles, so the description must compensate. It thoroughly explains the optional 'id' (caller-chosen, default feat-0-<slug-from-title>, no max+1). 'content' is characterized as body-only content validated against a schema with an H1-derived filename, though the accepted content shape itself 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?

The first clause gives a specific verb and resource ('Create a new feature') and immediately elaborates the mechanics: id assignment, filename derivation from the H1, body validation, and the write. It is clearly distinguishable from sibling get_feat and the other create_* tools, since the resource is named.

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?

It explicitly routes the agent to the follow-up tool ('use the corresponding get_feat tool to fetch the full document afterward') and frames the return value accordingly. It does not, however, say when to create a feat vs. a tsk/gol/req or any prerequisites for creating a feature document, so no exclusions are given.

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

Deploy Server