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

With no annotations, the description carries the full load and does well: it discloses that candidates are recomputed and selections validated against them, that failures come back in rejected[] with a reason, that provide changes the product rather than the document, that output is re-verified, and that nothing is written unless write is true. It omits permission/auth requirements and any note on partial-apply atomicity.

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 and nearly every sentence adds operational information. The middle sentences are dense and parenthetical-heavy, which slows parsing, but there is little outright waste.

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?

For a 9-parameter tool with nested objects and no output schema, the description compensates by enumerating the return payload (xml, applied[], rejected[], verification, remaining fixes) and the write/overwrite conditions. A short note on failure modes when selections partially match or on the CSDB folder resolution would close the remaining gap.

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 already 89%, so the schema documents most parameters on its own. The description adds meaningful semantics for selections (location + one candidate, action/target/value) and the provide→product mapping, but does not touch path, csdbDirs, or maxFixes beyond what the schema says.

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 and resource ("Apply fixes to an existing data module") and ties it to the upstream suggest_fixes output shape, so an agent knows this is the selection/commit step. It does not differentiate from the listed sibling apply_segments, which is a plausible source of confusion.

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?

Implicitly and explicitly establishes the workflow: take a location plus ONE candidate returned by suggest_fixes and pass it back, with "provide" candidates routed through the product parameter. It gives a clear condition for rejection but no explicit statement of when to prefer this over alternatives or when not to use it.

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

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

With no annotations, the description carries the full burden and does well: it discloses the skeleton-mismatch failure mode, the per-segment non-application rules (unknown/duplicate id, {n} placeholder mismatch) with the original sentence preserved, and that writes only occur when `write` is true. It omits overwrite-conflict and allowInvalid behaviors, which are only documented in 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.

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

Purpose is front-loaded in the first sentence, followed by output shape, failure mode, partial-application rules, and the write gate in a tight sequence. Every sentence carries distinct information with no filler.

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?

For an 11-parameter, nested-schema tool with no output schema, the description covers the critical behaviors (hash guard, unapplied[], verification, write gating). The response structure beyond `unapplied[]` and `error.code` — e.g., write-conflict reporting and remaining-fixes listing — is not described, though the schema hints at them.

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 100%, so the baseline is 3, but the description adds real meaning: `language` is the only thing that changes in the output, `issueInfo` is optional, `skeletonHash` is the value from extract_segments, and segment `text` must preserve {n} placeholders. `maxFixes` and `csdbDirs` are left entirely to the schema.

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 concrete verb and resource: putting translated sentences back into the data module they came from, and names the inverse relationship to extract_segments. An agent can immediately tell this apart from build_data_module (new content) and extract_segments (the source of the segments).

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?

The description makes the workflow clear by tying skeletonHash to extract_segments and by gating writes on `write`. It does not explicitly say 'call extract_segments first' or name when not to use it (e.g., new content belongs in build_data_module, which only appears in the schema), so usage is strongly implied rather than fully spelled out.

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

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

With no annotations, the description carries the full burden and does: it discloses the verification chain (XSD, BREX along brexDmRef, references, applicability), the bounded auto-fix loop with confidence "exact" and maxFixRounds, the two-tier fix reporting (appliedFixes vs fixes), write gating on write:true, and the input-error code. It also states the server keeps no state and the ledger must be round-tripped.

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?

Front-loaded with the action and scope in the first clause, then verification behavior, then return values, then the write gate, then the error case — a sensible priority order. It is long but nearly every clause carries information; the 'you never write XML, DMCs, ICNs or the BREX reference' aside earns its place by preventing wasted effort.

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?

With 11 parameters, deep nesting and no output schema, the description correctly enumerates the return shape (xml, fileName, dmCode/pmCode, verification, appliedFixes, fixes, ledger, next ICN) and the failure mode. The remaining gap is routing the residual fixes[] to the sibling apply_fixes, and any note on required CSDB directory setup.

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 description coverage is 100%, so both the draft tree and allocation are already documented field by field. The description adds framing (you supply titles/paragraphs/steps/tables/figures/references, never XML/DMC/ICN/BREX text) and names maxFixRounds, but contributes no new per-parameter semantics. Baseline 3 is right.

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 and resource — build ONE data module of a stated set of kinds or a publication module — from a structured draft, and says the DMC/PMC comes from allocation rules. The scope (one object per call) and the output artifacts are 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 implied rather than stated: the description never says when to pick this over the sibling apply_fixes for leftover fixes[], nor when to re-run rather than patch. The write:false / write:true split hints at a preview-then-commit workflow but requires the agent to infer it.

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

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

With no annotations, the description carries the full burden and does so: it discloses the build/verify/auto-fix/verify loop, that references are resolved against the CSDB plus DMs built in this call, what write:true actually copies (originals renamed to ICN), and the default of no writes at all. It also names the response fields (dataModules[], publicationModule, assets[], ledger, notRepresented), which is the behavioral contract 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?

Front-loaded with the verb and the kind mapping, and nearly every clause carries information (topic→DM kind mapping, verification loop, return fields, write default). It is a dense single block with no visual structure, which makes it heavier than it needs to be for its length.

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?

For a 21-parameter mutation-capable tool with no annotations and no output schema, the description covers the write semantics, the verification pipeline, the response shape and the limits of the draft format (notRepresented). The remaining depth on parameters like allocation.ledger and issuePolicy lives in the schema, so nothing critical is missing, though a note on failure/partial-write behavior would complete it.

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 description coverage is 90%, so the schema already explains allocation, ledger, issuePolicy, allowInvalid and the rest. The description adds value mainly for write and for the return shape rather than for individual parameters, 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?

Opens with a specific verb and resource ('Convert an experiential operation manual ... into S1000D') and then enumerates the exact output artifacts (one PM, one DM per topic with kind mapping, glossary DM, ICNs). It explicitly names the sibling relationship to build_data_module, so an agent can distinguish whole-manual conversion from single-DM building.

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 clear from context: this is the batch/manual-level path, and 'Every data module goes through the same flow as build_data_module' tells the agent how the two relate. It also states the glossary-only-when-all-topics rule and that nothing is written unless write is true. It stops short of an explicit 'use build_data_module instead when you have a single DM' routing sentence.

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

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

With no annotations, the description carries the burden and does well: it discloses that enumerations are passed through uninterpreted, that the sequence number defaults to the next free one in the CSDB, that output is verified against comment.xsd and BREX, that the response contains xml/fileName/commentCode/verification/fixes[], and that nothing is written unless write is true. It omits overwrite-conflict and allowInvalid semantics, though the schema covers those.

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 dense sentences with the resource identity front-loaded and no filler. The first sentence is long and packs the field list into one clause, but every clause carries information an agent needs.

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?

For a 22-parameter, deeply nested tool with no output schema, the description supplies the return shape (xml, fileName, commentCode, verification, fixes[]) and the write-safety model, which are the two biggest gaps. Missing pieces — directory resolution and invalid-write override — are already documented on the corresponding schema properties.

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 description coverage is 68%, so the schema does most of the work for the 22 parameters. The description adds real meaning for a few — comment type (q/i/r), priority range cp01–cp99, paragraphs, originator/sender, and the seqNumber default — but leaves the majority of parameters (refs, csdbDirs, brexDmRef, responseType, maxFixes) to the schema.

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 and resource — build a comment data module (comment.xsd) — and defines the resource precisely as a remark about data modules, publication modules, DMLs or DDNs. It does not explicitly contrast itself with the sibling build_data_module, so an agent must infer the split from the resource noun rather than from a stated exclusion.

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?

The only conditional guidance is 'Writes only when write is true', which is about mode rather than tool selection. There is no statement of when to prefer this over build_data_module, nor prerequisites such as an existing CSDB or BREX. Usage is implied by the resource description alone.

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

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

With no annotations, the description carries the burden and discloses substantial behavior: segment structure (stable id, XPath, context hint, text), inline placeholder rules, excluded values (attribute values, DMCs, ICNs, applicability expressions, ids), and the skeletonHash return. It still does not explicitly state read-only status, file/auth constraints, or error behavior, so it is not fully complete.

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?

The description is front-loaded and dense, moving from purpose to segment structure to exclusions to the apply_segments linkage. Each sentence contributes, though the middle sentences are information-heavy and could be split for readability.

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?

No output schema exists, so the description must explain returns, and it does: segments with id, XPath, context hint, text, plus skeletonHash. It omits how maxSegments truncation behaves, error cases, and file access expectations, but for an extraction tool with fully documented input parameters, it is largely complete.

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 description coverage is 100%, so the schema already documents all four parameters. The description mentions the content categories corresponding to the include enum and the placeholder convention, but it adds no syntax or format meaning for xml versus path or for maxSegments behavior beyond the schema. Baseline 3 is appropriate.

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 uses a specific verb and resource: 'Take the sentences that a person reads out of a data module so they can be translated.' It enumerates the exact content types returned and explicitly excludes technical values, making it distinguishable from sibling tools like build_data_module and apply_segments.

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?

It gives a clear usage context: extraction for translation, then pass the skeletonHash to apply_segments. It also states what the server does not do (translate or score). However, it does not explicitly name when not to use this tool versus alternatives such as build_data_module or convert_manual, leaving some routing to inference.

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