request_changes

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

With no annotations, the description carries the behavioral burden well: it discloses the rework intent, the requirement to close all prior findings, reviewRunId ownership, and the state transition back to ready requiring a new execution runId. It does not cover permissions, error behavior, or full side effects, but the core state-changing behavior is clear.

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 three dense sentences with no wasted wording. The action is front-loaded, followed by the key validation rule and then the ownership/state-transition behavior.

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 mutation tool with six parameters, nested finding arrays, no annotations, and no output schema, the description covers the critical business rules and state transition. It still leaves some parameter semantics and failure modes unexplained, but it is largely complete for correct invocation.

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 must compensate. It adds important meaning for findings (trigger, impact, evidence), findingClosures, and reviewRunId ownership, but it does not explain taskId, summary, actorLabel, findingIndex, status values, or the command/result evidence structure.

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 a specific review action: returning a claimed review for rework with actionable findings and finding closures. This distinguishes it from approval or completion actions, though it does not explicitly name the sibling alternatives.

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 gives clear context for when to use the tool: returning a claimed review for rework and requiring every previous finding to be closed on re-review. It also states a key ownership prerequisite for reviewRunId, but it does not explicitly contrast this with approve_review or give when-not guidance.

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