prepare_field_label_candidate

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

The readOnlyHint annotation already establishes the safe, non-writing nature, and the description reinforces that with 'No writes.' It adds some context by noting the hashes should be reviewed and that the result is a local set, but it does not explain hash validation, failure behavior, persistence, or what happens after the candidate is built.

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 definition is a single front-loaded sentence with no filler. It efficiently states the action, the local/non-writing nature, and the hash inputs, though the phrase 'reviewed baseline, source and target definition hashes' is dense and slightly opaque.

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 eight-parameter tool with seven required arguments, nested objects, no output schema, and a crowded sibling set, one sentence is insufficient. The description omits workflow context, output expectations, and enough parameter meaning to help an agent construct baseline/source/target and hash inputs correctly.

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?

The description references baseline, source, target, hashes, and selections only at a high level, while the schema itself documents just one of eight parameters. With 13% schema description coverage, the description should compensate but does not explain the baseline/source/target object shapes, hash format, or selection structure beyond the phrase 'explicitly selected localized field label changes.'

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 and resource: build a local set of localized field label changes. It also names the key inputs (baseline, source, target, hashes) and clarifies that no writes occur. It does not explicitly differentiate this from similar siblings like stage_isolated_field_labels or prepare_field_settings_candidate, so it stops short of a 5.

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 implies this is a non-writing preparation step through 'Build a local set' and 'No writes', but it gives no explicit when-to-use guidance and names no alternatives. It does not say when to choose this over stage_isolated_field_labels, prepare_field_settings_candidate, or any apply/publish tool.

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