Verify the delta

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

The description discloses critical behavior not present in annotations: fail-closed semantics, error/timeout/truncated/stale handling that returns UNKNOWN or ERROR, and explicit refusal to report clean. It also explains demo-mode simulation and the requirement for a non-simulated final-wave VERIFIED result. This far exceeds what the readOnlyHint/destructiveHint annotations convey.

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 compact and front-loaded with the core action, then systematically covers failure behavior and demo mode. Each sentence contributes distinct value without filler, making it easy to scan.

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?

Given the presence of an output schema and annotations, the description is strong on failure modes and demo behavior. It doesn't explicitly identify the authoritative source or pipeline prerequisites, but the canonical playbook references in the schema fill most gaps. It is complete enough for safe use in most scenarios.

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 schema already documents all three parameters with descriptions (plan_hash, wave, json_output), so the baseline is 3. The description adds 'final-wave' context that relates to the wave parameter and mentions demo mode, but it doesn't add new syntax or value formats beyond what the schema provides.

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 re-queries the authoritative source and diffs against the baseline, which is a specific verb+resource. It does not explicitly name sibling alternatives, so it stops short of full differentiation, but the verification intent is 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?

The description provides clear context: this is used to verify a delta before closing a change record, with important caveats like 'fails closed' and 'only a non-simulated, final-wave VERIFIED result permits closing.' It does not explicitly say when not to use it or name alternative tools, but the when-to-use is evident.

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