review_changes

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

Beyond the annotations it discloses the critical async behavior ("returns right away with the new execution and does not wait for a verdict") and the side-effect boundary ("The reviewer never edits files"). The readOnlyHint=false annotation is consistent with a tool that enqueues a new execution, so no conflict arises with the "read-only REVIEW" phrasing.

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 core action and its synchronous/asynchronous contract are front-loaded in the first two sentences. Every remaining sentence carries distinct information: the no-file-edit guarantee, the follow-up tool chain, and the workflow-vs-manual condition.

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?

An output schema exists, so return values need not be enumerated, yet the description still notes that the new execution is returned. Combined with the follow-up path and side-effect boundary, nothing an agent needs to call and correctly sequence this tool is missing.

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 coverage is 100%, with task_id, project_id, instruction, and context_version all documented in the schema, including the version-conflict consequence of a stale context_version. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

"Queue one independent, read-only REVIEW of a task's changes, run by whichever provider the project configured for REVIEW" gives a specific verb (queue), resource (review of task changes), and scope (one, independent, provider-configured). It is clearly distinguishable from dispatch_agent and the normal workflow, which do not describe an additive review request.

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 states explicitly when to call it ("call this to request an additional review") and when it is normally unnecessary ("The workflow normally dispatches REVIEW itself after implementation"). It also routes the agent through the follow-up sequence: wait_for_task or get_task_status, then get_task_result.

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