List pull requests

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

The description adds behavioral context beyond the readOnlyHint/openWorldHint annotations by specifying 'multi-page pagination' and 'compact triage-oriented response', which informs the agent about the tool's scope and output style. This is useful for setting expectations about fetching many items and the response format. No contradictions with annotations.

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 a single sentence, front-loaded with the core function, and includes two high-value behavioral hints without fluff. It earns a 5 for structure and efficiency.

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 rich schema with 100% parameter coverage and annotations indicating a safe read operation, the description covers the essential use case. The phrase 'compact triage-oriented response' gives a general sense of output, but without an output schema, a bit more detail on response fields could be helpful. Still, it is adequately complete.

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?

All 8 parameters have schema descriptions, so the schema carries the full semantic weight. The description mentions pagination behavior but not parameter specifics, so it adds no additional meaning to individual parameters. Baseline 3 is appropriate.

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 identifies the tool as 'List pull requests' with a specific verb+resource. It distinguishes from sibling get_pr by focusing on listing multiple PRs and mentions pagination and response style, which sets it apart from other PR-related tools.

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 implies a use case for triage-oriented overviews (compact response) and multi-page pagination, which helps an agent know when to use this tool over get_pr (which fetches a single PR). However, it does not explicitly state when not to use it or name alternatives, so it misses the full exclusion criteria for a 5.

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