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

The description adds substantial behavioral detail beyond the annotations: idempotent overwrite behavior, lifecycle applicability across open/fixed/dismissed findings, validation rules for judged_at_sha, reasoning audit requirements, judgment history append/update semantics, and severity-dependent auto-dismissal with autoDismissed in the result. These details are consistent with destructiveHint=true and provide useful operational context.

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 long but appropriately dense for a complex mutation tool with ten parameters and multiple validation and lifecycle rules. It is front-loaded with the primary action and then proceeds through eligibility, idempotency, error handling, SHA constraints, and auto-dismissal behavior without wasted sentences.

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 absence of an output schema, the description still reports key result behavior such as autoDismissed and autoDismissReason. It also covers all critical mutation semantics, validation constraints, and recovery guidance, leaving an agent well equipped to call the tool 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?

Although schema coverage is high, the description adds meaningful constraints not fully captured in the schema: finding_id is the only supported selector, judged_at_sha must be a full 40-character commit SHA from the actual code read and must not be outside the PR or precede the review SHA, and reasoning is required for later audit. It also clarifies that reason is not a substitute for reasoning.

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: applying a post-hoc triage verdict to a previously recorded finding. It explicitly distinguishes this tool from record_finding and list_pr_findings, and names the /reply-to-code-review flow in which it operates.

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?

It explicitly says when to use the tool, which findings can receive a verdict, how to locate them via finding_id from list_pr_findings, and what to do on a not_found response. It also explains that only findings recorded into the data layer are eligible, which prevents inappropriate calls.

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