biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Create feature

create_feat

Create a new feature document by validating body-only content, deriving a filename from its H1 title, assigning a caller-chosen or default id, and writing it 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. The structure reference is the get_feat_schema tool (the generated JSON Schema); the get_feat_template/get_feat_example tools return the authoring template and a complete sample. Returns the newly created document's frontmatter only (no body); use the corresponding get_feat tool to fetch the full document afterward.

Input Schema

Name	Required	Description	Default
`id`	No
`content`	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 / FeatFrontmatter / properties / status / enum
```
Added value: +[
+  "done",
+  "planning",
+  "progress",
+  "review"
+]
```
First observedv0.36.0Oct 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it explains caller-chosen vs default id behavior, no max+1 generation, filename derivation from the H1 title, content validation before id/existence guards, non-raising ValidateResult on invalid content, nothing written on failure, and that only frontmatter is returned. These are substantive details beyond the schema.

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?

The core behavior is front-loaded in the first sentence, but the description is a dense, overlong paragraph with many parenthetical references (ADR UUIDs, GitHub issue numbers, feat-110) that may not help an agent select or invoke the tool. It is informative but not tightly concise.

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?

Given the high complexity, low schema documentation, absence of annotations, and presence of an output schema, the description is complete enough: it covers creation, id semantics, validation failure behavior, guard ordering, write conditions, and retrieval follow-up. Return value explanation is present even though output schema exists.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate. It explains the optional 'id' parameter's caller-chosen behavior and default format, and describes 'content' as submitted body-only content that is validated before writing, adding meaning not present in the schema.

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 ('Create a new feature') and immediately explains the core mechanics: id assignment, filename derivation, validation, and writing to the feature base directory. It also distinguishes related siblings such as get_feat_schema, get_feat_template, get_feat_example, and get_feat for retrieval.

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?

The description clearly indicates this is for creating a new feature and points to get_feat_schema, get_feat_template, and get_feat_example for structure and authoring reference, plus get_feat for fetching the full document afterward. It does not explicitly contrast create_feat with edit/update_frontmatter or set_feat_id, so the when-not guidance is slightly incomplete.

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

Deploy Server