Skip to main content
Glama
bitbucket-mcp

bitbucket-mcp

by nevzatcirak

List pull requests

bb_list_pull_requests

Lists a repository's pull requests and filters by state, direction, or author, helping AI agents triage incoming and outgoing code review work.

Instructions

List pull requests of a repository. Filter by state (OPEN|MERGED|DECLINED|ALL), direction (INCOMING|OUTGOING) and optionally by author (client-side match on username or display name — paging metadata reflects unfiltered pages).

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": {
      "projectKey": "<projectKey>",
      "repositorySlug": "<repositorySlug>"
    },
    "name": "bb_list_pull_requests"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoOne-based page number (Cloud only; from nextPageStart of the previous call). Ignored on Server/DC.
limitNoPage size (1-1000).
startNoZero-based page offset (Server/DC).
stateNoPull request state filter.OPEN
authorNoFilter by author username or display name (case-insensitive, client-side).
directionNoINCOMING: into this repository's branches; OUTGOING: from this repository's branches.INCOMING
projectKeyYesProject key (on Cloud: workspace slug).
repositorySlugYesRepository slug, e.g. 'service-api'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden, and it does disclose one genuinely valuable trait: the author filter is a client-side match and paging metadata reflects unfiltered pages. However, it says nothing about read-only nature, permissions required, result ordering, or what a page of results contains, leaving meaningful behavioral gaps.

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

Conciseness4/5

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

Two dense sentences with the operation front-loaded and filters following; every clause carries information. The em-dash parenthetical is slightly compressed but not wasteful.

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

Completeness4/5

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

For an eight-parameter query tool with no output schema and no annotations, the description covers the filtering surface and the one non-obvious caveat about client-side author filtering and paging metadata. Return shape need not be explained without an output schema, though permission or ordering context would round it out.

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

Parameters3/5

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

Schema description coverage is 100%, so page, limit, start, state, direction, projectKey, and repositorySlug are all documented in the schema itself; baseline is 3. The description restates the state and direction enums already visible in the schema, adding only the paging-vs-author-filter interaction, which is marginal added meaning.

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

Purpose4/5

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

The description names a specific verb and resource ("List pull requests of a repository") and enumerates the filter dimensions, so the agent knows exactly what operation this performs. It does not explicitly contrast with sibling list-style tools such as bb_get_dashboard_pull_requests or bb_get_inbox_pull_requests, relying on "of a repository" to imply the scope difference.

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

Usage Guidelines3/5

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

Usage is implied by the filter enumeration — an agent can infer this is the tool for browsing PRs within a single repository with state/direction/author narrowing. There is no explicit statement of when to prefer this over the dashboard or inbox PR tools, and no prerequisites or exclusions are given.

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