List pull requests

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description adds cost/effort context ('one API call'), a batch-safety declaration, and the returned field structure. It does not mention auth/permission requirements or provider-specific rate limits, which keeps it below a 5.

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?

Front-loaded with the core action, then cleanly labeled sections that are easy to scan. Slight redundancy between 'read-only and batch-safe' in the Speed line and the separate 'Batch-safe: yes' line, plus an Output line that partially duplicates schema knowledge.

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?

With no output schema, the description explicitly enumerates the return shape (pr_list: repo, provider, state, total, prs[] with number/title/state/draft/head/base/author/url), covering what the agent needs to consume the result. All six params are schema-documented, so no gaps remain for a filtered-list tool.

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 100%, so every parameter including defaults and the repo resolution chain is already documented in structured data. The description only restates the state/head/base filters at a high level without adding format or syntax detail, 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?

States a specific verb and resource ('List pull/merge requests for a repo') plus the supported filters (state, head, base branch). It also implicitly distinguishes itself from write-oriented siblings by routing agents to project_pr_comment / project_pr_merge when the PR number is already known.

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?

Contains explicit 'Use when' and 'Avoid when' clauses, including the concrete trigger (needing the PR number for a branch before commenting/merging) and the exact alternative tools to use instead. Nothing about tool selection is left to inference.

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