Repair a failed flow step

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

Annotations only say it is a non-readonly, non-idempotent, non-destructive write; the description adds the crucial scope of that write — apply:true patches only 'simple selector steps', only at high/medium confidence, and refuses low-confidence cases with applied:false plus a note. That is real behavioral context an agent cannot get from the annotations, though it does not say what apply does when the step is not a simple selector.

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?

A single dense sentence, front-loaded with the primary action and the suggestion payload before the conditional apply behavior. The parenthetical clauses are compact and each carries information, though the nested parentheses make it slightly harder to parse at speed.

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 5-parameter mutation tool with no output schema, the description covers what is produced, what is mutated, the safety gate, and the failure outcome. It leaves a gap on the relationship between the flow and flowYaml inputs (which presumably select the target), but nothing essential to correct invocation is missing.

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 80%, so the baseline is 3, but the description adds genuine semantics for apply beyond the schema's 'patch the flow file when safe': it defines the confidence gate and the refusal outcome. The flow/flowYaml alternatives and sessionId remain unexplained in prose, keeping it below 5.

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 names a specific verb and resource ('Repair a failed flow step') and immediately scopes the output: a stronger locator suggestion plus app-side changes (testID/accessibilityIdentifier). That is far more specific than the title alone and distinguishes it from qa_flow_run or qa_flow_check, though no sibling is named explicitly.

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 through the apply flag and the failedStep reference to qa_flow_run.failedAtStep, which tells an agent this follows a failed run. However, there is no explicit statement of when to prefer this over re-running or re-checking a flow, and no guidance on choosing between the flow and flowYaml inputs.

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