biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Create free-form text

create_txt

Creates a new free-form text document with a fresh id, a filename derived from its H1 title, and validated body content, or adds a translated language variant of an existing document.

Instructions

Create a new free-form text document: assigns a fresh id, derives a filename from the body's H1 title, validates the submitted body-only content, and writes the new document to the free-form text 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. The structure reference is the get_txt_schema tool (the generated JSON Schema); the get_txt_template/get_txt_example tools return the authoring template and a complete sample. Returns the newly created document's frontmatter only (no body); use the corresponding get_txt tool to fetch the full document afterward. The optional language parameter (default 'en', feat-197-i18n) selects the language to create the document in: omitted/'en' = a new flat docs/txt/ document with a fresh id, exactly the default behavior (id must then be omitted); a non-default ISO 639-1-shaped lowercase two-letter code (e.g. 'de') creates a TRANSLATION of an existing free-form text document instead: id -- the shared id of the existing EN source document -- is then required (no fresh id is assigned; the variant carries the same id), the EN source must exist (else TxtNotFoundError), and the variant is written to docs/txt/{language}/ under the EN source's exact file name with status draft; content is validated through that language's heading-mapping table (translated headings are accepted) and persisted verbatim. An existing variant of that id and language is never overwritten (FileExistsError). A malformed language, one with no packaged heading-mapping table, a missing id for a non-default language, or an id given for the default language is a ValueError raised before any file access.

Input Schema

Name	Required	Default
`id`	No
`content`	Yes
`language`	No	en

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.38.0Nov 2, 2026

TDQS

A4.6/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: it discloses the non-raising ValidateResult on validation failure (valid=False, single errors[].message capped at 300 chars) and that nothing is written in that case, the exact error types (TxtNotFoundError, FileExistsError, ValueError raised before any file access), and that an existing variant is never overwritten. It also states the return shape (frontmatter only, no body) and the on-disk path for translation variants.

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 action is front-loaded, but the text is one very long paragraph dense with internal provenance citations (feat-110, ADR f14f125e-eaad-4f4f-a6fd-3c931bed726e, GitHub issue #204, ADR 519d1206 workaround chain, feat-197-i18n) that add no decision-relevant meaning for an agent. Splitting the two modes and the error contract into separate sentences would materially improve scanability.

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?

For a three-parameter mutation tool with no annotations, the description covers every decision point: mode selection, id requirements per mode, validation and failure semantics, error types, file placement, overwrite protection, and the fact that only frontmatter is returned (with an output schema present, no further return-value detail is needed).

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 and it does: 'id' is explained as the required shared id of the EN source for a non-default language and as forbidden for the default language, 'language' is constrained to a lowercase ISO 639-1-shaped two-letter code with 'en' as default, and 'content' is described as body-only, validated against the language's heading-mapping table, and persisted verbatim.

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 opening clause gives a specific verb and resource ("Create a new free-form text document") and immediately enumerates the concrete effects: fresh id assignment, filename derived from the H1 title, validation of body-only content, and write to the free-form text base directory. It is clearly distinguishable from siblings like create_prb/create_req and from the read-side get_txt family.

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 routes the agent to the right companion tools (get_txt_schema for structure, get_txt_template/get_txt_example for authoring, get_txt to fetch the full body afterward) and draws an explicit line between the two modes: omit 'language' for a new document, pass a two-letter code to create a translation. What is missing is any when-not-to-use guidance versus the many other create_* tools and versus 'edit'/'update' when the intent is to modify rather than create.

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

Deploy Server