> 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 50 tools that let AI assistants work with BugBug projects through the Model Context Protocol.

{% 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.

## 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_run_test`             | Start a test run by test name or ID.           |

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.                       |

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 detailed results of a suite 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.                           |

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.                                |

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_convert_group_to_component` | Convert a regular group into a reusable component.    |
| `bugbug_convert_component_to_group` | Convert a reusable component back to a regular group. |
| `bugbug_insert_group_in_test`       | Insert a group into a test.                           |
| `bugbug_delete_group`               | Delete a group by ID.                                 |
| `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_unlink_component_from_test` | Remove a linked component from a test.                |

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 %}

## 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.              |

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 %}

## 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. |

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 %}

### 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, update, patch, insert, unlink, import, delete, resolve, upload, run or stop can affect project data or execution. These actions should require explicit authorization and human confirmation.

</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>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.