> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/ai-testing/mcp/mcp-tools.md).

# Tools

BugBug MCP provides a set of tools that let AI assistants work with BugBug projects through the Model Context Protocol. The tool list grows as new features are added, so the tables below group the tools by area.

{% hint style="info" %}
BugBug MCP access requires a **Pro or higher** BugBug plan. Enable human confirmation for authorized changes and runs.
{% endhint %}

To reduce risk, enable human confirmation in your AI client for tools that create, update, delete, import, or run BugBug assets. Use read-only tools first when planning, reviewing, or debugging.

List and create tools take a `projectId`. Other tools take the ID of the item they work on. List tools return a short summary of each item; use the matching `get` tool for full details. Batch tools, such as `bugbug_create_steps`, report success or failure for each item separately.

## Tests

Use these tools to list, inspect, create, update, import, and run BugBug tests.

| Tool                           | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `bugbug_list_tests`            | List BugBug tests. Supports filtering by name. |
| `bugbug_get_test`              | Get details of a specific test.                |
| `bugbug_create_tests`          | Create one or more new tests.                  |
| `bugbug_patch_test`            | Partially update a test.                       |
| `bugbug_delete_test`           | Delete a test by ID.                           |
| `bugbug_import_test`           | Import a test from YAML or ZIP.                |
| `bugbug_update_step_position`  | Move a step within a test.                     |
| `bugbug_update_group_position` | Move a group within a test.                    |
| `bugbug_run_test`              | Start a test run by test name or ID.           |

### Run a test

`bugbug_run_test` takes:

| Parameter      | Value                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `testNameOrId` | Required. The test's name or UUID.                                                                                                                  |
| `profileName`  | Optional. The [profile](/editing-tests/variables.md) to run with, by name or UUID. If omitted, the test's default profile is used.                  |
| `variables`    | Optional. Values to override for this run, as a list of `{ "key": ..., "value": ... }`.                                                             |
| `projectId`    | Optional. Pass it when you sign in with access to several projects and the profile name exists in more than one of them, or use the profile's UUID. |

The tool returns right away with the run ID and a link to watch the run in BugBug. To get the result, call `bugbug_watch_run_progress`, then `bugbug_get_test_run`. `bugbug_watch_run_progress` can return before the run finishes, for example when your client's time limit for a tool call runs out. Call it again while the status isn't final. `bugbug_run_suite` works the same way with `suiteId`.

Sample prompt:

{% prompt description="Inspect a login test and its final assertion" defaultExpanded="full" %}

```markdown
For the <project> login flow, find the matching test and inspect its steps and final assertion. This is read-only. If multiple tests match or context is missing, ask me to choose. Return the test name, the assertion assessment, and specific evidence; do not change anything.
```

{% endprompt %}

## Suites

Use these tools to list, inspect, create, update, delete, and run test suites.

| Tool                  | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `bugbug_list_suites`  | List BugBug test suites. Supports filtering by name. |
| `bugbug_get_suite`    | Get details of a specific suite.                     |
| `bugbug_create_suite` | Create a new suite.                                  |
| `bugbug_update_suite` | Update a suite.                                      |
| `bugbug_delete_suite` | Delete a suite by ID.                                |
| `bugbug_run_suite`    | Start a suite run by suite ID.                       |

`bugbug_update_suite` changes only the fields you pass. When you pass `tests`, that list replaces the suite's tests: tests not in the list are removed from the suite, and new ones are added. Tests that were already in the suite keep their on/off state in the suite, and newly added tests are on. If you leave `tests` out, the suite's tests don't change.

Sample prompt:

{% prompt description="Recommend a smoke-test suite" defaultExpanded="full" %}

```markdown
For <project> and the <release/environment> deployment, list the smoke suites and inspect their membership and recent run results. This is read-only. If the target environment or release criteria are missing, ask me. Return the recommended suite, rationale, and evidence; do not start a run.
```

{% endprompt %}

## Test Runs & Suite Runs

Use these tools to inspect test and suite run history, wait for active runs, and stop running jobs.

| Tool                                    | Description                                                                                                          |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `bugbug_list_test_runs`                 | List historical test runs.                                                                                           |
| `bugbug_get_test_run`                   | Get detailed results of a test run.                                                                                  |
| `bugbug_list_suite_runs`                | List suite runs.                                                                                                     |
| `bugbug_get_suite_run`                  | Get results of a suite run: a compact view with the failed tests and their failing step by default, or the full run. |
| `bugbug_watch_run_progress`             | Wait for a test or suite run to finish and stream progress.                                                          |
| `bugbug_stop_run`                       | Stop a running test or suite run.                                                                                    |
| `bugbug_get_test_run_inbox`             | List or read emails received by a test run inbox.                                                                    |
| `bugbug_delete_test_run_inbox_messages` | Delete one message or clear a test run inbox.                                                                        |

Sample prompt:

{% prompt description="Diagnose the latest failed checkout run" icon="bug" defaultExpanded="full" %}

```markdown
For the <project> checkout test, inspect the latest failed run and its failed-step details, screenshots, logs, and DOM evidence. This is read-only. If no failed run or test identifier is available, ask me for one. Return the failure classification, supporting evidence, and smallest proposed fix; do not modify or rerun the test.
```

{% endprompt %}

## Steps

Use these tools to inspect, create, update, and delete test steps.

| Tool                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `bugbug_get_step`     | Get details of a specific step.                    |
| `bugbug_create_steps` | Create one or more steps with typed step payloads. |
| `bugbug_update_steps` | Partially update one or more steps.                |
| `bugbug_delete_steps` | Delete steps by ID.                                |

Every step belongs to a [group](/editing-tests/grouping-steps.md). Positions (`atIndex`) are zero-based and counted within the group, or within an if block when you pass its `blockId`. A step added to a [component](/editing-tests/components.md) changes every test that uses it; `bugbug_update_steps` reports steps in groups shared by several tests.

Sample prompt:

{% prompt description="Propose a reliable final assertion" icon="circle-check" defaultExpanded="full" %}

```markdown
For test <test-id> in <project>, inspect the existing final steps and propose an assertion payload for <expected outcome>. Do not mutate anything until I approve the exact payload. If the outcome, selector, or test target is unclear, ask me. Return the proposed payload and why it is reliable.
```

{% endprompt %}

## Groups and components

Use these tools to work with step groups and reusable components.

| Tool                                | Description                                                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `bugbug_list_groups`                | List groups and components.                                                                                              |
| `bugbug_get_group`                  | Get details of a group or component.                                                                                     |
| `bugbug_create_groups`              | Create one or more groups or reusable components.                                                                        |
| `bugbug_update_group`               | Partially update a group or component.                                                                                   |
| `bugbug_make_component_from_group`  | Make a regular group a reusable component (UI: Make component).                                                          |
| `bugbug_detach_component_from_test` | Replace one component occurrence with a copy of its steps (UI: Unlink). Requires `testId`; the reusable component stays. |
| `bugbug_insert_group_in_test`       | Insert a group into a test.                                                                                              |
| `bugbug_delete_group`               | Delete a group or component. Deleting a component removes it and its steps from every test that uses it.                 |
| `bugbug_list_components`            | List reusable components.                                                                                                |
| `bugbug_get_component_usage`        | Show where a component is used.                                                                                          |
| `bugbug_insert_component_into_test` | Link a reusable component into a test.                                                                                   |
| `bugbug_remove_component_from_test` | Remove a component and its steps from one test; the reusable component stays.                                            |

Sample prompt:

{% prompt description="Find reusable component opportunities" defaultExpanded="full" %}

```markdown
In <project>, inspect the named tests or suites for repeated login steps and component usage. This is read-only. If the scope is not specified, ask me which tests to inspect. Return affected tests, the evidence for duplication, and a recommended component boundary; do not refactor.
```

{% endprompt %}

## Folders

Use these tools to organize tests and reusable components into folders. Each folder holds only tests or only components, and folders can be nested up to 5 levels. Creating and renaming folders requires a paid plan (Core and higher).

| Tool                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `bugbug_list_folders`   | List the folder tree for tests or components.                   |
| `bugbug_create_folder`  | Create a folder at the root or inside a parent folder.          |
| `bugbug_update_folder`  | Rename a folder or move it to another parent.                   |
| `bugbug_delete_folder`  | Delete a folder. With `force`, also deletes its contents.       |
| `bugbug_move_to_folder` | Move up to 25 tests or components into a folder or to the root. |

## Debugging

Use these tools when diagnosing failed runs, broken selectors, or DOM-related problems.

| Tool                                 | Description                                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `bugbug_query_dom_snapshot_element`  | Query a DOM snapshot by CSS selector or XPath.                                                |
| `bugbug_get_failed_step_run_details` | Get details of a failed step run.                                                             |
| `bugbug_query_console_logs`          | Query the console output of a test run (needs run logs enabled in the project settings).      |
| `bugbug_query_network_requests`      | Query the network requests of a test run, with credentials redacted (needs run logs enabled). |

Sample prompt:

{% prompt description="Diagnose a failed step with run evidence" icon="bug" defaultExpanded="full" %}

```markdown
For <project>, diagnose failed run <run-id>, focusing on failed step <step-run-id> when provided. This is read-only: inspect failed-step details, screenshots, logs, and DOM evidence before reaching a conclusion. If the run or step ID is missing, ask me for it. Return the failure category, evidence, and smallest proposed fix; do not update the test.
```

{% endprompt %}

## Visual regression

Use these tools to inspect visual regression reference screenshots and resolve visual review results.

| Tool                                                   | Description                                      |
| ------------------------------------------------------ | ------------------------------------------------ |
| `bugbug_list_visual_regression_reference_screenshots`  | List reference screenshots for a step.           |
| `bugbug_resolve_visual_regression_review`              | Accept or reject a visual regression difference. |
| `bugbug_delete_visual_regression_reference_screenshot` | Delete a visual regression reference screenshot. |

Sample prompt:

{% prompt description="Review a visual regression difference" icon="images" defaultExpanded="full" %}

```markdown
For <project>, review visual regression failure <run-id>/<step-run-id>. Inspect the expected, observed, and diff screenshots and relevant failed-step details. Do not accept or update a baseline unless I explicitly approve it. If the target run is missing, ask me. Return the observed difference, risk assessment, and recommendation with evidence.
```

{% endprompt %}

## Tags

Use these tools to manage project tags and assign them to tests, suites and their runs. Assignments replace the direct tags of the target, and inherited tags on runs are preserved. Missing tag names are created with the default color, so use `bugbug_create_tag` first to choose a color.

| Tool                        | Description                                     |
| --------------------------- | ----------------------------------------------- |
| `bugbug_list_tags`          | List project tags with colors and usage counts. |
| `bugbug_get_tag`            | Get a tag by ID.                                |
| `bugbug_create_tag`         | Create a tag with an optional color.            |
| `bugbug_update_tag`         | Rename or recolor a tag everywhere it is used.  |
| `bugbug_delete_tag`         | Delete a tag and all its assignments.           |
| `bugbug_set_test_tags`      | Replace the direct tags of a test.              |
| `bugbug_set_test_run_tags`  | Replace the direct tags of a test run.          |
| `bugbug_set_suite_tags`     | Replace the direct tags of a suite.             |
| `bugbug_set_suite_run_tags` | Replace the direct tags of a suite run.         |

## Profiles and variables

Use these tools to inspect run profiles and manage variables used by tests.

| Tool                         | Description                                       |
| ---------------------------- | ------------------------------------------------- |
| `bugbug_list_profiles`       | List BugBug run profiles.                         |
| `bugbug_get_profile`         | Get details of a specific run profile.            |
| `bugbug_get_variables_list`  | List BugBug variables.                            |
| `bugbug_create_new_variable` | Create a new BugBug variable.                     |
| `bugbug_update_variable`     | Partially update a custom BugBug variable by key. |

Sample prompt:

{% prompt description="Inspect checkout profiles and variables" defaultExpanded="full" %}

```markdown
For <project>, inspect the profiles and variables available for checkout testing against <environment>. This is read-only. If the environment or checkout test is ambiguous, ask me. Return the matching profile, required variable keys, and any missing configuration; do not create or update variables.
```

{% endprompt %}

## Project and docs

Use these tools to select project context and answer BugBug documentation questions.

| Tool                             | Description                                                    |
| -------------------------------- | -------------------------------------------------------------- |
| `bugbug_list_projects`           | List projects accessible to the authenticated user or token.   |
| `bugbug_get_project_settings`    | Get settings for the active project.                           |
| `bugbug_upload_project_artifact` | Upload a file for use in an `upload-file` test step.           |
| `bugbug_ask_docs`                | Answer a question from BugBug documentation with source links. |

`bugbug_upload_project_artifact` takes the file name and its content encoded in Base64 (`contentBase64`). It works with the same sign-in as every other tool.

Sample prompt:

{% prompt description="Inspect project settings for cloud execution" icon="cloud" defaultExpanded="full" %}

```markdown
For <project>, identify the connected BugBug project and inspect settings that may affect cloud execution in <environment>. This is read-only. If more than one project is available or the environment is unspecified, ask me to choose. Return the selected project, relevant settings, and their likely impact with evidence; do not change settings.
```

{% endprompt %}

## Code mode

Use these tools for multi-step work. Instead of many small calls, the agent writes a short JavaScript function body that calls the typed `bugbug` API in an isolated sandbox, and only the returned value goes back to the model. This saves calls and tokens: the agent can read many tests or runs in one call and return only the fields it needs. Deletes, stopping runs, removing or detaching components, converting components to groups and resolving visual regressions are not available inside scripts. Use the dedicated tools for removing or detaching components.

| Tool                | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `bugbug_search_api` | Show an overview of the `bugbug` API or signatures matching a query. |
| `bugbug_execute`    | Run a JavaScript function body against the `bugbug` API.             |

For example, a script that returns the error codes of the five latest failed runs:

```js
const { results } = await bugbug.tests.listRuns({ status: 'failed', ordering: '-started', pageSize: 5 });
const runs = await Promise.all(results.map((run) => bugbug.tests.getRun(run.id)));
return runs.map((run) => ({ id: run.id, name: run.name, errorCode: run.errorCode }));
```

Limits for one script:

| Limit              | Value                                                                  |
| ------------------ | ---------------------------------------------------------------------- |
| `bugbug` API calls | 1000 reads and 50 changes                                              |
| Memory             | 64 MB                                                                  |
| Script CPU time    | 2 seconds                                                              |
| Total time         | 60 seconds, extended up to 15 minutes while the script waits for a run |
| Result and logs    | 100 KB each; larger output is cut                                      |

BugBug MCP sends at most 100 requests per minute to the BugBug API. Calls above that, for example many parallel reads in one script, wait up to 30 seconds for a free slot instead of failing. A script that needs more requests should be split into several scripts that pass on what they have processed.

Scripts have no network, file system, timers or credentials of their own. Scripts can modify data and start runs, so run them only with authorization for the target project and environment.

### Related docs

* [BugBug MCP](/ai-testing/mcp.md)
* [BugBug Plugin](/ai-testing/plugin.md)
* [BugBug Skills](/ai-testing/skills.md)

### FAQ

<details>

<summary>What can the BugBug MCP tools do?</summary>

BugBug MCP provides tools for working with projects, tests, suites, steps, components, profiles, variables and test runs. AI agents can inspect existing assets, create and update tests, start runs, monitor results, diagnose failures, review visual regression differences and import test definitions when authorized.

</details>

<details>

<summary>Which BugBug MCP tools are read-only, and which can change project data?</summary>

Tools beginning with actions such as `list`, `get` and `query` are generally used for read-only inspection. Tools that create, make, detach, update, patch, insert, remove, import, delete, move, tag, resolve, upload, run, execute or stop can affect project data or execution. These actions should require explicit authorization and human confirmation.

</details>

<details>

<summary>How do I run a test with a specific profile through MCP?</summary>

Call `bugbug_run_test` with `testNameOrId` and `profileName`. `profileName` accepts the profile's name or its UUID. The tool doesn't take a `runProfileId` parameter. If the name exists in several projects, pass `projectId` or use the UUID.

</details>

<details>

<summary>Can an AI agent create, edit and run BugBug tests through MCP?</summary>

Yes. An authorized agent can create tests and steps, update existing definitions, organize reusable components and start individual test or suite runs. The agent should first inspect the relevant project context and existing assets, then confirm the requested scope before making changes or starting execution.

</details>

<details>

<summary>How can an AI agent diagnose a failed test with BugBug MCP tools?</summary>

The agent can inspect the test run, retrieve details of the failed step and query the captured DOM snapshot. It can also use available screenshots, console logs, network logs and error details to classify the failure. It should return the supporting evidence and propose the smallest fix before changing the test.

</details>

<details>

<summary>Can an AI agent review visual regression failures through BugBug MCP?</summary>

Yes. BugBug MCP tools can access visual regression reference screenshots and help evaluate observed differences. The agent can describe what changed, estimate whether it is a product regression and recommend an action. It should not accept, reject or delete reference screenshots without explicit human approval.

</details>

<details>

<summary>Can BugBug MCP import tests from YAML or ZIP files?</summary>

Yes. The `bugbug_import_test` tool can import a BugBug test from YAML or ZIP. Before importing, the agent should validate the definition, variables, selectors, components and secret handling, then report any problems or risks and wait for authorization.

</details>

<details>

<summary>What are the rate limits of BugBug MCP?</summary>

BugBug MCP sends at most 100 requests per minute to the BugBug API; calls over that wait up to 30 seconds before they fail. The API itself allows 5 requests per second per token, see [Public API limits](/integrations/public-api.md#limits). Code mode scripts have their own limits on the number of calls, see [Code mode](#code-mode).

</details>

<details>

<summary>What is code mode, and why does it use fewer tokens?</summary>

In code mode the agent sends one short script to `bugbug_execute` instead of calling many tools one by one. The script runs on the BugBug MCP server and only its return value goes back to the model, so intermediate results don't fill the conversation.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/ai-testing/mcp/mcp-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.