diffci_verify

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

No annotations are supplied, so the description carries the full burden. It discloses two real behaviors: the result is a receipt tied to the checked-out HEAD, and the range is auto-derived from CI context when base/head are absent. It omits whether verification commands are executed (implied only by timeoutMs), what a failed verification means, and whether any state is written, which matters for a tool with a timeout and command-runtime implication.

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?

Two sentences, no filler, with the outcome and the default-range behavior front-loaded. Nothing could be removed without losing information.

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?

Placeholder.

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 100%, so all five parameters are already documented, including the base/head pairing constraint. The description adds only the omitted-parameter behavior (automatic CI range resolution); it says nothing extra about timeoutMs semantics or redactPaths effects beyond 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 specific verb ('Verify') and resource ('a clean commit range') plus the artifact returned ('a receipt bound to the checked-out head commit'). It does not differentiate itself from near-name siblings like diffci_verify_changed or diffci_verify_workflow, so an agent cannot tell from the description alone which verify variant applies.

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 second sentence gives one useful usage rule: omit base and head to auto-resolve the CI event range. There is no guidance on when to pick this over diffci_verify_changed, diffci_check, or diffci_verify_workflow, which is the main ambiguity an agent faces given the sibling set.

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