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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it explains that the tool refuses if expected_version doesn't match, that any workspace editor can call it, and that it answers step_up_required for REPAIR holds. It also states the return format (run receipt). No contradictions with annotations.

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 dense but every sentence contributes to usage, exclusions, parameter meaning, permissions, and follow-up. It is front-loaded with the core purpose and conditions, then flows logically. It could be slightly trimmed (e.g., the REPAIR explanation), but it remains efficient and well-structured.

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 niche legacy tool, the description covers when to use it, when not to, how to pass the correct expected_version, permission context, the REPAIR hold exception, the return value, and the next recommended step (run_events). No output schema exists, but the description states the return type. This is a complete and actionable definition.

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 0%, so the description carries the burden. It explains expected_version thoroughly: 'Pass expected_version from the get_run that showed you the preview, so a run that moved in between is refused rather than released.' It also provides an example with both parameters. run_id is self-explanatory as the run to approve, though not explicitly described; the example clarifies its usage.

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 clearly states the tool's purpose: to release a legacy preview hold for an existing full run. It distinguishes from new full builds and REPAIR holds, making the function unambiguous and easily differentiable from siblings like confirm_run.

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 gives explicit conditions for use: 'Call it ONLY once the legacy preview has sealed a table you have checked and the user has said to build the whole thing, or on a delegation you recorded with write_note.' It also explicitly excludes new full builds and REPAIR holds, stating the alternative (a person in a signed-in browser) for REPAIR holds. This is comprehensive routing guidance.

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