Github List Pr Reviews

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

Annotations already cover readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: ordering ('oldest first'), scope ('submitted on a pull request'), and a clear definition of what a review is (as opposed to a comment). It does not mention pagination or empty-result behavior, but given the annotations, this is a minor gap.

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 sentences, with the primary purpose front-loaded. The second sentence removes ambiguity with a sibling tool, and the third offers a useful usage tip. The trailing 'See #408' is slightly cryptic but not distracting. Overall, each sentence earns its place with no wasted words.

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 tool's low complexity, an output schema exists, and annotations cover safety, the description is largely complete: it tells what is returned (reviews with author and verdict), the ordering, and distinguishes from comments. It lacks explicit pagination behavior, but the page/per_page params and output schema likely cover that. The only notable omission is guidance on what happens when no reviews exist, but this is minor.

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 40% (only page and per_page have descriptions, while repo_owner, repo_name, pr_number do not). The description adds no parameter meaning, failing to compensate for the low coverage. Although these are standard GitHub identifiers, the rubric mandates that low coverage requires description compensation, which is absent here.

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 action ('Lists the reviews submitted on a pull request'), a clear resource (reviews), and adds ordering ('oldest first') and content ('author and verdict'). It also explicitly distinguishes from github_list_pr_comments, preventing confusion with a sibling tool. This is a precise, unambiguous purpose.

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 provides an explicit exclusion: 'A review is not a comment… github_list_pr_comments returns what was said on lines and in the thread, not whether anyone approved.' It also directs the agent to github_get_pr_content for requested_reviewers, offering a concrete alternative for a related need. This fully guides when to use this tool versus others.

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