Skip to main content
Glama

list_pull_requests

Read-only

Retrieve pull requests for one repository with number, title, author, draft and merged status, branch details, and total counts; filter by open, closed, or all to review what needs attention.

Instructions

List the pull requests (PRs) of ONE repository: number, title, author, draft flag, branches, and whether it was merged, plus the total that match. Filter by open, closed or all. Use for 'open PRs', 'what is waiting for review', or 'which PRs were merged'. Do NOT use for issues (use list_open_issues or search_issues) or for the commit history of a branch (use get_recent_commits).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "repo": "<repo>"
    },
    "name": "list_pull_requests"
  }
}

Input Schema

NameRequiredDescriptionDefault
repoYesRepository as 'owner/name' (e.g. 'octocat/hello-world'). A bare name like 'hello-world' is resolved against the authenticated user's account.
limitNoMaximum number of items to return (1-50). Totals are reported separately, so a small limit is fine when only a count is needed.
stateNo'open' (default), 'closed' (merged or rejected) or 'all'.open

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.0

TDQS

A4.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the response includes a total-matching count reported separately from the item list, which implies a small limit still yields accurate counts. It stops short of mentioning rate limits, pagination, or auth requirements, keeping it at a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: what it returns, how to filter, when to use it, and when not to. The scope constraint and return fields are front-loaded, and the exclusions are compressed into a single sentence without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description's enumeration of returned fields and the separate total count carries the return-value burden, which it does well. For a three-parameter read-only list tool, an agent has everything needed to select and call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents repo format, limit bounds and default, and the state enum. The description reinforces the repo scoping constraint and the open/closed/all filter semantics in prose, but adds no new syntax beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('List the pull requests (PRs) of ONE repository') and enumerates exactly what comes back: number, title, author, draft flag, branches, merged status, plus the total matching count. The capitalized 'ONE' scopes the tool unambiguously and separates it from cross-repo or issue-oriented siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete trigger phrasings ('open PRs', 'what is waiting for review', 'which PRs were merged') and explicit exclusions with named alternatives: issues go to list_open_issues or search_issues, and branch commit history goes to get_recent_commits. Both the positive and negative routing conditions are stated, leaving nothing to inference.

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