Skip to main content
Glama
RajuSudhar

Atlassian Bitbucket MCP Server

by RajuSudhar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Atlassian Bitbucket MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Atlassian Bitbucket for pull request reviews, code search, and repository operations.

Features

  • Pull Request Management: Review PRs, add/resolve comments, approve changes

  • Batched Reviews: Queue comments and tasks as pending, then publish them in one review — the API equivalent of Bitbucket's Start review / Finish review

  • Code Search: Search code across repositories and commits

  • Repository Operations: List repos, browse branches, view file content

  • Dual Instance Support: Works with both Bitbucket Cloud and self-hosted Data Center/Server

  • Secure: Built with security in mind, avoiding compromised npm packages

  • Type-Safe: Full TypeScript implementation with strict type checking

  • Caching: Smart caching layer for frequently accessed static data

  • Local-First: Designed for NPX-based local usage with Personal Access Tokens

  • CI Helper: atlassian-bitbucket-mcp/helper subpath export for direct programmatic use in CI scripts — no MCP client required

Related MCP server: bitbucket-mcp

Requirements

  • Node.js >= 20.0.0

  • pnpm

  • Bitbucket Personal Access Token (Cloud or Server/Data Center)

  • Access to a Bitbucket instance (Cloud or self-hosted)

Quick Start

1. Environment Setup

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and set the required variables:

BITBUCKET_URL=https://bitbucket.juspay.net # Cloud: https://bitbucket.org
BITBUCKET_TOKEN=BBDC-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BITBUCKET_DEFAULT_PROJECT=BZ # your default project key

For a self-hosted Server/DC instance, set BITBUCKET_URL to the base URL only (e.g. https://bitbucket.juspay.net) — the server appends /rest/api/1.0 itself. A repo such as https://bitbucket.juspay.net/projects/BZ/repos/nimble has project key BZ and repo slug nimble.

2. Installation

Beta channel: the current release stream is 1.0.0-beta.0 on the npm beta dist-tag. Install with:

npm install atlassian-bitbucket-mcp@beta
# or
pnpm add atlassian-bitbucket-mcp@beta

The latest dist-tag is not published yet.

pnpm install

3. Build

pnpm run build

4. Usage with MCP Client

Configure your MCP client (e.g., Claude Desktop) to use this server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "atlassian-bitbucket-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.juspay.net",
        "BITBUCKET_TOKEN": "BBDC-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BITBUCKET_DEFAULT_PROJECT": "BZ",
        "BITBUCKET_ALLOWED_PROJECTS": "BZ",
        "BITBUCKET_ALLOWED_REPOS": "BZ/nimble"
      }
    }
  }
}

BITBUCKET_ALLOWED_PROJECTS and BITBUCKET_ALLOWED_REPOS are optional — omit them to allow all projects/repos the token can access, or set them to restrict the server to specific scopes.

This is the stdio transport: the MCP client launches the server per session. No port is involved.

5. Run as an HTTP MCP (local service)

The server can instead run as a long-lived Streamable HTTP server and be registered as a Claude HTTP MCP. Set MCP_TRANSPORT=http and it listens on http://127.0.0.1:3900/mcp (configurable via MCP_HTTP_PORT / MCP_HTTP_HOST; GET /health returns a readiness probe). Set MCP_TRANSPORT=https to serve the same endpoint over TLS — see below.

Security: the HTTP endpoint is unauthenticated and sits in front of your Bitbucket token — keep MCP_HTTP_HOST on loopback (127.0.0.1) and never expose it to a network interface.

On macOS, install it as an always-on login service (launchd LaunchAgent):

# Builds, installs globally, writes ~/.config/bitbucket-mcp/env (chmod 600),
# and loads a LaunchAgent bound to 127.0.0.1:3900.
./scripts/install-macos-service.sh
# then put your real BITBUCKET_TOKEN in ~/.config/bitbucket-mcp/env and:
launchctl kickstart -k gui/$(id -u)/com.juspay.bitbucket-mcp

Register it with Claude (available in every project):

claude mcp add --scope user --transport http bitbucket http://127.0.0.1:3900/mcp
claude mcp list # bitbucket ... ✔ Connected

Serving over TLS (MCP_TRANSPORT=https). The HTTP transport can serve TLS itself: set MCP_TRANSPORT=https plus MCP_HTTP_TLS_CERT_FILE and MCP_HTTP_TLS_KEY_FILE (paths to PEM files — both are required in https mode and ignored otherwise). Everything else (/mcp endpoint, sessions, /health) is identical to http mode. For a locally-trusted certificate, use mkcert:

mkcert -install && mkcert localhost 127.0.0.1
MCP_TRANSPORT=https
MCP_HTTP_TLS_CERT_FILE=/absolute/path/to/localhost+1.pem
MCP_HTTP_TLS_KEY_FILE=/absolute/path/to/localhost+1-key.pem

TLS adds encryption, not authentication — the endpoint is still unauthenticated, so keep MCP_HTTP_HOST on loopback in https mode too.

Self-hosted TLS / internal CA. If your Bitbucket uses an internal CA, the outbound HTTPS calls need to trust it. Set NODE_EXTRA_CA_CERTS=/path/to/ca.pem in the env-file. Avoid Node's --use-system-ca for the background service — it hangs under launchd because macOS keychain access requires an interactive session. (--use-system-ca is fine for a foreground/stdio run.)

Configuration

Environment Variables

All configuration is done through environment variables. See .env.example for the complete list.

Required

  • BITBUCKET_URL - Your Bitbucket instance URL

  • BITBUCKET_TOKEN - Personal Access Token

  • BITBUCKET_DEFAULT_PROJECT - Default project key

Optional

  • BITBUCKET_ALLOWED_ACTIONS - Comma-separated list of allowed tool actions

  • BITBUCKET_ALLOWED_PROJECTS - Comma-separated allow-list of project keys the server may touch (empty = all). Case-insensitive.

  • BITBUCKET_ALLOWED_REPOS - Comma-separated allow-list of repositories (empty = all). Each entry is PROJECT/REPO or a bare REPO slug. Case-insensitive.

  • BITBUCKET_CACHE_ENABLED - Enable/disable caching (default: true)

  • BITBUCKET_CACHE_TTL_REPOS - Repository cache TTL in seconds (default: 3600)

  • MCP_TRANSPORT - stdio (default), http, or https

  • MCP_HTTP_PORT / MCP_HTTP_HOST - HTTP transport bind (default 3900 / 127.0.0.1)

  • MCP_HTTP_TLS_CERT_FILE / MCP_HTTP_TLS_KEY_FILE - PEM certificate/key paths, both required when MCP_TRANSPORT=https (ignored otherwise)

  • NODE_EXTRA_CA_CERTS - PEM path for a self-hosted internal CA (outbound TLS)

  • BITBUCKET_MCP_CONFIG, BITBUCKET_MCP_MAX_OUTPUT_TOKENS, BITBUCKET_MCP_CONFIG_DIR — output-token-limit governor (see Per-tool output-token limits)

  • See .env.example for all options

Creating a Personal Access Token

Bitbucket Cloud

  1. Go to Personal settings > Personal Access Tokens

  2. Click Create token

  3. Give it a name and select permissions:

    • Repositories: Read, Write

    • Pull requests: Read, Write

  4. Click Create and copy the token

Bitbucket Server/Data Center

  1. Go to Profile > Manage account > Personal access tokens

  2. Click Create a token

  3. Give it a name and select permissions:

    • Project permissions: Read

    • Repository permissions: Read, Write

  4. Click Create and copy the token

Per-tool output-token limits

The server can withhold oversize tool responses and return an actionable guidance error instead of streaming a wall of content that blows past the caller's context budget. When enabled (it is, by default, at 25,000 tokens), each tool's response is estimated with gpt-tokenizer's o200k_base encoding scaled by 1.2× (Claude runs ~15–20% higher than GPT-4o for prose) and compared against a configurable per-tool limit.

Discovery precedence

The governor loads config from the first available source:

  1. BITBUCKET_MCP_CONFIG env var — absolute path. Errors at startup if the file does not exist.

  2. ./bitbucket-mcp.config.json — in the current working directory.

  3. $XDG_CONFIG_HOME/bitbucket-mcp/config.json — or ~/.config/bitbucket-mcp/config.json if $XDG_CONFIG_HOME is unset. $BITBUCKET_MCP_CONFIG_DIR overrides the directory portion of this lookup.

  4. Built-in default (25,000 tokens across all tools).

Environment variables

  • BITBUCKET_MCP_CONFIG — absolute path to the config file.

  • BITBUCKET_MCP_MAX_OUTPUT_TOKENS — integer > 0. Overrides defaults.maxOutputTokens from the file. Never overrides a per-tool value.

  • BITBUCKET_MCP_CONFIG_DIR — overrides the XDG config directory used for the fallback config path.

JSON config shape

bitbucket-mcp.config.json:

{
  "$schema": "./bitbucket-mcp.config.schema.json",
  "defaults": { "maxOutputTokens": 25000 },
  "tools": {
    "bitbucket_list_pull_requests": { "maxOutputTokens": 10000 },
    "bitbucket_search_code": { "maxOutputTokens": 10000 }
  }
}

The schema is strict — unknown keys fail startup, so typos in the config are caught immediately. bitbucket-mcp.config.schema.json is committed at repo root and can be regenerated with pnpm run schema:gen after any change to serverConfigSchema.

Per-tool tools.<name>.maxOutputTokens always wins over the default and cannot be overridden by env.

Scaffolding

atlassian-bitbucket-mcp init writes a starter config to the XDG default location. Flags: --config-path <path>, --max-output-tokens <n>, -y (overwrite existing).

atlassian-bitbucket-mcp help prints usage, discovery order, env vars, and JSON shape — offline reference for the same information above.

What the guidance error looks like

When a tool's response exceeds its limit, the caller receives an isError: true result whose text names the tool, the estimated token count, the configured limit, narrowing suggestions (reduce limit, filter by project/repo, call a single-item retrieval tool), and both ways to raise the ceiling (per-tool config entry or the env var). The full response is withheld — nothing is truncated silently.

Available MCP Tools

This server provides the following tools for interacting with Bitbucket:

Pull Request Tools

  • bitbucket_list_pull_requests - List PRs for a repository

  • bitbucket_get_pull_request - Get detailed PR information

  • bitbucket_get_pr_diff - Get PR changes/diff

  • bitbucket_get_pr_commits - Get commits in a PR

  • bitbucket_get_pr_activities - Get PR comments and activities

  • bitbucket_add_pr_comment - Add a general comment (pending: true queues it in your review session instead of posting it)

  • bitbucket_add_pr_inline_comment - Add a per-file, per-line inline code comment on any author's PR (path + line + lineType; diffType defaults to EFFECTIVE on Server/DC; supports pending)

  • bitbucket_reply_to_comment - Reply to a comment (supports pending)

  • bitbucket_resolve_comment - Resolve a comment thread

  • bitbucket_update_comment - Edit a comment

  • bitbucket_update_pull_request - Update a PR's title and/or description (Server/DC only, requires current version for optimistic locking)

  • bitbucket_approve_pr - Approve a pull request

  • bitbucket_create_pr_task - Create a checklist task (blocker-severity comment) on a PR, optionally as a reply to an existing comment (Server/DC only; supports pending)

  • bitbucket_list_pr_tasks - List checklist tasks on a PR (Server/DC only)

  • bitbucket_resolve_pr_task - Set a task to OPEN or RESOLVED (Server/DC only)

  • bitbucket_delete_pr_task - Delete a task (Server/DC only)

PR Review Session Tools

Server/DC 7.7+ only. See Batched reviews.

  • bitbucket_start_pr_review - Begin a batched review: reports what is already pending in your session and how to add more

  • bitbucket_get_pr_review - List the pending, unpublished comments in your session (visible only to you)

  • bitbucket_publish_pr_review - Publish every pending comment at once, with an optional overview commentText and reviewer participantStatus

  • bitbucket_discard_pr_review - Delete every pending comment without notifying the author

Repository Tools

  • bitbucket_list_projects - List accessible projects

  • bitbucket_list_repositories - List repos in a project

  • bitbucket_get_repository - Get repository details

  • bitbucket_get_branches - List repository branches

  • bitbucket_get_commits - Get commit history

  • bitbucket_get_file_content - Get file content at ref

Code Search Tools

  • bitbucket_search_code - Search code across repositories

  • bitbucket_search_commits - Search commits by message

See docs/TOOLS.md for detailed tool documentation (coming soon).

Batched reviews (Start review / Finish review)

Bitbucket Server/DC 7.7+ lets a reviewer queue feedback privately and release it in one go — Start review, then Publish or Discard review in the web UI. The server models this as comments in PENDING state, scoped to (pull request, authenticated user), so the same session is shared by the web UI and this MCP server and survives restarts of either.

There is no "start review" endpoint: Bitbucket opens the session the moment you create the first pending comment, and closes it on publish or discard.

bitbucket_start_pr_review        # optional: shows what is already pending
  ↓
bitbucket_add_pr_inline_comment  { ..., pending: true }   # repeat as needed
bitbucket_create_pr_task         { ..., pending: true }
  ↓
bitbucket_get_pr_review          # read back everything queued, edit if needed
  ↓
bitbucket_publish_pr_review      { commentText?, participantStatus? }
   or bitbucket_discard_pr_review

Notes:

  • pending defaults to false, so every existing call site keeps posting immediately. Nothing changes unless you opt in.

  • Pending comments are invisible to the PR author and to other reviewers until published; bitbucket_get_pr_activities will not show them.

  • Queued comments can be edited (bitbucket_update_comment) or deleted while still pending — a pending comment carries an ordinary comment id/version.

  • bitbucket_publish_pr_review returns { "publishedCommentCount": N }. participantStatus is one of UNAPPROVED, NEEDS_WORK, APPROVED; omit it to publish without changing your verdict. Supplying it requires the manage_pr action, since it changes approval state.

  • bitbucket_discard_pr_review deletes all pending comments for the PR — it is not undoable, and the author is never notified.

  • On Bitbucket Cloud, and on Server/DC older than 7.7, the /review endpoints do not exist and these four tools return a 404-derived error.

Programmatic usage (CI)

Besides running as an MCP server, the package exposes the Bitbucket API layer directly as a library via the atlassian-bitbucket-mcp/helper subpath export — useful for CI jobs that need to comment on a PR without an MCP client in the loop. There is no permission or scope gating on this path: the script holds the token, so it can do whatever the token can.

import { createBitbucketHelper } from 'atlassian-bitbucket-mcp/helper';

// Explicit options override env; anything omitted falls back to
// BITBUCKET_URL / BITBUCKET_TOKEN / BITBUCKET_DEFAULT_PROJECT.
const helper = createBitbucketHelper({
  url: 'https://bitbucket.juspay.net',
  token: process.env.BITBUCKET_TOKEN,
  defaultProject: 'BZ',
});

const pr = await helper.pullRequests.get('BZ', 'nimble', 42);
await helper.pullRequests.addComment('BZ', 'nimble', 42, `CI passed for "${pr.title}"`);

Notes:

  • helper.pullRequests, helper.repositories and helper.search group the API by resource — the same operations as the MCP tools (list/get PRs, diffs, commits, comments, tasks, review sessions, approve, branches, file content, code/commit search). Every method is pre-bound, so destructuring is safe (const { addComment } = helper.pullRequests).

  • helper.client is the escape hatch for raw REST calls (client.requestJson(endpoint, { method, body, queryParams })); helper.config is the resolved effective config — it contains the token, so never log or serialize it.

  • Error classes (BitbucketApiError, NetworkError, TimeoutError) and the relevant Bitbucket types are re-exported from the same subpath for instanceof checks and typing.

  • Optional tuning: requestTimeout, maxRetries, rateLimitDelay options (or BITBUCKET_REQUEST_TIMEOUT / BITBUCKET_MAX_RETRIES / BITBUCKET_RATE_LIMIT_DELAY). Caching is always disabled in helper mode.

  • The package is ESM-only ("type": "module") — use import, not require.

Development

VSCode Setup (Recommended)

This project includes VSCode workspace settings and extension recommendations. When you open the project in VSCode, you'll be prompted to install:

  • ESLint - Code linting

  • Prettier - Code formatting

  • Markdownlint - Markdown style checking

All formatting and linting happens automatically on save.

Development Commands

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Watch mode for development
pnpm run watch

# Run with local changes
pnpm link --global

# Code quality checks
pnpm run format:all # Format all files
pnpm run lint:all   # Lint all files (markdown + code)
pnpm run typecheck  # Type check with TypeScript
pnpm run validate   # Run all checks (format + lint + typecheck)

Git Hooks

This project uses Husky for Git hooks to maintain code quality and consistency:

Pre-commit Hook

Automatically runs before each commit:

  1. Prettier - Formats all code

  2. ESLint - Lints and auto-fixes issues

  3. TypeScript - Type checks the code

  4. Build - Ensures project compiles

This ensures all committed code meets quality standards.

Commit Message Hook

  • Enforces Conventional Commits format

  • Valid formats: <type>(<optional-scope>): <description>

  • Allowed types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert

  • Examples:

    • feat: add user authentication

    • fix(auth): resolve login bug

    • docs: update README

Pre-push Hook

  • Validates branch naming convention

  • Allowed patterns:

    • main, master, develop, dev

    • feature/<description>, feat/<description>

    • bugfix/<description>, fix/<description>

    • hotfix/<description>

    • release/<version>

    • chore/<description>, docs/<description>

  • Examples:

    • feature/user-authentication

    • fix/login-bug

    • release/v1.0.0

Project Structure

atlassian-bitbucket-mcp/
├── .husky/              # Git hooks
│   ├── commit-msg       # Conventional commits validation
│   ├── pre-commit       # Code quality checks
│   └── pre-push         # Branch name validation
├── docs/                # Documentation
│   ├── ARCHITECTURE.md  # System architecture and design
│   ├── CODING-STANDARDS.md  # Coding standards and best practices
│   ├── BRANCH-MANAGEMENT.md  # Branch naming and management
│   └── SECURITY.md      # Security policy
├── scripts/             # Utility scripts
│   ├── check-package-security.sh
│   ├── pre-commit.sh    # Pre-commit validation script
│   ├── pre-push.sh      # Pre-push validation script
│   ├── commit-msg.sh    # Commit message validation
│   ├── validate-branch-name.sh  # Branch name validator
│   └── setup-vscode.sh  # VSCode workspace setup
├── types/               # Shared TypeScript type definitions
│   ├── index.ts         # Type re-exports
│   ├── bitbucket.ts     # Bitbucket API types
│   ├── mcp.ts           # MCP protocol types
│   ├── config.ts        # Configuration types
│   ├── cache.ts         # Cache types
│   ├── logger.ts        # Logging types
│   └── common.ts        # Common utility types
├── src/                 # MCP server implementation
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration
│   ├── cache.ts         # Caching layer
│   ├── logger.ts        # Centralized logging
│   ├── tools/           # MCP tool implementations
│   └── bitbucket/       # Bitbucket API client
├── openapi/             # OpenAPI specifications (future)
│   ├── bitbucket-cloud.yaml
│   └── bitbucket-server.yaml
├── package.json
├── tsconfig.json
└── README.md

Security

This project follows security best practices:

  • All dependencies are checked against known compromised packages

  • Minimal dependency footprint

  • Regular security audits

  • See docs/SECURITY.md for detailed security policy

Before Installing Packages

# Check if a package is safe
./scripts/check-package-security.sh <package-name>

License

This project is licensed under the GNU General Public License v3.0.

Documentation

For detailed information about this project, see:

Contributing

Contributions are welcome! Please ensure:

  1. All new dependencies are verified against compromised package lists

  2. Code follows the Coding Standards

  3. Types use type (not interface) and are placed in types/ directory

  4. Centralized logger is used at all critical paths

  5. OpenAPI YAML files are updated alongside type changes

  6. Tests are included for new features

  7. Git hooks pass (branch naming, format, lint, typecheck, build)

Available Tools

19 tools
bitbucket_add_pr_commentC

Add a general comment to a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
textYesComment text

TDQS

C2.9/5.0
Behavior2/5

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

The description indicates a mutation via 'Add', but discloses no behavioral traits such as whether the comment is appended, if notifications are sent, or if there are any side effects. With no annotations provided, the description fails to compensate.

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?

The description is a single, concise sentence that conveys the basic purpose without fluff. However, it could be slightly expanded without losing conciseness to improve clarity.

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

Completeness2/5

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

Given the absence of annotations, output schema, and the presence of a similar sibling tool, the description lacks contextual completeness. It does not explain the nature of a 'general comment' or provide any detail about the expected outcome or error states.

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?

All four parameters are fully described in the input schema (100% coverage), so the description adds no extra meaning. It does not clarify the relationship between parameters or the concept of a 'general comment' beyond the schema.

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 clearly states the action 'Add' and the resource 'general comment' on a 'pull request'. However, it does not differentiate from the sibling tool 'bitbucket_add_pr_inline_comment', leaving ambiguity about what 'general' means compared to inline comments.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus the inline comment tool, nor are there prerequisites or context conditions mentioned. This leaves the agent without direction for proper invocation.

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

bitbucket_add_pr_inline_commentB

Add inline code comment on a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
textYesComment text
pathYesFile path
lineYesLine number
lineTypeYesLine type
fileTypeNoFile type

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states the action but does not mention idempotency, permissions, side effects, or response behavior.

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?

The description is a single, efficient sentence that front-loads the purpose with no redundant words.

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

Completeness2/5

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is insufficient. It omits return values, formatting expectations, and behavioral constraints.

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 coverage is 100%, so the input schema fully documents parameters. The description adds no additional meaning beyond 'inline code comment' context, resulting in a baseline score.

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 clearly states the action ('Add') and specific resource ('inline code comment on a pull request'), distinguishing it from sibling 'bitbucket_add_pr_comment' which likely adds a general comment.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool vs alternatives, such as bitbucket_add_pr_comment or bitbucket_reply_to_comment. No usage context is given.

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

bitbucket_approve_prA

Approve a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries full burden. It clearly states the action ('Approve'), indicating a state-changing but non-destructive operation. However, it does not disclose potential side effects, permissions, or return behavior.

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?

Single concise sentence with no extraneous text. Efficiently communicates the core purpose.

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

Completeness3/5

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

No output schema is provided; description omits what the tool returns (e.g., success status). However, for a simple approval action, the description combined with complete parameter schema is moderately adequate.

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?

Input schema covers 100% of parameters with descriptions. The description adds no further detail beyond the schema, so baseline score applies.

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 uses a specific verb ('Approve') and resource ('pull request'), clearly distinguishing it from sibling tools like bitbucket_add_pr_comment, bitbucket_resolve_comment, etc.

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?

The description implies the tool is used to approve a pull request, but does not provide guidance on when to use it versus alternatives (e.g., bitbucket_add_pr_comment for commenting) or when not to use it.

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

bitbucket_get_branchesC

List repository branches

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
limitNoMax results
startNoPagination start

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are present, so the description must provide behavioral context. It only says 'List repository branches' without mentioning pagination, ordering, or what happens on empty results. This is minimal.

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?

The description is a single sentence with no waste. It is front-loaded and appropriately concise for a simple listing tool.

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

Completeness2/5

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

No output schema and no annotations; the description does not explain the return format, pagination behavior, or any edge cases. For a tool with 4 parameters, it is incomplete.

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 the schema already defines each parameter. The description adds no additional meaning beyond what the schema provides.

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?

Description clearly states the action (list) and resource (repository branches). It is distinct from sibling tools that list repositories or get repository details. However, it does not specify that it requires project and repo parameters, which is inferred from the schema but not described.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like bitbucket_list_repositories or bitbucket_get_repository. No exclusions or context are provided.

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

bitbucket_get_commitsC

Get commit history for a repository

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
limitNoMax results
startNoPagination start

TDQS

C2.8/5.0
Behavior2/5

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

No annotations exist, and the description omits behavioral details such as pagination behavior (implied by limit/start parameters), ordering, or what constitutes a commit. The description does not contradict annotations but fails to disclose important traits.

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

Conciseness3/5

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

The description is concise at one sentence, but it lacks critical usage and behavioral information, making it slightly under-specified for effective tool selection.

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

Completeness2/5

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

Given the absence of an output schema and the presence of pagination parameters, the description should mention pagination and result format. The current text is too minimal for an agent to confidently use this tool correctly.

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?

The input schema already provides complete descriptions for all four parameters, so the description adds no additional meaning. Baseline 3 is appropriate given 100% schema coverage.

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 clearly states the tool fetches commit history for a repository, which is a specific verb and resource. It is distinct from sibling tools like bitbucket_search_commits, which implies filtered retrieval.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like bitbucket_search_commits, nor are there any prerequisites or exclusions mentioned.

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

bitbucket_get_file_contentC

Get file content at a specific ref

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
pathYesFile path
refNoBranch, tag, or commit ref

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided, and the description does not disclose what the tool returns (e.g., raw content, base64, size limits) or any behavioral traits like authorization needs or rate limits.

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?

Extremely concise at 6 words, front-loaded with the action. Could benefit from slightly more detail without becoming verbose, but it's not wasteful.

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

Completeness2/5

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

Lacks output schema and annotations. The description fails to specify what the output is (e.g., file content as text), does not mention that the ref is optional (though the description implies it is required), and provides no usage context.

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 coverage is 100% with descriptions for all 4 parameters. The description adds no extra meaning beyond stating 'at a specific ref', which aligns with the ref parameter documentation.

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 clearly states the verb 'Get' and the resource 'file content' with a qualifier 'at a specific ref'. It distinguishes from sibling tools like bitbucket_get_repository (which gets repo metadata) and bitbucket_get_branches (which lists branches), but does not explicitly differentiate them.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like bitbucket_search_code. There is no mention of prerequisites, context, or exclusions.

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

bitbucket_get_pr_activitiesB

Get pull request comments and activities

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
limitNoMax results
startNoPagination start

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only says 'Get', implying read-only, but does not clarify what activities are included (e.g., approvals, status changes) or mention pagination behavior, permission requirements, or any side effects.

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?

The description is a single, succinct sentence that is immediately understandable with no unnecessary words. It is front-loaded with the core purpose.

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

Completeness2/5

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

For a tool with 5 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain the structure of the response, pagination details (even though 'start' and 'limit' are parameters), or what constitutes an 'activity.'

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 each parameter already has a meaningful description. The tool description adds no extra semantic value beyond the schema, meeting the baseline for high coverage.

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 explicitly states the action ('Get') and the resource ('pull request comments and activities'), which clearly differentiates from siblings like bitbucket_get_pull_request that retrieve the PR itself, or comment-specific tools.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives (e.g., when to fetch comments vs. diff vs. commits). The description does not mention prerequisites, exclusions, or context for appropriate use.

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

bitbucket_get_pr_commitsB

Get commits in a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
limitNoMax results
startNoPagination start

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, and the description is too brief to disclose behavioral traits such as pagination (handled by 'limit' and 'start' params but not explained), ordering, or what happens when the PR has no commits.

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?

A single, front-loaded sentence with no unnecessary words. It efficiently conveys the core action, though extremely minimal.

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

Completeness2/5

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

With 5 parameters and no output schema, the description should provide more context about return format, pagination details, or example usage. The current description is insufficient for a tool with moderate complexity.

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 coverage is 100%, meaning each parameter has a description in the schema. The tool description adds no additional parameter information, so baseline 3 is appropriate.

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?

Description clearly states the action: 'Get commits in a pull request'. It uses a specific verb and resource, distinguishing it from siblings like 'bitbucket_get_pr_diff' or 'bitbucket_get_pull_request'.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives like 'bitbucket_get_pr_activities' or 'bitbucket_get_pr_diff'. The description lacks context for usage scenarios.

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

bitbucket_get_pr_diffB

Get pull request diff/changes

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID

TDQS

B3/5.0
Behavior2/5

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

With no annotations, the description fails to disclose behavioral traits such as read-only nature, response format, or potential side effects. 'Get' implies a read operation, but details are lacking.

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

Conciseness3/5

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

The description is extremely concise (4 words) and front-loaded, but does not provide sufficient context. It earns its place but is too sparse for a meaningful description.

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

Completeness2/5

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

Given no output schema and no annotations, the description is incomplete. It does not mention what the diff includes, format, or limitations, leaving agents without essential context for safe invocation.

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 coverage is 100% with descriptive parameter names and descriptions. The tool description adds no extra semantic value beyond what the schema provides, so baseline 3 is appropriate.

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 clearly states 'Get pull request diff/changes', identifying the verb and resource. It distinguishes from sibling tools like bitbucket_get_pull_request (which likely returns PR metadata) and bitbucket_get_pr_commits (returns commits).

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like bitbucket_get_pull_request or bitbucket_get_pr_commits. No context about prerequisites or when it might not be suitable.

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

bitbucket_get_pull_requestB

Get detailed pull request information

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavior. It only states 'Get detailed pull request information', omitting whether it includes comments, diffs, approvals, or other attributes. The lack of detail hinders the agent's understanding of what 'detailed' covers.

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?

The description is concise with a single sentence. It is front-loaded with the key action and resource. While it could add value with more details, it avoids unnecessary verbosity.

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

Completeness3/5

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

Given the simplicity of the tool (retrieve a PR by ID) and the lack of an output schema, the description is minimal but adequate. It does not describe return format or additional fields, but the expected output is implicit for a typical PR retrieval. Slightly below complete for a new agent.

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?

The input schema has 100% coverage with descriptive parameter names (project, repo, prId) and descriptions. The description adds no additional meaning beyond what the schema already provides, resulting in a baseline score of 3.

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 'Get detailed pull request information' clearly specifies the verb 'Get' and resource 'pull request information'. It distinguishes from siblings like bitbucket_list_pull_requests (listing vs single) and bitbucket_approve_pr (action vs read). However, it could be more precise about what 'detailed' entails.

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: use this to retrieve details of a specific pull request, as opposed to listing PRs or performing actions. No explicit when/when-not guidance or alternatives are provided, leaving the agent to infer from sibling context.

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

bitbucket_get_repositoryB

Get repository details

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug

TDQS

B3.1/5.0
Behavior2/5

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

Without annotations, the description should disclose behavioral traits like authentication or output nature. It only repeats the tool's purpose, adding no value beyond the name.

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?

A single sentence is concise and front-loaded. However, it is minimal and could be slightly more informative without sacrificing conciseness.

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?

Given the tool's simplicity (2 parameters, no output schema), the description is adequate for basic understanding. It covers the core function, though return details are unspecified.

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 coverage is 100%, so the schema already documents both parameters' meanings. The description adds no additional parameter information, meeting the baseline.

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 clearly states the tool retrieves repository details, but it does not differentiate from siblings like get_branches or get_commits. The verb+resource is specific and not a tautology.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description implies usage for retrieving repository details but lacks context or exclusions.

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

bitbucket_list_projectsB

List accessible Bitbucket projects

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results
startNoPagination start

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description must disclose behavior but only says 'list'. It fails to mention that the tool is read-only, any required permissions, or pagination specifics beyond parameter names. The schema hints at pagination but the description adds no behavioral context.

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?

The description is a single, concise sentence with no fluff. It effectively communicates the core purpose in minimal space, which is ideal for quick comprehension.

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

Completeness2/5

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

Given the simplicity of the tool (2 optional params, no output schema, no annotations), the description is extremely minimal. It does not explain return values, pagination behavior, or any limitations, leaving the agent with insufficient context for confident usage.

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?

The input schema has 100% coverage for both parameters (limit, start), so the baseline is 3. The description does not add any additional meaning or constraints beyond the schema, making it adequate but not helpful.

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 clearly states the action ('List') and the resource ('accessible Bitbucket projects'), making the tool's purpose immediately understandable. It sufficiently distinguishes from sibling tools that deal with pull requests, branches, etc.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like bitbucket_list_repositories or bitbucket_search_code. The description simply states what the tool does without context or exclusions.

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

bitbucket_list_pull_requestsB

List pull requests for a repository

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
stateNoPR state filter: OPEN, MERGED, DECLINED
limitNoMax results
startNoPagination start

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided. The description does not disclose behavioral traits such as pagination (despite start and limit parameters), rate limits, or whether the result is a list with summary details. The agent must infer behavior from parameter names.

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?

The description is a single sentence with no wasted words. It front-loads the core purpose. Perfectly concise.

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

Completeness2/5

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

The tool has 5 parameters including pagination and state filter, but the description is extremely sparse. It does not mention filtering, pagination, or output format. Lacks necessary context given the tool's complexity.

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?

The input schema has 100% description coverage for all 5 parameters. The tool description adds no additional meaning beyond what the schema already provides. With high schema coverage, baseline 3 is appropriate.

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 clearly states the action (list) and resource (pull requests for a repository). It differentiates from sibling tools like bitbucket_get_pull_request which retrieves a single PR. However, it omits details like filtering capabilities that are present in the schema.

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?

The description implies the tool should be used to retrieve multiple pull requests for a repository, but it does not provide any guidance on when to prefer it over siblings (e.g., bitbucket_get_pull_request for a specific PR) or when not to use it.

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

bitbucket_list_repositoriesC

List repositories in a project

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
limitNoMax results
startNoPagination start

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations present, the description should disclose all behavioral traits. It does not mention that the tool returns paginated results, any ordering, or rate limits. The presence of 'start' and 'limit' parameters hints at pagination, but the description does not confirm this behavior.

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

Conciseness3/5

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

The description is extremely short (one sentence), which is concise but lacks important details. It is not verbose, but could be more informative without adding excessive length.

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

Completeness2/5

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

No output schema exists, so the description should explain the return value (e.g., an array of repository objects). It does not mention pagination behavior, default limits, or any filtering beyond the required project key. For a list tool, this is insufficient context.

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?

The input schema has 100% description coverage, so the baseline is 3. The description adds no extra meaning beyond the schema, but it also does not contradict it. The schema already provides meaningful descriptions for each parameter.

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 clearly states the verb 'List' and the resource 'repositories in a project', making the tool's purpose immediately understandable. However, it does not distinguish itself from siblings like 'bitbucket_get_repository' (which is for a single repo) or search tools, missing an opportunity to clarify scope.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus searching for repositories (e.g., via 'bitbucket_search_code') or viewing details of a single repository. The description lacks context about typical use cases or prerequisites.

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

bitbucket_reply_to_commentC

Reply to a comment on a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
commentIdYesParent comment ID
textYesReply text

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided, so the description is the sole source of behavioral context. It only states 'Reply to a comment' without disclosing mutation effects, permissions, or whether the reply is nested. This is insufficient for an agent to understand side effects.

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?

The description is a single sentence with no wasted words. However, it could be expanded without becoming verbose given the lack of other guidance.

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

Completeness2/5

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

For a tool with 5 required parameters, no output schema, and no annotations, the description is too sparse. It fails to explain the expected outcome (e.g., the reply becomes a child comment) or any prerequisites like existing parent comment ID.

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?

The input schema has 100% description coverage for all parameters, so the baseline is 3. The tool description adds no new information about parameters beyond what the schema already provides.

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 uses the specific verb 'Reply' and resource 'comment on a pull request', clearly indicating the action. While siblings like bitbucket_add_pr_comment and bitbucket_update_comment exist, 'reply' suggests responding to an existing comment, which provides some differentiation.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like add_pr_comment (for new top-level comments) or resolve_comment. The description lacks any when-to-use or when-not-to-use information.

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

bitbucket_resolve_commentB

Resolve a comment thread on a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
commentIdYesComment ID to resolve
versionYesComment version for optimistic locking

TDQS

B3/5.0
Behavior2/5

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

The description only says 'resolve' without explaining side effects (e.g., thread closed, needs version for locking). No annotations are present, so the description should provide more behavioral context but fails to do so.

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

Conciseness3/5

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

The description is a single sentence, which is concise but lacks structure (e.g., parameter listing or usage hints). It states purpose but nothing more.

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

Completeness2/5

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

Given the 5 required parameters and no output schema, the description is too sparse. It does not explain optimistic locking, what 'resolve' entails, or how to handle errors.

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?

All 5 parameters have descriptions in the schema (100% coverage). The tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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 clearly states the action ('resolve') and the target ('comment thread on a pull request'). It distinguishes this tool from siblings like adding, replying, or updating comments.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., comment must be unresolved) or exclusions.

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

bitbucket_search_codeB

Search code across repositories in a project

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
queryYesSearch query
limitNoMax results
startNoPagination start

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, and the description does not disclose behavioral aspects like read-only nature, rate limits, or behavior on empty results. Minimal disclosure.

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?

Single sentence, front-loaded, no redundant information. Very concise, though could include a bit more context without harming conciseness.

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

Completeness2/5

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

Given the tool's simplicity (4 params, no output schema), the description is terse and omits details about return format, pagination, or search behavior. Incomplete for an AI agent.

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 coverage is 100% with descriptions for all parameters, so the description adds no additional meaning. Baseline of 3 is appropriate.

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 clearly states the tool searches code across repositories in a project, using a specific verb (search) and resource (code). It distinguishes from siblings like bitbucket_search_commits which searches commits.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as bitbucket_search_commits, or when not to use it. Lacks context for selection.

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

bitbucket_search_commitsB

Search commits by message

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
queryYesSearch query
limitNoMax results
startNoPagination start

TDQS

B3.1/5.0
Behavior2/5

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

Description provides no behavioral traits (e.g., pagination, ordering, performance) beyond the bare action. With no annotations, the description should disclose more, such as the fact that pagination parameters exist or that results are limited to commits matching a message string.

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?

The description is extremely concise at four words, front-loading the key purpose. While efficient, it sacrifices potentially useful detail that could improve clarity.

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

Completeness2/5

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

Given 5 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain the result format, pagination behavior, or query syntax, leaving the agent with incomplete information for effective use.

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 coverage is 100% with descriptions for each parameter, so the description does not need to add parameter details. However, it misses the opportunity to clarify how the 'query' parameter is interpreted (e.g., exact match, substring), which is not obvious from the parameter description alone.

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 'Search commits by message' clearly states the tool's action (search) and resource (commits) with a specific criterion (by message), distinguishing it from siblings like bitbucket_get_commits which likely retrieves all commits without message filtering.

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

Usage Guidelines2/5

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

No guidance on when to use this tool over alternatives such as bitbucket_search_code or bitbucket_get_commits. The description lacks context for appropriate usage scenarios.

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

bitbucket_update_commentB

Edit a comment on a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
repoYesRepository slug
prIdYesPull request ID
commentIdYesComment ID to edit
textYesUpdated comment text
versionYesComment version for optimistic locking

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, and the description fails to disclose key behaviors like optimistic locking (version parameter), required permissions, or side effects. The term 'Edit' alone is insufficient.

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?

Extremely concise (6 words) and front-loaded. However, missing critical behavioral info slightly reduces efficiency for agent usage.

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

Completeness2/5

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

No output schema, all 6 params required, and no mention of return value, concurrency, or prerequisite steps. Incomplete for a mutation tool.

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 coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's property descriptions, which are already clear.

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 'Edit a comment on a pull request' uses a specific verb (Edit) and resource (comment on pull request), distinguishing it from sibling tools like add, reply, or resolve.

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

Usage Guidelines2/5

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

No guidance on when to use this vs alternatives (e.g., add_comment, reply_to_comment), nor when not to use it (e.g., locked comments).

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 19 tool updatesv0.1.0
    • First observedbitbucket_add_pr_comment
    • First observedbitbucket_add_pr_inline_comment
    • First observedbitbucket_approve_pr
    • First observedbitbucket_get_branches
    • First observedbitbucket_get_commits
    • First observedbitbucket_get_file_content
    • First observedbitbucket_get_pr_activities
    • First observedbitbucket_get_pr_commits
    • First observedbitbucket_get_pr_diff
    • First observedbitbucket_get_pull_request
    • First observedbitbucket_get_repository
    • First observedbitbucket_list_projects
    • First observedbitbucket_list_pull_requests
    • First observedbitbucket_list_repositories
    • First observedbitbucket_reply_to_comment
    • First observedbitbucket_resolve_comment
    • First observedbitbucket_search_code
    • First observedbitbucket_search_commits
    • First observedbitbucket_update_comment
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 19 tools

Disambiguation5/5

Each tool has a clearly distinct purpose. The action-noun pattern (e.g., 'add_pr_comment' vs 'add_pr_inline_comment') ensures no ambiguity between similar operations.

Naming Consistency5/5

All tools follow the 'bitbucket_<verb>_<noun>' pattern using snake_case. The naming is perfectly uniform and predictable.

Tool Count5/5

With 19 tools, the set is well-scoped for a Bitbucket server. It covers projects, repositories, pull requests, and comments without being overwhelming.

Completeness3/5

The tool set heavily focuses on reading and commenting on pull requests and repositories, but lacks create/update/delete operations for repositories and projects, as well as merge/decline for pull requests. This leaves notable gaps for full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Bitbucket MCP Server

    bobmaertz
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.
    2,884 npm
    1
    MIT

  • bitbucket-mcp

    yunusemregul
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to programmatically manage Bitbucket Cloud resources, including pull requests, repositories, and branches, automating code review workflows.
    7 npm
    MIT

Appeared in Searches