apply_segments

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.