Skip to main content
Glama
deenesjakoruzh
pdogra1299

Bitbucket MCP Server

by pdogra1299
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Bitbucket MCP Server

npm version License: MIT

An MCP (Model Context Protocol) server that provides tools for interacting with the Bitbucket API, supporting both Bitbucket Cloud and Bitbucket Server.

Features

Available Tools (29 total)

PR Core (pr_core)

  • get_pull_request - Full PR details including comments, file changes, and merge info

  • list_pull_requests - List PRs with filters (state, author, pagination)

  • create_pull_request - Create new pull requests

  • update_pull_request - Update PR details (title, description, reviewers, destination branch)

  • merge_pull_request - Merge pull requests with various strategies

  • decline_pull_request - Decline/reject a pull request

PR Comments (pr_comments)

  • add_comment - Add general, inline, threaded, or suggestion comments to a PR

  • delete_comment - Delete a comment from a pull request

Code Review (pr_review)

  • get_pull_request_diff - Structured line-by-line diff with ADDED/REMOVED/CONTEXT types

  • set_pr_approval - Approve (approved: true) or unapprove (approved: false) a PR

  • set_review_status - Request changes (request_changes: true) or remove the request (false)

PR Tasks — Bitbucket Server only (pr_tasks)

  • list_pr_tasks - List all tasks on a pull request

  • create_pr_task - Create a new task on a pull request

  • update_pr_task - Update the text of an existing task

  • set_pr_task_status - Mark a task done (done: true) or reopen it (done: false)

  • delete_pr_task - Delete a task from a pull request

  • convert_pr_item - Convert a comment to a task (direction: "to_task") or back ("to_comment")

Commits (commits)

  • list_pr_commits - List all commits in a pull request

  • list_branch_commits - List commits in a branch with date/author/message filters

  • get_commit_detail - Get the structured diff for a specific commit by SHA

Branches (branches)

  • list_branches - List branches with filtering and pagination

  • get_branch - Detailed branch info including associated PRs and stats

  • delete_branch - Delete a branch

Files (files)

  • list_directory_content - List files and directories in a repository path

  • get_file_content - Get file content with smart truncation for large files

  • search_files - Search for files by glob pattern (case-insensitive, like VS Code Ctrl+P)

  • get_file_blame - Per-line blame: who last modified each line, commit hash, and author timestamp (Bitbucket Server only)

Search — Bitbucket Server only (search)

  • search_code - Search for code across repositories

  • search_repositories - Search for repositories by name or description

Discovery (discovery)

  • list_projects - List all accessible Bitbucket projects/workspaces

  • list_repositories - List repositories in a project or across all accessible projects

Token Optimization

v2.0.0 introduces significant token savings on every LLM request:

Configuration

Tools exposed

Est. tokens

Bitbucket Server (all groups)

29

~5,100

Bitbucket Cloud (auto-filtered)

21

~3,900

Custom group preset (e.g. pr_core,pr_review,files)

12

~2,100

Bitbucket Cloud automatically hides the 10 server-only tools with no configuration needed.

BITBUCKET_TOOL_GROUPS lets you expose only the groups relevant to your workflow — see Tool Group Filtering below.

Related MCP server: bitbucket-mcp-server

Installation

Using npx (Recommended)

The easiest way to use this MCP server is directly with npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

For Bitbucket Server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

From Source

  1. Clone or download this repository

  2. Install dependencies:

    npm install

  3. Build the TypeScript code:

    npm run build

Authentication Setup

This server uses Bitbucket App Passwords for authentication.

Creating an App Password

  1. Log in to your Bitbucket account

  2. Navigate to: https://bitbucket.org/account/settings/app-passwords/

  3. Click "Create app password"

  4. Give it a descriptive label (e.g., "MCP Server")

  5. Select the following permissions:

    • Account: Read

    • Repositories: Read, Write

    • Pull requests: Read, Write

  6. Click "Create"

  7. Important: Copy the generated password immediately (you won't be able to see it again!)

Running the Setup Script

node scripts/setup-auth.js

This will guide you through the authentication setup process.

Configuration

Add the server to your MCP settings file (usually located at ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Replace:

  • /absolute/path/to/bitbucket-mcp-server with the actual path to this directory

  • your-username with your Bitbucket username (not email)

  • your-app-password with the app password you created

For Bitbucket Server, use:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Important for Bitbucket Server users:

  • Use your full email address as the username (e.g., "john.doe@company.com")

  • This is required for approval/review actions to work correctly

Tool Group Filtering

Reduce the number of tools sent to the LLM on every request by setting BITBUCKET_TOOL_GROUPS to a comma-separated list of group names. Only tools in the listed groups will be exposed.

Available groups

Group

Tools

Platform

pr_core

get_pull_request, list_pull_requests, create_pull_request, update_pull_request, merge_pull_request, decline_pull_request

Both

pr_comments

add_comment, delete_comment

Both

pr_review

get_pull_request_diff, set_pr_approval, set_review_status

Both

pr_tasks

list_pr_tasks, create_pr_task, update_pr_task, set_pr_task_status, delete_pr_task, convert_pr_item

Server only

commits

list_pr_commits, list_branch_commits, get_commit_detail

Both

branches

list_branches, get_branch, delete_branch

Both

files

list_directory_content, get_file_content, search_files, get_file_blame (Server only)

Both

search

search_code, search_repositories

Server only

discovery

list_projects, list_repositories

Both

Example presets

PR review workflow (~2,100 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_review,files"
}

Full PR management (~3,500 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_comments,pr_review,pr_tasks"
}

Code exploration only (~1,400 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "files,search,discovery"
}

When BITBUCKET_TOOL_GROUPS is not set, all applicable tools are exposed (default behaviour). Bitbucket Cloud users always have server-only tools automatically hidden regardless of this setting.

Usage

Once configured, you can use the available tools:

Get Pull Request

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Returns detailed information about the pull request including:

  • Title and description

  • Author and reviewers

  • Source and destination branches

  • Approval status

  • Links to web UI and diff

  • Merge commit details (when PR is merged):

    • merge_commit_hash: The hash of the merge commit

    • merged_by: Who performed the merge

    • merged_at: When the merge occurred

    • merge_commit_message: The merge commit message

  • Active comments with nested replies (unresolved comments that need attention):

    • active_comments: Array of active comments (up to 20 most recent top-level comments)

      • Comment text and author

      • Creation date

      • Whether it's an inline comment (with file path and line number)

      • Nested replies (for Bitbucket Server):

        • replies: Array of reply comments with same structure

        • Replies can be nested multiple levels deep

      • Parent reference (for Bitbucket Cloud):

        • parent_id: ID of the parent comment for replies

    • active_comment_count: Total count of unresolved comments (including nested replies)

    • total_comment_count: Total count of all comments (including resolved and replies)

  • File changes:

    • file_changes: Array of all files modified in the PR

      • File path

      • Status (added, modified, removed, or renamed)

      • Old path (for renamed files)

    • file_changes_summary: Summary statistics

      • Total files changed

  • And more...

Search Code

Search for code across Bitbucket repositories (currently only supported for Bitbucket Server):

// Search in a specific repository
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// Search across all repositories in a workspace
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // Optional: filter by file pattern
    "limit": 100
  }
}

// Search with file pattern filtering
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // Only search in .tsx files
    "start": 0,
    "limit": 25
  }
}

Returns search results with:

  • File path and name

  • Repository and project information

  • Matched lines with:

    • Line number

    • Full line content

    • Highlighted segments showing exact matches

  • Pagination information

Example response:

{
  "message": "Code search completed successfully",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: Implement error handling",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": Implement error handling", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

Note: This tool currently only works with Bitbucket Server. Bitbucket Cloud support is planned for a future release.

List Pull Requests

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "state": "OPEN",  // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
    "author": "username",  // Optional: filter by author (see note below)
    "limit": 25,  // Optional: max results per page (default: 25)
    "start": 0  // Optional: pagination start index (default: 0)
  }
}

Returns a paginated list of pull requests with:

  • Array of pull requests with same details as get_pull_request

  • Total count of matching PRs

  • Pagination info (has_more, next_start)

Note on Author Filter:

  • For Bitbucket Cloud: Use the username (e.g., "johndoe")

  • For Bitbucket Server: Use the full email address (e.g., "john.doe@company.com")

Create Pull Request

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "Add new feature",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "This PR adds a new feature...",  // Optional
    "reviewers": ["john.doe", "jane.smith"],  // Optional
    "close_source_branch": true  // Optional (default: false)
  }
}

Update Pull Request

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "Updated title",  // Optional
    "description": "Updated description",  // Optional
    "destination_branch": "develop",  // Optional
    "reviewers": ["new.reviewer"]  // Optional - see note below
  }
}

Important Note on Reviewers:

  • When updating a PR without specifying the reviewers parameter, existing reviewers and their approval status are preserved

  • When providing the reviewers parameter:

    • The reviewer list is replaced with the new list

    • For reviewers that already exist on the PR, their approval status is preserved

    • New reviewers are added without approval status

  • This prevents accidentally removing reviewers when you only want to update the PR description or title

Add Comment

Add a comment to a pull request, either as a general comment or inline on specific code:

// General comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Great work on this PR!"
  }
}

// Inline comment on specific line
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this into a separate function",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// Reply to existing comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "I agree with this suggestion",
    "parent_comment_id": 456
  }
}

// Add comment with code suggestion (single line)
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive.",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// Add comment with multi-line code suggestion
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This function could be simplified using array methods.",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

The suggestion feature formats comments using GitHub-style markdown suggestion blocks that Bitbucket can render. When adding a suggestion:

  • suggestion is required and contains the replacement code

  • file_path and line_number are required when using suggestions

  • suggestion_end_line is optional and used for multi-line suggestions (defaults to line_number)

  • The comment will be formatted with a ````suggestion` markdown block that may be applicable in the Bitbucket UI

Using Code Snippets Instead of Line Numbers

The add_comment tool now supports finding line numbers automatically using code snippets. This is especially useful when AI tools analyze diffs and may struggle with exact line numbers:

// Add comment using code snippet
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// Handle multiple matches with strategy
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // Auto-select highest confidence match
  }
}

Code Snippet Parameters:

  • code_snippet: The exact code line to find (alternative to line_number)

  • search_context: Optional context to disambiguate multiple matches

    • before: Array of lines that should appear before the target

    • after: Array of lines that should appear after the target

  • match_strategy: How to handle multiple matches

    • "strict" (default): Fail with error showing all matches

    • "best": Auto-select the highest confidence match

Error Response for Multiple Matches (strict mode):

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "Code snippet 'return result;' found in 3 locations",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line_type": "ADDED"
      },
      // ... more matches
    ],
    "suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
  }
}

This feature is particularly useful for:

  • AI-powered code review tools that analyze diffs

  • Scripts that automatically add comments based on code patterns

  • Avoiding line number confusion in large diffs

Note on comment replies:

  • Use parent_comment_id to reply to any comment (general or inline)

  • In get_pull_request responses:

    • Bitbucket Server shows replies nested in a replies array

    • Bitbucket Cloud shows a parent_id field for reply comments

  • You can reply to replies, creating nested conversations

Note on inline comments:

  • file_path: The path to the file as shown in the diff

  • line_number: The line number as shown in the diff

  • line_type:

    • ADDED - For newly added lines (green in diff)

    • REMOVED - For deleted lines (red in diff)

    • CONTEXT - For unchanged context lines

Add Comment - Complete Usage Guide

The add_comment tool supports multiple scenarios. Here's when and how to use each approach:

1. General PR Comments (No file/line)

  • Use when: Making overall feedback about the PR

  • Required params: comment_text only

  • Example: "LGTM!", "Please update the documentation"

2. Reply to Existing Comments

  • Use when: Continuing a conversation thread

  • Required params: comment_text, parent_comment_id

  • Works for both general and inline comment replies

3. Inline Comments with Line Number

  • Use when: You know the exact line number from the diff

  • Required params: comment_text, file_path, line_number

  • Optional: line_type (defaults to CONTEXT)

4. Inline Comments with Code Snippet

  • Use when: You have the code but not the line number (common for AI tools)

  • Required params: comment_text, file_path, code_snippet

  • The tool will automatically find the line number

  • Add search_context if the code appears multiple times

  • Use match_strategy: "best" to auto-select when multiple matches exist

5. Code Suggestions

  • Use when: Proposing specific code changes

  • Required params: comment_text, file_path, line_number, suggestion

  • For multi-line: also add suggestion_end_line

  • Creates applicable suggestion blocks in Bitbucket UI

Decision Flow for AI/Automated Tools:

1. Do you want to suggest code changes?
   → Use suggestion with line_number
   
2. Do you have the exact line number?
   → Use line_number directly
   
3. Do you have the code snippet but not line number?
   → Use code_snippet (add search_context if needed)
   
4. Is it a general comment about the PR?
   → Use comment_text only
   
5. Are you replying to another comment?
   → Add parent_comment_id

Common Pitfalls to Avoid:

  • Don't use both line_number and code_snippet - pick one

  • Suggestions always need file_path and line_number

  • Code snippets must match exactly (including whitespace)

  • REMOVED lines reference the source file, ADDED/CONTEXT reference the destination

Merge Pull Request

{
  "tool": "merge_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "merge_strategy": "squash",  // Optional: merge-commit, squash, fast-forward
    "close_source_branch": true,  // Optional
    "commit_message": "Custom merge message"  // Optional
  }
}

List Branches

{
  "tool": "list_branches",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "filter": "feature",  // Optional: filter by name pattern
    "limit": 25,  // Optional (default: 25)
    "start": 0  // Optional: for pagination (default: 0)
  }
}

Returns a paginated list of branches with:

  • Branch name and ID

  • Latest commit hash

  • Default branch indicator

  • Pagination info

Delete Branch

{
  "tool": "delete_branch",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "feature/old-feature",
    "force": false  // Optional (default: false)
  }
}

Note: Branch deletion requires appropriate permissions. The branch will be permanently deleted.

Get Branch

{
  "tool": "get_branch",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "feature/new-feature",
    "include_merged_prs": false  // Optional (default: false)
  }
}

Returns comprehensive branch information including:

  • Branch details:

    • Name and ID

    • Latest commit (hash, message, author, date)

    • Default branch indicator

  • Open pull requests from this branch:

    • PR title and ID

    • Destination branch

    • Author and reviewers

    • Approval status (approved by, changes requested by, pending)

    • PR URL

  • Merged pull requests (if include_merged_prs is true):

    • PR title and ID

    • Merge date and who merged it

  • Statistics:

    • Total open PRs count

    • Total merged PRs count

    • Days since last commit

This tool is particularly useful for:

  • Checking if a branch has open PRs before deletion

  • Getting an overview of branch activity

  • Understanding PR review status

  • Identifying stale branches

List Branch Commits

Get all commits in a specific branch with advanced filtering options:

// Basic usage - get recent commits
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "feature/new-feature",
    "limit": 50  // Optional (default: 25)
  }
}

// Filter by date range
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "main",
    "since": "2025-01-01T00:00:00Z",  // ISO date string
    "until": "2025-01-15T23:59:59Z"   // ISO date string
  }
}

// Filter by author
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "develop",
    "author": "john.doe@company.com",  // Email or username
    "limit": 100
  }
}

// Exclude merge commits
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "release/v2.0",
    "include_merge_commits": false
  }
}

// Search in commit messages
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "main",
    "search": "bugfix",  // Search in commit messages
    "limit": 50
  }
}

// Combine multiple filters
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "develop",
    "author": "jane.smith@company.com",
    "since": "2025-01-01T00:00:00Z",
    "include_merge_commits": false,
    "search": "feature",
    "limit": 100,
    "start": 0  // For pagination
  }
}

// Include CI/CD build status (Bitbucket Server only)
{
  "tool": "list_branch_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "branch_name": "main",
    "include_build_status": true,  // Fetch build status for each commit
    "limit": 50
  }
}

Filter Parameters:

  • since: ISO date string - only show commits after this date

  • until: ISO date string - only show commits before this date

  • author: Filter by author email/username

  • include_merge_commits: Boolean to include/exclude merge commits (default: true)

  • search: Search for text in commit messages

  • include_build_status: Boolean to include CI/CD build status (default: false, Bitbucket Server only)

Returns detailed commit information:

{
  "branch_name": "feature/new-feature",
  "branch_head": "abc123def456",  // Latest commit hash
  "commits": [
    {
      "hash": "abc123def456",
      "abbreviated_hash": "abc123d",
      "message": "Add new feature implementation",
      "author": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "date": "2025-01-03T10:30:00Z",
      "parents": ["parent1hash", "parent2hash"],
      "is_merge_commit": false,
      "build_status": {  // Only present when include_build_status is true
        "successful": 5,
        "failed": 0,
        "in_progress": 1,
        "unknown": 0
      }
    }
    // ... more commits
  ],
  "total_count": 150,
  "start": 0,
  "limit": 25,
  "has_more": true,
  "next_start": 25,
  "filters_applied": {
    "author": "john.doe@example.com",
    "since": "2025-01-01",
    "include_merge_commits": false,
    "include_build_status": true
  }
}

This tool is particularly useful for:

  • Reviewing commit history before releases

  • Finding commits by specific authors

  • Tracking changes within date ranges

  • Searching for specific features or fixes

  • Analyzing branch activity patterns

  • Monitoring CI/CD build status for commits (Bitbucket Server only)

List PR Commits

Get all commits that are part of a pull request:

// Basic usage
{
  "tool": "list_pr_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "limit": 50,  // Optional (default: 25)
    "start": 0    // Optional: for pagination
  }
}

// Include CI/CD build status (Bitbucket Server only)
{
  "tool": "list_pr_commits",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "include_build_status": true,  // Fetch build status for each commit
    "limit": 50
  }
}

Returns commit information for the PR:

{
  "pull_request_id": 123,
  "pull_request_title": "Add awesome feature",
  "commits": [
    {
      "hash": "def456ghi789",
      "abbreviated_hash": "def456g",
      "message": "Initial implementation",
      "author": {
        "name": "Jane Smith",
        "email": "jane.smith@example.com"
      },
      "date": "2025-01-02T14:20:00Z",
      "parents": ["parent1hash"],
      "is_merge_commit": false,
      "build_status": {  // Only present when include_build_status is true
        "successful": 3,
        "failed": 0,
        "in_progress": 0,
        "unknown": 0
      }
    }
    // ... more commits
  ],
  "total_count": 5,
  "start": 0,
  "limit": 25,
  "has_more": false
}

This tool is particularly useful for:

  • Reviewing all changes in a PR before merging

  • Understanding the development history of a PR

  • Checking commit messages for quality

  • Verifying authorship of changes

  • Analyzing PR complexity by commit count

  • Monitoring CI/CD build status for all PR commits (Bitbucket Server only)

Get Commit Detail

Get the diff for a specific commit by SHA with structured line-by-line information. Returns files with hunks containing individual lines, each with line numbers and ADDED/REMOVED/CONTEXT type information.

// Basic usage - get full commit diff
{
  "tool": "get_commit_detail",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "commit_id": "abc123def456",
    "context_lines": 5  // Optional (default: 3)
  }
}

// Get diff for a specific file only
{
  "tool": "get_commit_detail",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "commit_id": "abc123def456",
    "file_path": "src/index.ts"
  }
}

// Exclude generated/lock files
{
  "tool": "get_commit_detail",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "commit_id": "abc123def456",
    "exclude_patterns": ["*.lock", "*.svg", "node_modules/**"]
  }
}

// Include only specific file types
{
  "tool": "get_commit_detail",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "commit_id": "abc123def456",
    "include_patterns": ["*.ts", "src/**/*.js"]
  }
}

Structured Response Format (Bitbucket Server):

{
  "commit_id": "abc123def456",
  "files": [
    {
      "file_path": "src/index.ts",
      "old_path": null,
      "status": "modified",
      "hunks": [
        {
          "context": "export function foo() {",
          "source_start": 10,
          "source_span": 5,
          "destination_start": 10,
          "destination_span": 6,
          "lines": [
            {
              "source_line": 10,
              "destination_line": 10,
              "type": "CONTEXT",
              "content": "  const x = 1;"
            },
            {
              "source_line": 11,
              "destination_line": 11,
              "type": "REMOVED",
              "content": "  return x;"
            },
            {
              "source_line": 11,
              "destination_line": 11,
              "type": "ADDED",
              "content": "  return x + 1;"
            }
          ]
        }
      ]
    }
  ],
  "summary": {
    "total_files": 3,
    "files_included": 1,
    "files_excluded": 2
  },
  "filter_metadata": {
    "filters_applied": {
      "file_path": "src/index.ts"
    }
  }
}

This tool is particularly useful for:

  • Reviewing exactly what changed in a specific commit

  • Auditing a commit before or after it lands on a branch

  • Getting structured diff data for automated analysis

Get Pull Request Diff

Get the diff/changes for a pull request with structured line-by-line information. Returns files with hunks containing individual lines, each with line numbers and type information for easy inline commenting.

// Get full diff (default behavior)
{
  "tool": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "context_lines": 5  // Optional (default: 3)
  }
}

// Exclude specific file types
{
  "tool": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "exclude_patterns": ["*.lock", "*.svg", "node_modules/**", "*.min.js"]
  }
}

// Include only specific file types
{
  "tool": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "include_patterns": ["*.res", "*.resi", "src/**/*.js"]
  }
}

// Get diff for a specific file only
{
  "tool": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "file_path": "src/components/Button.res"
  }
}

// Combine filters
{
  "tool": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "include_patterns": ["src/**/*"],
    "exclude_patterns": ["*.test.js", "*.spec.js"]
  }
}

Filtering Options:

  • include_patterns: Array of glob patterns to include (whitelist)

  • exclude_patterns: Array of glob patterns to exclude (blacklist)

  • file_path: Get diff for a specific file only

  • Patterns support standard glob syntax (e.g., *.js, src/**/*.res, !test/**)

Structured Response Format (Bitbucket Server):

The response includes structured line-by-line information with line numbers, making it easy for AI tools to add inline comments:

{
  "message": "Pull request diff retrieved successfully",
  "pull_request_id": 123,
  "from_hash": "abc123...",
  "to_hash": "def456...",
  "files": [
    {
      "file_path": "src/components/Button.res",
      "old_path": null,
      "status": "modified",
      "hunks": [
        {
          "context": "let make = () => {",
          "source_start": 27,
          "source_span": 6,
          "destination_start": 27,
          "destination_span": 7,
          "lines": [
            {
              "source_line": 27,
              "destination_line": 27,
              "type": "CONTEXT",
              "content": "  let onClick = () => {"
            },
            {
              "source_line": 28,
              "destination_line": 28,
              "type": "CONTEXT",
              "content": "    setLoading(true)"
            },
            {
              "source_line": 29,
              "destination_line": 29,
              "type": "REMOVED",
              "content": "    oldFunction()"
            },
            {
              "source_line": 29,
              "destination_line": 29,
              "type": "ADDED",
              "content": "    newFunction()"
            },
            {
              "source_line": 30,
              "destination_line": 30,
              "type": "CONTEXT",
              "content": "  }"
            }
          ]
        }
      ]
    }
  ],
  "summary": {
    "total_files": 15,
    "files_included": 1,
    "files_excluded": 14
  },
  "filter_metadata": {
    "filters_applied": {
      "file_path": "src/components/Button.res"
    },
    "excluded_file_list": ["package-lock.json", "logo.svg"]
  }
}

Line Types and Usage with add_comment:

Line Type

Description

Use with add_comment

ADDED

New line (green in diff)

Use destination_line as line_number, line_type: "ADDED"

REMOVED

Deleted line (red in diff)

Use source_line as line_number, line_type: "REMOVED"

CONTEXT

Unchanged context line

Use destination_line as line_number, line_type: "CONTEXT"

Example: Adding an inline comment on an ADDED line:

// From the diff response, we see line 29 was added with content "    newFunction()"
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "file_path": "src/components/Button.res",
    "line_number": 29,  // Use destination_line for ADDED
    "line_type": "ADDED",
    "comment_text": "Consider adding error handling here"
  }
}

Note: Bitbucket Cloud currently returns raw diff format. The structured format is available for Bitbucket Server only.

Approve Pull Request

{
  "tool": "approve_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Request Changes

{
  "tool": "request_changes",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment": "Please address the following issues..."  // Optional
  }
}

List Directory Content

{
  "tool": "list_directory_content",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "path": "src/components",  // Optional (defaults to root)
    "branch": "main"  // Optional (defaults to default branch)
  }
}

Returns directory listing with:

  • Path and branch information

  • Array of contents with:

    • Name

    • Type (file or directory)

    • Size (for files)

    • Full path

  • Total items count

Search Files

Search for files by name or path pattern in a repository. Uses glob patterns with case-insensitive matching (like VS Code's Ctrl+P file search).

// Search for all TypeScript files
{
  "tool": "search_files",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pattern": "*.ts"
  }
}

// Search for files containing "Controller" in the name
{
  "tool": "search_files",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pattern": "**/Controller*"
  }
}

// Search within a specific directory
{
  "tool": "search_files",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pattern": "*.res",
    "path": "src/components"
  }
}

// Search on a specific branch with result limit
{
  "tool": "search_files",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pattern": "**/*Config*",
    "branch": "develop",
    "limit": 50
  }
}

// Case-insensitive search (matches SomeComponent.res, Somefile.res, etc.)
{
  "tool": "search_files",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pattern": "**/someFile*"
  }
}

Parameters:

  • workspace: Project key (required)

  • repository: Repository slug (required)

  • pattern: Glob pattern to filter files (optional, returns all files if not specified)

    • Supports standard glob syntax: *.ts, **/*.java, **/Controller*

    • Case-insensitive matching

  • path: Subdirectory to search within (optional, defaults to root)

  • branch: Branch name (optional, defaults to default branch)

  • limit: Maximum number of matching files to return (optional, default: 100)

Response:

{
  "workspace": "PROJ",
  "repository": "my-repo",
  "branch": "master",
  "search_path": "/",
  "pattern": "*.res",
  "files": [
    "src/App.res",
    "src/components/Button.res",
    "src/utils/DateUtils.res"
  ],
  "total_files_scanned": 5000,
  "total_matched": 150,
  "returned": 100,
  "truncated": true
}

This tool is particularly useful for:

  • Finding files by name pattern (like VS Code's Ctrl+P)

  • Discovering all files of a certain type in a repository

  • Locating configuration files or specific components

  • Exploring unfamiliar codebases

Get File Content

{
  "tool": "get_file_content",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "file_path": "src/index.ts",
    "branch": "main",  // Optional (defaults to default branch)
    "start_line": 1,  // Optional: starting line (1-based, use negative for from end)
    "line_count": 100,  // Optional: number of lines to return
    "full_content": false  // Optional: force full content (default: false)
  }
}

Smart Truncation Features:

  • Automatically truncates large files (>50KB) to prevent token overload

  • Default line counts based on file type:

    • Config files (.yml, .json): 200 lines

    • Documentation (.md, .txt): 300 lines

    • Code files (.ts, .js, .py): 500 lines

    • Log files: Last 100 lines

  • Use start_line: -50 to get last 50 lines (tail functionality)

  • Files larger than 1MB require explicit full_content: true or line parameters

Returns file content with:

  • File path and branch

  • File size and encoding

  • Content (full or truncated based on parameters)

  • Line information (if truncated):

    • Total lines in file

    • Range of returned lines

    • Truncation indicator

  • Last modified information (commit, author, date)

Example responses:

// Small file - returns full content
{
  "file_path": "package.json",
  "branch": "main",
  "size": 1234,
  "encoding": "utf-8",
  "content": "{\n  \"name\": \"my-project\",\n  ...",
  "last_modified": {
    "commit_id": "abc123",
    "author": "John Doe",
    "date": "2025-01-21T10:00:00Z"
  }
}

// Large file - automatically truncated
{
  "file_path": "src/components/LargeComponent.tsx",
  "branch": "main",
  "size": 125000,
  "encoding": "utf-8",
  "content": "... first 500 lines ...",
  "line_info": {
    "total_lines": 3500,
    "returned_lines": {
      "start": 1,
      "end": 500
    },
    "truncated": true,
    "message": "Showing lines 1-500 of 3500. File size: 122.1KB"
  }
}

Get File Blame

Get per-line authorship (blame) for a file — who last modified each line, the commit hash, and author timestamp. Feed the returned commit_id into get_commit_detail to see what actually changed.

Bitbucket Server only. Bitbucket Cloud does not expose a blame API.

// Full-file blame
{
  "tool": "get_file_blame",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "file_path": "src/index.ts"
  }
}

// Blame for a specific branch and line range
{
  "tool": "get_file_blame",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "file_path": "src/index.ts",
    "branch": "main",
    "start_line": 100,
    "line_count": 20
  }
}

// Ungrouped — one entry per line
{
  "tool": "get_file_blame",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "file_path": "src/index.ts",
    "group_by_commit": false
  }
}

Parameters:

  • file_path: File path, e.g. "src/index.ts" (required)

  • branch: Branch name (optional, defaults to default branch)

  • start_line: Starting line (1-based) to limit output (optional)

  • line_count: Number of lines to return from start_line (optional)

  • group_by_commit: Group contiguous lines from the same commit into ranges (default: true)

Response (grouped, default):

{
  "file_path": "src/index.ts",
  "branch": "main",
  "total_lines": 1982,
  "returned_lines": { "start": 1, "end": 1982 },
  "unique_commits": 42,
  "unique_authors": 16,
  "grouped": true,
  "blame": [
    {
      "line_start": 1,
      "line_end": 4,
      "commit_id": "fbbe61e95f51abb8aed8dd5a472074a77b3d0f46",
      "commit_display_id": "fbbe61e95f5",
      "author": { "name": "Jane Doe", "email": "jane@example.com" },
      "date": "2025-04-15T12:01:01.000Z",
      "original_file_name": "src/index.ts"
    }
  ]
}

Response (ungrouped, group_by_commit: false): each blame entry has a single line field instead of line_start/line_end.

Useful for:

  • Finding the main authors of a file before requesting reviews

  • Tracing who introduced a particular line or block

  • Feeding commit_id into get_commit_detail to see the full diff of a blamed change

  • Identifying code ownership when refactoring shared modules

List Projects

List all accessible Bitbucket projects (Server) or workspaces (Cloud):

// List all accessible projects
{
  "tool": "list_projects",
  "arguments": {
    "limit": 25,  // Optional (default: 25)
    "start": 0    // Optional: for pagination (default: 0)
  }
}

// Filter by project name
{
  "tool": "list_projects",
  "arguments": {
    "name": "backend",  // Partial name match
    "limit": 50
  }
}

// Filter by permission level (Bitbucket Server only)
{
  "tool": "list_projects",
  "arguments": {
    "permission": "PROJECT_WRITE",  // PROJECT_READ, PROJECT_WRITE, PROJECT_ADMIN
    "limit": 100
  }
}

Parameters:

  • name: Filter by project/workspace name (partial match, optional)

  • permission: Filter by permission level (Bitbucket Server only, optional)

    • PROJECT_READ: Read access

    • PROJECT_WRITE: Write access

    • PROJECT_ADMIN: Admin access

  • limit: Maximum number of projects to return (default: 25)

  • start: Start index for pagination (default: 0)

Returns project/workspace information:

{
  "projects": [
    {
      "key": "PROJ",
      "id": 1234,
      "name": "My Project",
      "description": "Project description",
      "is_public": false,
      "type": "NORMAL",  // NORMAL or PERSONAL (Server), WORKSPACE (Cloud)
      "url": "https://bitbucket.yourcompany.com/projects/PROJ"
    }
    // ... more projects
  ],
  "total_count": 15,
  "start": 0,
  "limit": 25,
  "has_more": false,
  "next_start": null
}

Note:

  • For Bitbucket Cloud, this returns workspaces (not projects in the traditional sense)

  • For Bitbucket Server, this returns both personal and team projects

This tool is particularly useful for:

  • Discovering available projects/workspaces for your account

  • Finding project keys needed for other API calls

  • Identifying projects you have specific permissions on

  • Browsing organizational structure

List Repositories

List repositories within a specific project/workspace or across all accessible repositories:

// List all repositories in a workspace/project
{
  "tool": "list_repositories",
  "arguments": {
    "workspace": "PROJ",  // Required for Bitbucket Cloud, optional for Server
    "limit": 25,          // Optional (default: 25)
    "start": 0            // Optional: for pagination (default: 0)
  }
}

// List all accessible repositories (Bitbucket Server only)
{
  "tool": "list_repositories",
  "arguments": {
    "limit": 100
  }
}

// Filter by repository name
{
  "tool": "list_repositories",
  "arguments": {
    "workspace": "PROJ",
    "name": "frontend",  // Partial name match
    "limit": 50
  }
}

// Filter by permission level (Bitbucket Server only)
{
  "tool": "list_repositories",
  "arguments": {
    "workspace": "PROJ",
    "permission": "REPO_WRITE",  // REPO_READ, REPO_WRITE, REPO_ADMIN
    "limit": 100
  }
}

Parameters:

  • workspace: Project key (Server) or workspace slug (Cloud)

    • Required for Bitbucket Cloud

    • Optional for Bitbucket Server (omit to list all accessible repos)

  • name: Filter by repository name (partial match, optional)

  • permission: Filter by permission level (Bitbucket Server only, optional)

    • REPO_READ: Read access

    • REPO_WRITE: Write access

    • REPO_ADMIN: Admin access

  • limit: Maximum number of repositories to return (default: 25)

  • start: Start index for pagination (default: 0)

Returns repository information:

{
  "repositories": [
    {
      "slug": "my-repo",
      "id": 5678,
      "name": "My Repository",
      "description": "Repository description",
      "project_key": "PROJ",
      "project_name": "My Project",
      "state": "AVAILABLE",  // AVAILABLE, INITIALISING, INITIALISATION_FAILED (Server)
      "is_public": false,
      "is_forkable": true,
      "clone_urls": {
        "http": "https://bitbucket.yourcompany.com/scm/PROJ/my-repo.git",
        "ssh": "ssh://git@bitbucket.yourcompany.com:7999/PROJ/my-repo.git"
      },
      "url": "https://bitbucket.yourcompany.com/projects/PROJ/repos/my-repo"
    }
    // ... more repositories
  ],
  "total_count": 42,
  "start": 0,
  "limit": 25,
  "has_more": true,
  "next_start": 25,
  "workspace": "PROJ"
}

Important Notes:

  • Bitbucket Cloud requires the workspace parameter. If omitted, you'll receive an error message

  • Bitbucket Server allows listing all accessible repos by omitting the workspace parameter

  • Clone URLs are provided for both HTTP(S) and SSH protocols

This tool is particularly useful for:

  • Discovering available repositories in a project/workspace

  • Finding repository slugs needed for other API calls

  • Identifying repositories you have specific permissions on

  • Getting clone URLs for repositories

  • Browsing repository structure within an organization

Search Repositories

Search for repositories by name or description (Bitbucket Server only):

// Basic search
{
  "tool": "search_repositories",
  "arguments": {
    "search_query": "backend",
    "limit": 10
  }
}

// Search within a specific project
{
  "tool": "search_repositories",
  "arguments": {
    "search_query": "dashboard",
    "workspace": "PROJ",
    "limit": 25
  }
}

Returns repository search results with project association.

Decline Pull Request

Decline/reject a pull request:

{
  "tool": "decline_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment": "Closing this PR as the feature is no longer needed"  // Optional
  }
}

Delete Comment

Delete a comment from a pull request:

{
  "tool": "delete_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_id": 456
  }
}

Note: Comments with replies cannot be deleted. Only the comment author, PR author, or repository admin can delete comments.

PR Task Management (Bitbucket Server only)

Tasks are checklist items that can be added to pull requests. They help track action items that need to be completed before merging.

List PR Tasks

{
  "tool": "list_pr_tasks",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Returns all tasks with their status:

{
  "pull_request_id": 123,
  "tasks": [
    {
      "id": 456,
      "text": "Update documentation",
      "author": "John Doe",
      "state": "OPEN",
      "created_on": "2025-01-25T10:00:00Z",
      "is_resolved": false
    }
  ],
  "summary": {
    "total": 3,
    "open": 2,
    "resolved": 1
  }
}

Create PR Task

{
  "tool": "create_pr_task",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "text": "Add unit tests for the new feature"
  }
}

Update PR Task

{
  "tool": "update_pr_task",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "task_id": 456,
    "text": "Add unit tests and integration tests"
  }
}

Mark/Unmark Task as Done

// Mark as done
{
  "tool": "mark_pr_task_done",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "task_id": 456
  }
}

// Reopen task
{
  "tool": "unmark_pr_task_done",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "task_id": 456
  }
}

Delete PR Task

{
  "tool": "delete_pr_task",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "task_id": 456
  }
}

Convert Between Comments and Tasks

// Convert a comment to a task
{
  "tool": "convert_comment_to_task",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_id": 456
  }
}

// Convert a task back to a comment
{
  "tool": "convert_task_to_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "task_id": 456
  }
}

Note on Tasks:

  • Tasks are implemented as comments with severity: "BLOCKER" in Bitbucket Server

  • Tasks can be in OPEN or RESOLVED state

  • Only the task creator, PR author, or repository admin can edit text or delete tasks

  • Anyone with read access can mark tasks as done/undone

Development

  • npm run dev - Watch mode for development

  • npm run build - Build the TypeScript code

  • npm start - Run the built server

Troubleshooting

  1. Authentication errors: Double-check your username and app password

  2. 404 errors: Verify the workspace, repository slug, and PR ID

  3. Permission errors: Ensure your app password has the required permissions

License

MIT

Available Tools

19 tools
add_commentA

Add a comment to a pull request. Supports: 1) General PR comments, 2) Replies to existing comments, 3) Inline comments on specific code lines (using line_number OR code_snippet), 4) Code suggestions for single or multi-line replacements. For inline comments, you can either provide exact line_number or use code_snippet to auto-detect the line.

ParametersJSON Schema
NameRequiredDescriptionDefault
code_snippetNoExact code text from the diff to find and comment on. Use this instead of line_number for auto-detection. Must match exactly including whitespace (optional)
comment_textYesThe main comment text. For suggestions, this is the explanation before the code suggestion.
file_pathNoFile path for inline comment. Required for inline comments. Example: "src/components/Button.js" (optional)
line_numberNoExact line number in the file. Use this OR code_snippet, not both. Required with file_path unless using code_snippet (optional)
line_typeNoType of line: ADDED (green/new lines), REMOVED (red/deleted lines), or CONTEXT (unchanged lines). Default: CONTEXT
match_strategyNoHow to handle multiple matches when using code_snippet. "strict": fail with detailed error showing all matches. "best": automatically pick the highest confidence match. Default: "strict"
parent_comment_idNoID of comment to reply to. Use this to create threaded conversations (optional)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
search_contextNoAdditional context lines to help locate the exact position when using code_snippet. Useful when the same code appears multiple times (optional)
suggestionNoReplacement code for a suggestion. Creates a suggestion block that can be applied in Bitbucket UI. Requires file_path and line_number. For multi-line, include newlines in the string (optional)
suggestion_end_lineNoFor multi-line suggestions: the last line number to replace. If not provided, only replaces the single line at line_number (optional)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It adds meaningful context by explaining supported comment types, the auto-detection behavior of code_snippet, and the distinction between single and multi-line suggestions. This goes beyond a simple 'add comment' statement, though it does not mention side effects or error handling (e.g., strict match failures), which are partially covered in the schema.

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 concise, front-loaded with the primary purpose, and uses a numbered list to structure four distinct capabilities. Every sentence adds value without redundancy, making it easy to parse quickly.

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 complexity (13 params, nested objects, no output schema), the description covers the main functionality and usage patterns well. It lacks explicit guidance on some edge cases or return values, but the schema compensates. The description is complete enough for an agent to select and invoke the tool correctly in most scenarios.

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 schema already provides 100% coverage with detailed descriptions for all 13 parameters, including relationships like 'Use this OR code_snippet, not both.' The description adds a high-level synthesis of modes but does not provide additional parameter-level semantics beyond what the schema states. 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 verb+resource ('Add a comment to a pull request') and enumerates four distinct modes: general comments, replies, inline comments, and code suggestions. This differentiates it from sibling tools like approve_pull_request or request_changes, making its purpose unambiguous.

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

Usage Guidelines4/5

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

The description explains when to use the tool (for adding comments) and provides guidance on selecting modes (e.g., line_number vs code_snippet). It does not explicitly contrast with alternatives, but the four-mode breakdown gives clear context for choosing among tool features. No exclusions are stated, but the tool's scope is evident.

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

approve_pull_requestC

Approve a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Approve a pull request' without mentioning state changes, permissions, reversibility, or side effects. This is insufficient for a mutation tool.

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 short sentence with no unnecessary words, achieving excellent conciseness. It is front-loaded and to the point.

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 mutation tool with no annotations and no output schema, the description lacks necessary context. It does not explain what happens upon approval, whether the operation is reversible, or what response to expect, leaving significant gaps.

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%, with each parameter clearly described. The tool description adds no additional parameter information, so the baseline score of 3 applies.

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 states the specific verb 'approve' and resource 'pull request', clearly distinguishing it from siblings like 'request_changes' or 'merge_pull_request'. However, it is very terse and could be more explicit about what approving entails.

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

Usage Guidelines1/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 'request_changes' or 'unapprove_pull_request'. It simply states the action without any context or exclusions.

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

create_pull_requestC

Create a new pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
close_source_branchNoWhether to close source branch after merge (optional, default: false)
descriptionNoDescription of the pull request (optional)
destination_branchYesDestination branch name (e.g., "main", "master")
repositoryYesRepository slug (e.g., "my-repo")
reviewersNoArray of reviewer usernames/emails (optional)
source_branchYesSource branch name
titleYesTitle of the pull request
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

C2.7/5.0
Behavior1/5

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It merely restates the action without mentioning side effects (e.g., creating a PR in Bitbucket), required permissions, potential failures, or the outcome of the operation.

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 zero wasted words. It is appropriately front-loaded and concise, though 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 8 parameters, no output schema, and no annotations, the description is too minimal to provide complete context. It does not explain the expected result, error scenarios, or how this tool fits into the pull request lifecycle beyond the obvious act of creation.

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 documents all 8 parameters thoroughly. The description adds no additional parameter semantics, but this is acceptable given the schema's completeness.

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 'Create a new pull request' uses a specific verb and resource, clearly distinguishing the action from sibling tools like update_pull_request or merge_pull_request. However, it lacks any additional detail about scope or context, such as the Bitbucket workspace or repository, which are only found 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 Guidelines2/5

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

There is no explicit guidance on when to use this tool versus alternatives. The verb 'create' implies a new resource, but the description does not state exclusions (e.g., do not use this to update existing PRs) or mention any prerequisites like branch existence.

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

delete_branchC

Delete a branch

ParametersJSON Schema
NameRequiredDescriptionDefault
branch_nameYesBranch name to delete
forceNoForce delete even if branch is not merged (optional, default: false)
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

C2.9/5.0
Behavior1/5

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It fails to mention that this is a destructive, irreversible operation, the existence of a force flag, or any error conditions. The description adds no behavioral insight beyond the tool 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?

The description is one short, front-loaded sentence with no wasted words. It is appropriately concise, though under-specified in other dimensions.

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 destructive tool with no annotations and no output schema, the description is incomplete. It lacks any mention of safety implications, force behavior, or failure conditions, leaving the agent without sufficient context to use it safely.

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% for all 4 parameters, so the baseline is 3. The description itself does not add any parameter-related meaning, but the schema fully documents them.

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 "Delete a branch" clearly states the action and resource, distinguishing it from siblings like get_branch or list_branches. It is specific and unambiguous.

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, any prerequisites (e.g., branch must be merged), or alternatives. It simply states the action without context.

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

get_branchA

Get detailed information about a branch including associated pull requests

ParametersJSON Schema
NameRequiredDescriptionDefault
branch_nameYesBranch name to get details for
include_merged_prsNoInclude merged PRs from this branch (default: false)
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it "gets" information, which implies a read-only operation, but it does not explicitly mention that it has no side effects, nor does it describe what "detailed information" includes or any default behaviors (e.g., whether merged PRs are included by default). The only behavioral hint is the mention of associated PRs, but 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.

Conciseness5/5

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

The description is a single, concise sentence that is front-loaded with the core purpose and includes a relevant detail about PRs. There is no redundant or filler text, making it highly efficient.

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?

For a read-only tool with no output schema, the description gives a general idea of the response (detailed branch info + associated PRs) but lacks specifics about return shape or edge cases. The explicit mention of "associated pull requests" adds value, yet the vague phrase "detailed information" leaves some uncertainty. Overall, it is minimally adequate but not comprehensive.

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 descriptions for all four parameters. The description itself does not add parameter-specific meaning, but the schema already fully documents each parameter. Baseline 3 is appropriate since the description does not go beyond the schema.

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 states a clear verb+resource: "Get detailed information about a branch" and adds a distinguishing detail, "including associated pull requests." This differentiates it from sibling tools like list_branches (which lists branches) and get_pull_request (which gets a single PR). The purpose is unambiguous.

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 use when a user needs branch details along with associated PRs, but it does not explicitly state when to use this over alternatives or mention any exclusions. There is no direct guidance like "use list_branches for branch names only," so usage is only implied.

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

get_file_contentB

Get file content from a repository with smart truncation for large files

ParametersJSON Schema
NameRequiredDescriptionDefault
branchNoBranch name (optional, defaults to default branch)
file_pathYesPath to the file (e.g., "src/index.ts")
full_contentNoForce return full content regardless of size (optional, default: false)
line_countNoNumber of lines to return (optional, default varies by file size)
repositoryYesRepository slug (e.g., "my-repo")
start_lineNoStarting line number (1-based). Use negative for lines from end (optional)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.2/5.0
Behavior3/5

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

The description discloses the behavioral trait of smart truncation for large files, which adds value beyond the raw schema. However, with no annotations provided, the description carries the full burden and only vaguely references 'smart truncation' without explaining specifics like response formats, binary file handling, or permission requirements. This is partial disclosure, scoring 3.

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, well-structured sentence that immediately conveys the tool's purpose and key behavioral aspect. It is front-loaded and contains no filler. Every word contributes value, making it exemplary in 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?

With 7 parameters, no output schema, and no annotations, the one-sentence description is insufficient for full contextual understanding. It does not explain the truncation mechanism, potential return values, error handling, or how to retrieve full content (despite full_content being a parameter). The tool's behavior remains underspecified, so completeness is low.

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% parameter description coverage, so the baseline is 3. The description mentions truncation, which relates to parameters like line_count and full_content, but adds no specific parameter-level meaning beyond what the schema already provides. Thus, it meets the baseline without enhancement.

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 file content from a repository, using the verb 'Get' and specific resource 'file content'. It includes a distinctive feature ('smart truncation for large files') that adds context. While it does not explicitly distinguish from siblings like list_directory_content, the action is unique enough; a 4 is appropriate for clear verb+resource but no explicit sibling 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?

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or conditions. It simply states what the tool does without contextual advice. Since there is no mention of when not to use it or how it compares to other tools, the score is 2 ('no guidance').

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

get_pull_requestA

Get details of a Bitbucket pull request including merge commit information

ParametersJSON Schema
NameRequiredDescriptionDefault
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.7/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 burden of behavioral disclosure. It indicates this is a read operation ('Get details') and mentions the inclusion of merge commit information, which is useful context. However, it does not disclose potential errors, authentication requirements, or the exact shape of the response beyond merge commit info.

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, front-loaded sentence that directly states the tool's purpose and a key detail. Every word earns its place, and there is no 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?

For a simple read tool with three well-documented parameters and no output schema, the description is reasonably complete. It tells the agent what to expect (details including merge commit info). However, it could be more specific about what 'details' encompasses or that it returns the full pull request object, which would provide more complete 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 provides descriptions for all three parameters, covering 100% of the schema. The description itself adds no extra parameter-level meaning, but this is acceptable because the schema already fully documents workspace, repository, and pull_request_id.

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's function with a specific verb ('Get'), a specific resource ('details of a Bitbucket pull request'), and an explicit detail ('including merge commit information'). It distinguishes this tool from siblings like list_pull_requests (which lists) and update_pull_request (which modifies).

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 when to use this tool (when you need details of a single pull request) but does not explicitly state when not to use it or name alternatives. Given sibling tool names, usage context is somewhat implied but not fully articulated.

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

get_pull_request_diffB

Get the diff/changes for a pull request with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
context_linesNoNumber of context lines around changes (optional, default: 3)
exclude_patternsNoArray of glob patterns to exclude (e.g., ["*.lock", "*.svg"]) (optional)
file_pathNoSpecific file path to get diff for (e.g., "src/index.ts") (optional)
include_patternsNoArray of glob patterns to include (e.g., ["*.res", "src/**/*.js"]) (optional)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions 'optional filtering' but does not explain output format, pagination, how filters interact, or any limitations. This is insufficient for a tool with no supporting annotations.

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, front-loaded sentence that conveys the core function and optional filtering without waste. Every word contributes to understanding.

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 7 parameters, no output schema, and no annotations, a one-sentence description is inadequate. It does not explain what the diff includes, how filters combine, or any edge cases, making the tool harder to use 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?

Schema description coverage is 100%, so the baseline is 3. The phrase 'optional filtering' adds general context for the include/exclude and file_path parameters but does not provide syntax or behavioral details beyond what the schema already specifies.

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's function: 'Get the diff/changes for a pull request with optional filtering.' This uses a specific verb and resource, and distinguishes it from sibling tools like get_pull_request (which likely returns metadata) and get_file_content (which fetches file contents).

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 usage for retrieving pull request changes but does not explicitly state when to use this tool versus alternatives. No mention of exclusions or specific circumstances, though the purpose itself suggests the main use case.

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

list_branch_commitsB

List commits in a branch with detailed information and filtering options

ParametersJSON Schema
NameRequiredDescriptionDefault
authorNoFilter by author email/username (optional)
branch_nameYesBranch name to get commits from
include_merge_commitsNoInclude merge commits in results (default: true)
limitNoMaximum number of commits to return (default: 25)
repositoryYesRepository slug (e.g., "my-repo")
searchNoSearch for text in commit messages (optional)
sinceNoISO date string - only show commits after this date (optional)
startNoStart index for pagination (default: 0)
untilNoISO date string - only show commits before this date (optional)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'detailed information and filtering options' without explaining any behavioral specifics like pagination, ordering, default values for include_merge_commits, or return format. It does not even explicitly state that the operation is read-only beyond the verb 'List'. The description adds little value over the schema.

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 concise single sentence that front-loads the primary action. It is appropriately sized for the tool's complexity, though it could be slightly more structured by explicitly listing key filtering capabilities. It earns a 4 for being efficient and avoid unnecessary verbosity.

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 has 10 parameters, no output schema, and no annotations, the description is far too brief to provide adequate context. It does not explain return value structure, pagination behavior, default limits (though defaults are in schema), or any special considerations like how merge commits are handled. The description leaves significant gaps for an agent to understand the full behavior and output of the 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 description coverage is 100% (all 10 parameters have descriptions), so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides. It mentions 'filtering options' generically, which is already covered by the parameter descriptions for since, until, author, search, etc.

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's function: listing commits in a branch. It uses a specific verb ('List') and resource ('commits in a branch'), which distinguishes it from siblings like list_pr_commits (in a pull request) and list_branches (listing branches). However, the phrase 'detailed information and filtering options' is somewhat vague and does not explicitly distinguish from all siblings.

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

Usage Guidelines4/5

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

The description implies the tool is used when you need commits from a specific branch, providing clear context. It does not mention alternatives or exclusions, but the resource and scope are explicit enough that an AI agent can infer when to invoke it. This meets the 'clear context, no exclusions' criterion.

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

list_branchesB

List branches in a repository

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoFilter branches by name pattern (optional)
limitNoMaximum number of branches to return (default: 25)
repositoryYesRepository slug (e.g., "my-repo")
startNoStart index for pagination (default: 0)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'list branches' and does not mention pagination behavior, response format, permissions, or any side effects. This is a significant gap for a tool with pagination parameters.

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 filler or redundancy. It is appropriately sized for a simple list operation, and the main verb is front-loaded.

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 a basic list tool, the description is sufficient for an agent to understand what it does. The schema covers all parameters, and while the description does not mention return values, the absence of an output schema makes that less critical. However, the lack of behavioral transparency slightly reduces completeness.

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% parameter description coverage, providing detailed meaning for all five parameters. The description adds no additional parameter semantics beyond the schema, so the baseline score of 3 applies.

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 'List branches in a repository' clearly states the action (list) and the resource (branches), with a scoping location (repository). It is specific enough to distinguish from sibling tools like delete_branch or get_branch, though it does not explicitly name alternatives.

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 when to use the tool—when you need to list branches in a repository—but it does not explicitly mention alternatives or exclusions. Usage context is clear but not elaborated.

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

list_directory_contentA

List files and directories in a repository path

ParametersJSON Schema
NameRequiredDescriptionDefault
branchNoBranch name (optional, defaults to default branch)
pathNoDirectory path (optional, defaults to root, e.g., "src/components")
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic read operation ('List') but does not reveal important traits like whether the listing is recursive, includes hidden files, or how permissions are handled. This is insufficient for a tool with no annotation support.

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 redundant words. It is front-loaded with the action and resource, making it easy to scan and understand.

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 tool's simplicity and the schema's full parameter coverage, the description is minimally adequate. However, it lacks details about the return format or any recursive behavior, which would be useful since there is no output schema. It is incomplete in those respects.

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 schema provides complete descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds no extra meaning about parameters beyond what the schema already states, hence it neither helps nor harms.

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's function with a specific verb ('List') and resource ('files and directories') within a repository path. It is unambiguous and distinguishes itself from siblings like get_file_content and list_branches by specifying directory listing.

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 usage is implied by the name and description: it is used to browse repository contents. However, there are no explicit instructions on when to choose this tool over alternatives, such as get_file_content for file retrieval or search_code for queries.

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

list_pr_commitsB

List all commits that are part of a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of commits to return (default: 25)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
startNoStart index for pagination (default: 0)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

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 carries the full burden of behavioral disclosure but falls short. It does not mention that results are paginated (the schema includes limit and start parameters), nor does it clarify that 'all commits' may be limited by default (max 25). It also fails to specify output format, ordering, or how commits are defined relative to the PR. The word 'all' could mislead users into expecting every commit regardless of pagination.

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, front-loaded with the action and resource. It avoids unnecessary words or repetition, making it extremely efficient while still conveying 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?

Despite the tool's moderate complexity (pagination, PR association, no output schema), the description provides minimal context. It does not clarify what 'part of a pull request' means (e.g., commits on the source branch), how pagination is handled, or what fields are returned. The schema covers parameters, but the description lacks behavioral and return-value details, making it insufficient for an agent to fully understand the tool's behavior.

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 provides descriptions for all 5 parameters, giving 100% coverage. The description adds no semantic value beyond the schema; it does not explain how parameters interact (e.g., that limit and start control pagination). Since schema coverage is high, a baseline score of 3 is appropriate, but the description could have reinforced key parameter behavior.

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 and specifically states the tool's function: 'List all commits that are part of a pull request'. It uses a specific verb (list) and a distinct resource (commits within a pull request), which distinguishes it from sibling tools like list_branch_commits or 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, such as when needing branch commits instead (list_branch_commits), nor does it reference any sibling tools or usage context. The only implication is that it is used for PR commits, but no explicit differentiation is offered.

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

list_pull_requestsC

List pull requests for a repository with optional filters

ParametersJSON Schema
NameRequiredDescriptionDefault
authorNoFilter by author username
limitNoMaximum number of PRs to return (default: 25)
repositoryYesRepository slug (e.g., "my-repo")
startNoStart index for pagination (default: 0)
stateNoFilter by PR state: OPEN, MERGED, DECLINED, ALL (default: OPEN)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read operation via 'List', but does not mention default state filtering (OPEN), pagination behavior, or return format. This is minimal and does not expose important behaviors.

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 of 10 words, front-loaded with the verb and resource. Every word contributes to the core purpose, with no redundancy or filler.

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 six parameters, no output schema, and no annotations, the one-sentence description is insufficient. It does not explain default behavior, pagination semantics, or what the returned list contains, leaving significant gaps for an agent to infer.

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 six parameters are fully described in the input schema, so the description adds no parameter-level detail beyond the generic note about 'optional filters'. With schema coverage at 100%, the baseline of 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 uses the specific verb 'List' and the resource 'pull requests', scoped to 'a repository', clearly indicating a multi-item listing operation. It indirectly distinguishes from 'get_pull_request' via the plural form, but does not explicitly name sibling alternatives.

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 offers no guidance on when to use this tool versus alternatives like get_pull_request, create_pull_request, or merge_pull_request. It only states the basic function with no exclusions or recommendations.

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

merge_pull_requestC

Merge a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
close_source_branchNoWhether to close source branch after merge (optional)
commit_messageNoCustom merge commit message (optional)
merge_strategyNoMerge strategy: merge-commit, squash, fast-forward (optional)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description bears the full burden of behavioral disclosure. It simply says 'Merge a pull request', but does not state that merging is an irreversible action, what side effects occur (e.g., source branch closing), or whether special permissions are required. The schema hints at some parameters, but the description itself adds no transparency.

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 short sentence that is front-loaded and not verbose. It is crisp but lacks substantive content; still, for conciseness alone, it is appropriately sized—though under-specified.

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 description is minimal for a tool with six parameters, no annotations, and no output schema. It fails to explain merge strategies, optional fields, side effects (like source branch deletion), or what happens after the merge. The rich schema cannot compensate for the lack of high-level behavioral 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 description coverage is 100%, so all six parameters are already documented with descriptions and enum values. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 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 uses the specific verb 'merge' with a clear resource ('a pull request'), which distinguishes it from sibling tools like create, update, approve, or request changes. However, it lacks any additional context (e.g., platform, scope) beyond the inherent meaning of the tool name.

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 approve_pull_request or update_pull_request. The description does not mention prerequisites, when merging is appropriate, or any caveats about merge strategies or branch deletion.

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

remove_requested_changesB

Remove change request from a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are present, so the description carries the full burden. It does not disclose side effects (e.g., changing the pull request review status), permissions required, or behavior if no change request exists. This is a mutation tool with 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, front-loaded sentence with no unnecessary words. It is easily parsed and efficiently conveys the core action.

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?

Despite low complexity, the description omits critical context about what 'change request' means in the Bitbucket review workflow, the effect on the PR status, and any preconditions. With no annotations, the tool is under-specified for an agent to use confidently.

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 descriptions for all three parameters (workspace, repository, pull_request_id) with 100% coverage. The description adds no additional parameter meaning, so the 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 action ('Remove') and the target ('change request from a pull request'), making it distinct from the sibling tool request_changes which adds a change request. The verb+resource structure is specific and unambiguous.

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, whether a prior change request must exist, or how it fits with approve/unapprove flows. There are no exclusions or alternatives mentioned, leaving the agent to infer usage from the sibling names alone.

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

request_changesB

Request changes on a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
commentNoComment explaining requested changes (optional)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description must disclose behavioral traits, but it only states the action without explaining consequences (e.g., whether this blocks merging, creates a review thread, or notifies the author). The mutation effect is implied but not elaborated, which is insufficient for a write operation.

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 that directly states the tool's purpose. It contains no filler, redundancy, or unnecessary detail, making it easy to parse and immediately actionable.

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 tool's simplicity and full schema coverage, the description is minimally adequate but lacks behavioral context (e.g., effect on PR state) that would be expected for a mutation tool with no annotations. It answers 'what' but not 'so what' or 'what next', leaving some gaps in completeness.

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 input schema fully documents all four parameters (workspace, repository, pull_request_id, comment). The description adds no parameter-level details beyond the schema, warranting the baseline score of 3.

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 ('Request changes') and the resource ('a pull request'), using a specific verb and object. It distinguishes itself from sibling tools like approve_pull_request, unapprove_pull_request, and merge_pull_request by naming a distinct operation.

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 versus alternatives such as add_comment or update_pull_request. There is no mention of preconditions, typical scenarios, or exclusions, leaving the agent to infer usage from the name alone.

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

search_codeA

Search for code across Bitbucket repositories with enhanced context-aware search patterns (currently only supported for Bitbucket Server)

ParametersJSON Schema
NameRequiredDescriptionDefault
file_patternNoFile path pattern to filter results (e.g., "*.java", "src/**/*.ts") (optional)
include_patternsNoAdditional custom search patterns to include (e.g., ["variable =", ".variable"]) (optional)
limitNoMaximum number of results to return (default: 25)
repositoryNoRepository slug to search in (optional, searches all repos if not specified)
search_contextNoContext to search for: assignment (term=value), declaration (defining term), usage (calling/accessing term), exact (quoted match), or any (all patterns)
search_queryYesThe search term or phrase to look for in code (e.g., "variable")
startNoStart index for pagination (default: 0)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.6/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It only hints at 'enhanced context-aware search patterns' without explaining what that means, nor does it disclose read-only nature, result format, pagination behavior, or any side effects. For a search operation, the agent is left guessing about the return payload and exact behavior beyond the schema.

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, well-structured sentence. It leads with the primary action and resource, then adds a critical constraint (Bitbucket Server only). Every word is useful and no information is wasted, making it appropriately concise and front-loaded.

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?

Despite having 8 parameters and no output schema, the description is minimal and does not explain key aspects such as the structure of results, default behavior (e.g., all repositories), or the meaning of 'context-aware' search. It lacks critical context that an agent needs to confidently invoke the tool, especially given the absence of annotations and output schema.

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 baseline is 3. The description's phrase 'context-aware search patterns' loosely maps to the 'search_context' parameter, but it does not add meaningful parameter-specific information beyond what the schema already provides. It does not clarify usage of parameters like 'file_pattern' or 'include_patterns' further.

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's function: 'Search for code across Bitbucket repositories.' It uses a specific verb ('search'), names the resource ('code' in Bitbucket repositories), and is distinct from sibling tools (which focus on pull requests, branches, and file content). The mention of 'enhanced context-aware search patterns' further specifies its unique capability, though not fully detailed.

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

Usage Guidelines4/5

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

The description provides clear context for when to use the tool (searching code) and includes an explicit constraint: 'currently only supported for Bitbucket Server.' This helps agents avoid using it for Bitbucket Cloud. However, it does not mention alternatives because no sibling tools offer code search, so the 'when-not' is partially covered by the server restriction.

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

unapprove_pull_requestA

Remove approval from a pull request

ParametersJSON Schema
NameRequiredDescriptionDefault
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.6/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of explaining behavior. It only states 'Remove approval from a pull request' without disclosing side effects, permissions, behavior when no approval exists, or irreversibility. This is a mutation tool with minimal behavioral disclosure.

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, clear sentence that directly states the action and object. It is concise with no repetitive or extraneous information.

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 simple operation, three required parameters with full schema descriptions, and no output schema, the description is largely complete. It states what the tool does and the schema covers arguments. However, behavioral details (e.g., effect if no approval exists) are absent, which prevents a perfect score.

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 full descriptions for all three parameters (workspace, repository, pull_request_id) at 100% coverage. The description adds no additional parameter semantics, but none are needed beyond the schema.

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 'Remove approval from a pull request' clearly states a specific action (remove approval) and the resource (pull request). It distinguishes itself from siblings like approve_pull_request and remove_requested_changes, which have different purposes.

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 does not provide explicit guidance on when to use this tool versus alternatives such as approve_pull_request or remove_requested_changes. The intended usage is implied by the name and verb, but no exclusions or alternative references are given.

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

update_pull_requestA

Update an existing pull request. When updating without specifying reviewers, existing reviewers and their approval status will be preserved.

ParametersJSON Schema
NameRequiredDescriptionDefault
descriptionNoNew description (optional)
destination_branchNoNew destination branch (optional)
pull_request_idYesPull request ID
repositoryYesRepository slug (e.g., "my-repo")
reviewersNoNew list of reviewer usernames/emails. If provided, replaces the reviewer list (preserving approval status for existing reviewers). If omitted, existing reviewers are preserved. (optional)
titleNoNew title (optional)
workspaceYesBitbucket workspace/project key (e.g., "PROJ")

TDQS

A3.9/5.0
Behavior3/5

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

The description discloses a genuinely important behavioral trait—preserving reviewers and approval status when reviewers are not specified—which is valuable beyond the basic update action. However, with no annotations, it does not address permissions, reversibility, or other side effects, so it is only partially transparent.

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 just two sentences, front-loaded with the primary action and immediately followed by a critical caveat. There is no filler or redundancy.

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 7 parameters, no annotations, and no output schema, the description covers the key reviewer preservation nuance but omits other update semantics (e.g., partial vs full update, response shape, prerequisites). The schema fills parameter details, but the tool description is lean 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?

All seven parameters are already fully described in the input schema (100% coverage), and the tool description essentially repeats the reviewer caveat already present in the schema. It adds no new semantic value beyond what the schema provides.

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 and resource ('Update an existing pull request') and adds a clarifying behavioral note about reviewer preservation, which helps distinguish it from create_pull_request or merge_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 Guidelines4/5

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

The phrase 'existing pull request' clearly signals it is for modifying already-created PRs, and the reviewer caveat gives a concrete usage condition. It does not explicitly mention alternatives like create_pull_request, but the context and sibling tool names make the use case clear.

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 updatesv1.0.0
    • First observedadd_comment
    • First observedapprove_pull_request
    • First observedcreate_pull_request
    • First observeddelete_branch
    • First observedget_branch
    • First observedget_file_content
    • First observedget_pull_request
    • First observedget_pull_request_diff
    • First observedlist_branch_commits
    • First observedlist_branches
    • First observedlist_directory_content
    • First observedlist_pr_commits
    • First observedlist_pull_requests
    • First observedmerge_pull_request
    • First observedremove_requested_changes
    • First observedrequest_changes
    • First observedsearch_code
    • First observedunapprove_pull_request
    • First observedupdate_pull_request
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.3/5.0

Scored across 19 tools

Disambiguation5/5

Each tool has a distinct purpose with clear boundaries. For example, list_pull_requests retrieves a list, get_pull_request gets details, create_pull_request creates new ones, and update_pull_request modifies existing ones. There is no functional overlap between tools like approve_pull_request, request_changes, and remove_requested_changes, which all handle different review states.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case. Verbs like list, get, create, update, delete, add, approve, merge, remove, request, search, and unapprove are used predictably. There are no deviations in naming conventions across the 19 tools.

Tool Count4/5

With 19 tools, the count is slightly high but reasonable for a comprehensive Bitbucket server covering repositories, branches, pull requests, and code operations. It includes core CRUD and lifecycle management without being excessive, though it borders on the upper limit of typical scopes.

Completeness5/5

The tool set provides complete coverage for Bitbucket operations, including full pull request lifecycle (create, get, list, update, approve, request changes, merge, comment), branch management (list, get, delete), repository navigation (list directory, get file), and code search. No obvious gaps exist for the domain.

Maintenance

ActivityStale
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Bitbucket MCP Server

    zhanglc
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that provides tools for interacting with the Bitbucket API, supporting both Bitbucket Cloud and Bitbucket Server, enabling pull request, branch, file, code review, and search operations.
    19
    5,589 npm
    MIT

  • Bitbucket MCP

    inconcept
    A
    license
    B
    quality
    C
    maintenance
    An MCP server for Bitbucket Cloud that enables managing pull requests, branches, and repositories in natural language from any MCP-capable client.
    23
    186 npm
    4
    MIT

  • Bitbucket MCP Server

    nbhson
    A
    license
    B
    quality
    B
    maintenance
    MCP server for Bitbucket Server integration, enabling project, repository, pull request, source code, branch, and code review operations via the Bitbucket Server APIs.
    27
    13 npm
    MIT

Appeared in Searches