review_reply

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that question replies receive answers later via review_wait and that notes do not resolve the thread, but it omits permission requirements, whether the thread must already exist, and other side effects of posting.

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 definition is front-loaded with the core action and uses two compact sentences. The second sentence is dense with kind-specific clauses, but each clause provides useful selection guidance rather than wasted wording.

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 simple three-parameter posting tool with no output schema, the description covers purpose and the key behavioral difference between note and question. It is less complete on tool-level alternatives and threading prerequisites, but remains sufficient for an agent to call it correctly in most cases.

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 only 33%, and the description meaningfully elaborates the kind enum by explaining question timing and note behavior. It adds little or no meaning for comment_id or text beyond what their names imply, so the low schema coverage is only partially compensated.

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: "Post a message in a comment thread," and adds placement context ("shown in the margin next to the text"). It does not explicitly differentiate this action from the sibling review_comment tool, leaving some ambiguity.

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 gives clear guidance for choosing kind=question versus kind=note, including that answers arrive in a later review_wait. However, it does not explain when to use review_reply instead of sibling tools such as review_comment, review_threads, or review_resolve, so tool-level usage is only implied.

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