txt_to_docx

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

Annotations only cover the safety profile (idempotent, non-destructive); the description adds real behavioral substance: one paragraph per line, tabs preserved, form feeds become page breaks, and unencodable characters are refused with positions rather than dropped. That failure-mode disclosure is genuinely useful and not recoverable from the schema. It omits overwrite semantics (default false) and report behavior timing, keeping it short of a 5.

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?

Four tight clauses, conversion rules front-loaded, no filler sentences. The final sentence ('The report checks text and numbers') is somewhat cryptic and the '[docbridge schema 0.2.4]' tag is low-value, but overall density is high.

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 need not be explained, and this is a non-destructive, idempotent writer. However, for a file-writing tool the description never states what happens when output_path exists without overwrite, nor how encoding and the report parameters interact with the conversion summary it advertises. Adequate but with clear gaps for a 7-parameter mutation tool.

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?

Schema coverage is 57%, and the schema already documents detail, encoding, and max_differences well. The description references the report ('The report checks text and numbers') without tying it to report_path, detail, or max_differences, and never mentions overwrite or output_path defaults. Marginal added meaning over the schema, so the baseline 3 applies.

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?

The description states a specific verb+resource direction ('DOCX from plain text') and enumerates the exact text-to-DOCX mapping rules, which distinguishes it from markdown_to_docx and other conversion siblings. It never uses the tool name's phrasing, so an agent must infer that txt_to_docx is the txt→docx converter, but the transformation semantics make the intent unambiguous.

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 the input format ('plain text', 'a .md/.txt input'). There is no explicit when-to-use versus markdown_to_docx or when-not guidance, and the version tag '[docbridge schema 0.2.4]' occupies space that routing guidance could fill. An agent can guess the right tool from the format description but gets no help choosing between the sibling converters.

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