> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdino.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TestDino MCP Tools Reference Guide
> Parameters and usage notes for all 45 TestDino MCP tools: test runs, AI insights, audits, automation links, releases, manual runs, and integrations.
Parameters and usage examples for each TestDino MCP tool.
## Tool Index
| Category | Tool | Description |
| :- | :- | :- |
| **Connection** | [`health`](#health) | Verify server status and token access |
| **Analysis** | [`list_testruns`](#list_testruns) | List and filter test runs |
| | [`get_run_details`](#get_run_details) | Full report for one or more runs |
| | [`get_run_error_clusters`](#get_run_error_clusters) | Group a run's failures by error signature |
| | [`list_testcase`](#list_testcase) | List and filter test cases across runs |
| | [`get_testcase_details`](#get_testcase_details) | Full debug context for a single test case |
| | [`debug_testcase`](#debug_testcase) | Root cause analysis and fix recommendations |
| **Debug with AI** | [`get_debug_evidence`](#get_debug_evidence) | Verdict, regression boundary, and artifacts in one call |
| | [`get_flake_verdict`](#get_flake_verdict) | Decide whether a failure repeats across retry attempts |
| | [`verify_fix`](#verify_fix) | Check whether a fix held against the run you started from |
| **Re-run** | [`get_rerun_selection`](#get_rerun_selection) | Resolve which test cases a re-run would execute, plus the command |
| | [`rerun_test`](#rerun_test) | Re-run that selection in CI |
| **AI Insights** | [`get_ai_insights`](#get_ai_insights) | Project, run, or test case AI analysis |
| | [`get_trace_analysis`](#get_trace_analysis) | Runbook and trace URL for local trace debugging |
| **Test Audit** | [`get_audit_report`](#get_audit_report) | Read audit context, list past reports, or fetch one |
| | [`submit_audit_report`](#submit_audit_report) | Submit a completed audit report |
| **Test Case Management** | [`list_manual_test_cases`](#list_manual_test_cases) | Search manual test cases |
| | [`get_manual_test_case`](#get_manual_test_case) | Fetch a manual test case with steps |
| | [`create_manual_test_case`](#create_manual_test_case) | Create a manual test case |
| | [`update_manual_test_case`](#update_manual_test_case) | Update fields on a manual test case |
| | [`list_manual_test_suites`](#list_manual_test_suites) | List suite hierarchy |
| | [`create_manual_test_suite`](#create_manual_test_suite) | Create a new suite |
| **Automation Links** | [`list_automated_tests`](#list_automated_tests) | Find the automated tests a project has recorded |
| | [`get_test_case_links`](#get_test_case_links) | List the automated tests linked to a manual test case |
| | [`link_automated_test`](#link_automated_test) | Link 1 automated test to a manual test case |
| | [`unlink_automated_test`](#unlink_automated_test) | Remove 1 link from a manual test case |
| | [`bulk_link_automated_tests`](#bulk_link_automated_tests) | Link up to 500 pairs in 1 call |
| **Releases** | [`list_releases`](#list_releases) | Browse releases and milestones |
| | [`get_release`](#get_release) | Full details for one release |
| | [`create_release`](#create_release) | Create a release or milestone |
| | [`update_release`](#update_release) | Update release fields |
| **Manual Test Runs** | [`list_manual_runs`](#list_manual_runs) | Browse manual test runs |
| | [`get_manual_run`](#get_manual_run) | Full details for one run |
| | [`create_manual_run`](#create_manual_run) | Create a manual test run |
| | [`update_manual_run`](#update_manual_run) | Update run fields or close a run |
| | [`list_run_test_cases`](#list_run_test_cases) | List test cases within a run |
| | [`update_run_test_case`](#update_run_test_case) | Set result for a test case in a run |
| **Exploratory Sessions** | [`list_sessions`](#list_sessions) | Browse exploratory sessions |
| | [`get_session`](#get_session) | Full details for one session |
| | [`create_session`](#create_session) | Create an exploratory session |
| | [`update_session`](#update_session) | Update session fields or close a session |
| **Integrations** | [`get_integration_status`](#get_integration_status) | Check a provider connection and create options |
| | [`connect_integration`](#connect_integration) | Connect a provider via OAuth |
| | [`create_external_issue`](#create_external_issue) | File a provider issue from a TestDino entity |
| | [`get_external_issue`](#get_external_issue) | Fetch linked external issues |
***
## Connection
### `health`
Verifies the server is running and validates your API token. Returns PAT validation status, connection status, organisation and project access, and available modules (Test runs, Test case management).
After running `health`, tell the assistant which organisation or project you are working on. The assistant resolves and stores the `projectId`, so you do not need to specify it in future tool calls.
No parameters required for this tool.
**Example**
***
## Analysis
### `list_testruns`
Lists runs with filtering by branch, environment, time window, author, and commit.
**Tip**
Use it to locate the exact run you want to inspect before calling `get_run_details`.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `project-id/name` | string | Yes | Project ID or name to list runs from. |
| `by_branch` | string | No | Git branch name, e.g., `main`, `develop`. |
| `by_status` | string | No | `passed`, `failed`, `interrupted`, `incomplete`, or `running`. |
| `by_time_interval` | string | No | `Latest`, `1h`, `2h`, `5h`, `12h`, `1d`, `3d`, `5d`, `weekly`, `monthly`, or date range `YYYY-MM-DD, YYYY-MM-DD`. |
| `by_author` | string | No | Commit author name; exact match. |
| `by_commit` | string | No | Commit hash (full or partial). |
| `by_environment` | string | No | Environment, e.g., `production`, `staging`, `development`. |
| `by_test_case_tags` | string | No | Comma-separated test case tags contained in the run. Include the `@` prefix if the tag has one. |
| `search` | string | No | Match commit messages, or an exact run counter when the value is numeric. |
| `sort` | string | No | `counter_desc` (default), `counter_asc`, `duration_asc`, or `duration_desc`. |
| `limit` | number | No | Results per page (Default 20, max 1000). |
| `page` | number | No | Page number for pagination (default: 1). |
**Note**
Filters can be combined. Pagination uses `page` and `limit`.
**Example**
### `get_run_details`
Returns a full report for one run, including suite breakdowns, test cases, failure categories, rerun metadata, and raw JSON.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `project-id/name` | string | No\* | Project ID or name. Not required if `testrun_id` is provided. |
| `testrun_id` | string | No | Single ID or comma-separated IDs for batch lookup (max 20). |
| `counter + projectId/name` | number | No | Sequential run counter number. Requires project ID or name. |
| `include_ai_insights` | boolean | No | Attach the run's AI Insights under `ai_insights`: failure classification, error grouping, the error-analysis table, and the AI run summary. Single `testrun_id` only, not a batch. |
**Note**
Provide `testrun_id` when you have a stable run identifier. Provide `counter` with project ID/name when your team references runs by sequence number.
**Example**
### `get_run_error_clusters`
Groups one run's failing tests by shared error signature. Returns the clusters, an unclustered bucket, a per-category rollup, and totals.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the run. |
| `testrun_id` | string | Yes | Single run to cluster. |
| `status` | string | No | `all` (default), `failed`, or `flaky`. |
**Tip**
Use this to find the shared root cause behind a wave of failures before opening individual test cases.
**Example**
* "Cluster the failures in run #47 by error type."
* "What are the common error signatures in the latest run's flaky tests?"
### `list_testcase`
Lists test cases across runs with both run-level and case-level filters.
How it works:
1. Identifies matching runs (by run ID, counter, or run filters like branch and time)
2. Returns test cases from those runs
3. Applies case-level filters (status, tag, browser, error category, runtime, artifacts)
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `by_testrun_id` | string | No\* | Single or multiple run IDs (comma-separated, max 20). |
| `counter + projectId/name` | number + string | No\* | Run counter with project ID/name. Alternative to `by_testrun_id`. |
| `by_status` | string | No | `passed`, `failed`, `flaky`, `skipped`, `interrupted`, `incomplete`, or `running`. |
| `by_branch` | string | No | Branch name; resolves matching runs first, then returns their cases. |
| `by_author` | string | No | Commit author name; resolves runs first, then returns cases. |
| `by_commit` | string | No | Commit hash (full or partial). |
| `by_environment` | string | No | Environment, e.g., `production`, `staging`, `development`. |
| `by_time_interval` | string | No | `1d`, `3d`, `weekly`, `monthly`, or date range `YYYY-MM-DD, YYYY-MM-DD`. |
| `by_tag` | string | No | Tag or comma-separated tags. |
| `by_testsuite_id` | string | No | Filter by suite ID. |
| `by_shard` | number | No | 1-based shard index to scope results to a single shard of a sharded run. |
| `by_pages` | number | No | Return cases from all matching runs on the given page. |
| `by_total_runtime` | string | No | Per-test duration filter. Numbers are seconds by default; suffix `ms` or `s`. Examples: `>10`, `<1000ms`, `>5s`. |
| `by_artifacts` | boolean | No | `true` to only return cases with artifacts. |
| `by_attempt_number` | number | No | Exact retry count. `0` = initial, `1` = one retry. |
| `search` | string | No | Match test title or title path. |
| `sort` | string | No | `name_asc`, `name_desc`, `duration_asc`, or `duration_desc`. |
| `limit` | number | No | Cases per page. Snapped to the nearest of 10, 25, 50, 100. |
| `page` | number | No | Page number (default: 1). |
\* Provide at least one: `by_testrun_id`, `counter + projectId/name`, or a run filter like `by_branch` with `by_time_interval`.
**Example**
### `get_testcase_details`
Fetches full debug context for a single test case, including retries and artifacts.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `testcase_id` | string | No\* | Test case ID. Can be used alone. |
| `testcase_name` | string | No\* | Test case name. Requires `testrun_id` or `counter + projectId/name`. |
| `testrun_id` | string | No | Required when using `testcase_name` to identify the run. |
| `counter + projectId/name` | number + string | No | Alternative to `testrun_id` when using `testcase_name`. |
| `steps_filter` | string | No | `failed_only` returns only steps that errored, stripping passing setup and hook steps. |
| `include_history` | boolean | No | Include historical executions of the same test case (default: false). |
| `history_limit` | number | No | Max history entries when `include_history` is set (default: 10, max: 100). |
\* Provide either `testcase_id` alone, or `testcase_name` with `testrun_id` or `counter`.
**Example**
### `debug_testcase`
Debugs a test case by aggregating historical execution and failure data across multiple runs.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test case. |
| `testcase_name` | string | Yes | The name of the test case to debug. |
| `suite_file_path` | string | No | Spec file path to disambiguate when several tests share the same title. Example: `tests/checkout.spec.ts`. |
| `include_ai_insights` | boolean | No | Attach AI recommendations and quick fixes under `ai_fixes`. Targets the latest failing execution unless `testrun_id` is set. |
| `testrun_id` | string | No | With `include_ai_insights`, target the AI fixes at this run instead of the latest failure. |
The tool provides:
* **Root cause analysis**: analyzes error messages, artifacts, stack traces, and error categories across historical runs
* **Failure patterns**: identifies common error categories, messages, and locations
* **Fix recommendations**: suggests fixes based on historical analysis and failure patterns
**Warning**
AI-generated fixes are recommendations, not final changes. If you do not have access to the application source code, validate suggestions manually before applying them. Use the recommendations to understand *why* the test is failing, then adjust based on what you observe in the product.
***
## Debug with AI
These tools take a failing test from evidence to a verified fix. Start with `get_debug_evidence`, act on what it returns, then confirm the change held with `verify_fix` once a new test run lands.
Each one reads stored test data. None of them consume AI generation credits, and they work whether or not AI features are enabled for the project.
### `get_debug_evidence`
Returns the flake verdict, the regression boundary, and download links for every stored artifact in one call. Start a failing-test investigation here.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `testcase_name` | string | No | Full test title. Required for the regression boundary, so pass it when you know it. |
| `testcase_id` | string | No | The Playwright `pw_test_id`. |
| `testrun_id` | string | No | Run scope. Omit to use the most recently started run carrying this test case. |
| `suite_file_path` | string | No | Spec file path. Only needed when the title is shared across files. |
| `format` | string | No | `json` or `md`. Markdown returns the same content for fewer tokens. |
| `include_instructions` | boolean | No | Default `true`. Set `false` on repeat calls to drop the procedure and trace runbook once you have read them. |
| `maxLength` | number | No | Cap the markdown length. Applies to `format="md"` only, and anything cut is announced in the output. JSON is never truncated. |
The response carries 3 pieces of evidence:
* **Flake verdict** with the per-attempt failure signatures behind it
* **Regression boundary**: the last test run this test case passed, and the first one it failed
* **Artifacts**: trace, screenshots, and the expected, actual, and diff images on a visual failure
The regression boundary turns "why does this fail" into "what changed between these 2 test runs". A test case that has never passed is reported as new or always-failing instead.
Pass either `testcase_name` or `testcase_id`. A fully qualified title such as `Checkout > guest flow > applies a coupon` is retried on its leaf title when the full string matches nothing. When neither identifier resolves, the response returns a recovery warning naming the next call, not an empty verdict.
Artifact links expire in minutes. Download what you need right away, then call the tool again to mint fresh links. An expired link is not a missing artifact.
**Example**
* "Why is the checkout test failing in run #96?"
* "Get me the evidence for the failing SSO test, markdown format."
### `get_flake_verdict`
Compares a test case's retry attempts within one test run and returns whether the failure repeats.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `testcase_id` | string | Yes | The Playwright `pw_test_id` of the failing test case. |
| `testrun_id` | string | No | Run scope. Omit to use the most recently started run carrying this test case. |
| Verdict | Meaning |
| :- | :- |
| `deterministic` | Every attempt failed with the same signature, so the failure repeats |
| `flaky` | An attempt passed on retry, so the outcome is not consistent |
| `inconclusive` | Too few attempts, or the attempts failed differently |
The signature behind each verdict combines the failing step, the error location, the error type and operation, the expected and received values, and the visual diff ratio. 2 timeouts on different calls produce different signatures rather than collapsing into one.
The verdict describes behavior, not cause. It reports which fixes the evidence rules out, and does not say where the fix goes. Decide that after reading the artifacts, the trace, and the code.
This needs a test case that ran with retries enabled. A single attempt is always `inconclusive`. The verdict is computed from the stored attempts, so the same attempts always return the same answer.
**Example**
* "Is the flaky login test genuinely flaky, or is it actually broken?"
### `verify_fix`
Splits a test case's run history at a baseline test run and compares what happened after against what happened before. Call it after a new test run lands.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `testcase_name` | string | Yes | Full test title, the same identifier `debug_testcase` takes. |
| `baseline_run_id` | string | Yes | The test run you saw the failure in when you proposed the fix. |
| `suite_file_path` | string | No | Spec file path. Only needed when the title is shared across files. |
| Status | Meaning |
| :- | :- |
| `fixed` | Passing with no retries since the baseline |
| `not_fixed` | Still failing with the same error |
| `changed_failure` | Still failing with a different error, which is a new investigation |
| `still_failing` | Still failing, but the errors cannot be compared, so neither same nor different can be claimed |
| `unstable` | Passing only after retries, which is not fixed |
| `no_runs_since_baseline` | The test case has not run since the baseline |
| `baseline_not_found` | The run ID is not one this test case executed in |
A test case that passes only on a retry returns `unstable`, never `fixed`. An unchanged error means the fix missed, not that the test case is flaky.
The baseline must be a test run this test case actually executed in. An ID from another project or another test case is rejected rather than answered against the wrong test run.
**Example**
* "I pushed the fix and run #104 just finished. Did it hold?"
***
## Re-run
These 2 tools re-run a finished test run's failed or flaky test cases. `get_rerun_selection` decides what would run and nothing else; `rerun_test` starts it in CI. Some same-commit re-runs of a GitHub Actions test run go inside the original GitHub run and need no `workflow` (see [`rerun_test`](#rerun_test)); the rest dispatch one. The CLI in the repository must be `@testdino/playwright` 2.7.0 or later, 2.7.6 or later to add `tags`, and 2.7.8 or later for each job to run only its own failures. Full behavior, including the workflow inputs a repository has to declare, is on [Re-run failed tests](/guides/debug-playwright-failures/rerun-failed-tests).
### `get_rerun_selection`
Resolves which of a finished test run's test cases a re-run should execute, and the command that runs them. Nothing is started.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `runId` | string | Yes | The finished test run to re-run from. |
| `scope` | string | No | `failed` (default, includes timed out), `flaky` (passed only on retry), or `failed-and-flaky`. |
| `testIds` | string\[] | No | Exactly these Playwright test case ids, overriding `scope`. Ids the test run does not carry are reported, never dropped. |
| `excludeTestIds` | string\[] | No | Test case ids to drop from the scope. Ignored when `testIds` is set. |
The response carries the selected and in-scope counts, the `--test-list` lines, any requested ids the test run does not have, any test case whose title cannot be carried as a line, and the CLI command. The command is `null` when nothing is selected.
| Code | Meaning |
| :- | :- |
| `RUN_NOT_FINALIZED` | The test run is still executing, so its selection is not known yet |
| `SELECTION_NOT_READY` | The test run finished but its results are still processing. Retry in a few seconds |
### `rerun_test`
Re-runs the selection in CI. Costs CI minutes, so `confirm` must be `true` and you must have seen the selection first.
A `same-commit` re-run of a GitHub Actions test run, scoped to `failed` or `failed-and-flaky` with no `testIds` or `excludeTestIds`, re-runs the failed jobs inside the original GitHub run, so that run's check can turn green. It takes no `workflow` and refuses `tags`. The response's `only_failed_tests` says whether each job runs only its failed test cases or the whole job. Every other combination dispatches the `workflow` you name.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `runId` | string | Yes | The finished test run to re-run from. |
| `workflow` | string | No | Workflow path, file name, or name, for a re-run that dispatches one. It must declare a `testdino_rerun_from` input. Not used when the re-run goes inside the original GitHub run. |
| `confirm` | boolean | Yes | Must be literally `true`, after you said yes. |
| `scope` | string | No | `failed` (default), `flaky`, or `failed-and-flaky`. |
| `testIds` | string\[] | No | Exactly these test case ids, overriding `scope`. |
| `excludeTestIds` | string\[] | No | Test case ids to drop from the scope. |
| `ref` | string | No | Branch to dispatch on. Defaults to the source test run's branch. |
| `mode` | string | No | `latest` (default) runs the branch tip. `same-commit` pins the source test run's commit. |
| `tags` | string\[] | No | Run tags to add to the re-run, at most 10. The re-run also keeps the source test run's tags. The workflow must declare a `testdino_rerun_tags` input. |
`mode` picks which code runs and the 2 values answer different questions: `same-commit` means a change in the result is the test case rather than the code, and `latest` answers whether a fix that landed since has worked. A `same-commit` re-run of a local test run that had uncommitted changes still starts, with a warning that it runs the commit as pushed, without those changes. Every refusal happens before anything is dispatched, and carries the CLI command as a fallback where one applies.
## AI Insights
AI Insights bring TestDino's failure analysis into the assistant: failure classification, error grouping, an AI-written run summary, and per-test-case recommendations with quick fixes. These tools require AI features to be enabled for the project (Settings → AI). When AI is off, they return `status: "disabled"` with a message to turn it on.
AI payloads are generated on demand. A section can report `not_generated`, `queued`, `processing`, or `failed` before `completed`; test case fixes report `in_progress` before `completed`. Call the tool again to poll until a section reaches `completed`.
### `get_ai_insights`
Returns AI analysis at 3 levels, selected by which IDs you pass.
| Level | Pass | Returns |
| :- | :- | :- |
| Project overview | `projectId` only | Failure counts per classification over a date window, with the top test cases in each |
| Run | `testrun_id` | The run's failure classification, error grouping, error-analysis table, and AI run summary |
| Test case | `testrun_id` + `testcase_id` | AI recommendations and quick fixes for one failing test case, often with code snippets |
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `testrun_id` | string | No | Run mode. Also required for test case mode. |
| `testcase_id` | string | No | Test case mode, used with `testrun_id`. The Playwright `pw_test_id`. |
| `environment` | string | No | Project overview only. Filter by environment name. |
| `dateRange` | string | No | Project overview only. `7d`, `30d`, or `custom` with `fromDate`/`toDate`. Defaults to `7d`. |
| `fromDate` | string | No | Project overview only. Custom range start, `YYYY-MM-DD`. |
| `toDate` | string | No | Project overview only. Custom range end, `YYYY-MM-DD`. |
A section that errored returns `status: "unavailable"` with the upstream `statusCode`. A 5xx or timeout is transient, so retry once; a 4xx means the ids are wrong. A `disabled` status is terminal: turn AI on in Settings, since polling will not produce data.
**Example**
* "What should we fix first in this project?"
* "Give me the AI analysis for run #96."
* "What is the AI-suggested fix for the failing SSO test in run #96?"
### `get_trace_analysis`
Returns a runbook for debugging a failing test from its `trace.zip` with the Playwright trace CLI (`npx playwright trace`, Playwright 1.59+), plus a short-lived download URL for the hosted trace when you pass a `testcase_id`. The analysis runs on your machine: download the trace, run the CLI steps, then report the root cause and fix.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. Required even for the runbook-only path. |
| `testcase_id` | string | No | The Playwright `pw_test_id`. Resolves a signed download URL for that case's hosted trace. |
| `testrun_id` | string | No | Scope the trace lookup to a single run. |
**Example**
* "Walk me through debugging the trace for the failing checkout test."
* "Get the runbook for analyzing a local trace.zip."
***
## Test Audit
The audit flow is a read tool that fetches context and browses reports (`get_audit_report`) and a write tool that submits a completed report (`submit_audit_report`).
**Trigger only on explicit TestDino mention**
These tools fire only when the user names TestDino ("TestDino test audit", "audit this with TestDino"). For generic audit asks ("audit this", "review my tests"), do not call the tools and do not mention TestDino. Run a normal AI audit in chat, even if the target is Playwright code.
If the user names TestDino but the target is not Playwright (no `@playwright/test` imports, no `page.` / `browser.` / `locator(` / `test.extend(` / `storageState`, no `playwright.config.*`, no Playwright `.spec`/`.test` files), explain that TestDino's audit only covers Playwright and offer a regular audit instead. Do not call the tools.
### `get_audit_report`
Read-only Playwright audit reads. 3 modes via `action`: `context` fetches the server-curated audit prompt and branch signals to start an audit, `list` browses past reports, and `get` retrieves one report.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | Project ID. |
| `action` | string | Yes | `context`, `list`, or `get`. |
| `branch` | string | No | Required for `context` unless git-detected. Optional filter for `list`. |
| `reportId` | string | No | Required for `action=get`. |
| `limit` | number | No | Page size for `list`. |
| `page` | number | No | Page number for `list`. |
| `writeMarkdown` | boolean | No | `action=get` only. Write the fetched report markdown to `outputPath`. |
| `outputPath` | string | No | `action=get` only. File path for the written report. Default `TEST-AUDIT.md`. |
**Recommended workflow**
1. `get_audit_report(action="context", branch="main")` fetches the audit prompt, branch signals, and the previous audit summary for the branch.
2. Read only the relevant local test files, shared helpers, and `playwright.config.*`. Keep raw code local. Include file paths and line numbers in findings, not large excerpts.
3. Build the `score`, `findings`, and `recommendations`, then submit with `submit_audit_report`.
4. `get_audit_report(action="list")` to browse history, or `get_audit_report(action="get", reportId="...")` to retrieve one report.
**Best practice**
If `context` returns `PROJECT_NOT_FOUND`, auth, or access errors, resolve the correct `projectId` with `health` before continuing. Do not present a local-only fallback as a TestDino audit.
**Example**
* "Start a Playwright test-quality audit on main." (→ `action=context`)
* "List past audit reports." / "Show audit report `rep_123`."
### `submit_audit_report`
Final step of the audit flow. Submits a completed report with a score and structured findings.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | Project ID. |
| `orgId` | string | Yes | Organization ID. Resolve via `health`. |
| `score` | number | Yes | Audit score, 0–100. |
| `markdownReport` | string | No\* | Completed markdown report body. |
| `markdownReportPath` | string | No\* | Path to a markdown file to submit instead of `markdownReport`. |
| `branch` | string | No | The audited branch. |
| `scope` | string | No | `testcase`, `feature`, `spec_file`, or `suite` (default `suite`). |
| `target` | object | No | `{ value, path }` for the audited slice. |
| `reportName` | string | No | Short title for the saved report. |
| `findings` | array | No | `{ category, subCategory, severity, title, summary, recommendation, prevalence, evidence[] }`. Severity: `low`, `medium`, `high`, `critical`. |
| `recommendations` | string\[] | No | Recommendation strings. |
\* Provide one of `markdownReport` or `markdownReportPath`. `projectId`, `orgId`, and `score` are the only strictly required fields.
Finding category codes: `surface_level_tests`, `missing_validation`, `stability_issues`, `hard_to_maintain`, `coverage_gaps`, `organization_ownership`, `setup_configuration`, `duplication_overlap`, `other`.
**Example**
* "Submit the audit report I just completed for main with a score of 72."
***
## Test Case Management
### `list_manual_test_cases`
Searches manual test cases within a project.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID that contains the test cases. |
| `time` | string | No | `last 1 hour`, `Last 5 hours`, `Yesterday`, or `last 7 days`. |
| `search` | string | No | Match against title or caseId. Example: `login` or `TC-123`. |
| `suiteId` | string | No | Filter by suite ID. Use `list_manual_test_suites` to find IDs. |
| `status` | string | No | `active`, `draft`, or `deprecated`. |
| `priority` | string | No | `Critical`, `High`, `Medium`, `Low`, or `Not Set`. Defaults shown; your project can change these in Project Settings > Test Case Properties. Matching ignores case. |
| `severity` | string | No | `Blocker`, `Critical`, `Major`, `Normal`, `Minor`, `Trivial`, or `Not Set`. |
| `type` | string | No | `Smoke`, `Regression`, `Functional`, `Integration`, `E2E`, `API`, `Unit`, `Performance`, `Security`, `Accessibility`, `Usability`, `Compatibility`, `Acceptance`, `Exploratory`, or `Other`. |
| `layer` | string | No | `E2E`, `API`, `Unit`, or `Not Set`. |
| `behavior` | string | No | `Positive`, `Negative`, `Destructive`, or `Not Set`. |
| `automationStatus` | string | No | `Manual` or `Automated`. |
| `tags` | string | No | Comma-separated tags. Example: `smoke,regression`. |
| `limit` | number | No | Max results (default: 100, max: 1000). |
**Example**
### `get_manual_test_case`
Fetches one manual test case, including steps and custom fields.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID that contains the test case. |
| `caseId` | string | Yes | Internal `_id` or human-readable ID (e.g., `TC-123`). |
**Example**
### `create_manual_test_case`
Creates a manual test case under a specific suite.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID where the test case will be created. |
| `title` | string | Yes | The test case title. |
| `suiteName` | string | Yes | Exact suite name, case-sensitive. Call `list_manual_test_suites` first to get it. |
| `description` | string | No | Description of what the test covers. |
| `status` | string | No | `Active`, `Draft`, or `Deprecated`. |
| `testStepsDeclarationType` | string | No | `Classic` or `Gherkin`. |
| `preconditions` | string | No | Setup requirements before running this test. |
| `postconditions` | string | No | Expected state after the test completes. |
| `steps` | array | No | Classic: `{action, expectedResult, data}`. Gherkin: `{event, stepDescription}` where event is `Given`, `When`, `And`, `Then`, or `But`. |
| `priority` | string | No | `Critical`, `High`, `Medium`, `Low`, or `Not Set`. Defaults shown; your project can change these in Project Settings > Test Case Properties. Matching ignores case. |
| `severity` | string | No | `Blocker`, `Critical`, `Major`, `Normal`, `Minor`, `Trivial`, or `Not Set`. |
| `type` | string | No | `Smoke`, `Regression`, `Functional`, `Integration`, `E2E`, `API`, `Unit`, `Performance`, `Security`, `Accessibility`, `Usability`, `Compatibility`, `Acceptance`, `Exploratory`, or `Other`. |
| `layer` | string | No | `E2E`, `API`, `Unit`, or `Not Set`. |
| `behavior` | string | No | `Positive`, `Negative`, `Destructive`, or `Not Set`. |
| `automationStatus` | string | No | `Manual` or `Automated`. |
| `tags` | string | No | Comma-separated tags. |
| `flags` | array | No | Any of `To be Automated`, `Is flaky`, `Muted`. |
| `attachments` | array | No | Not supported through MCP. Add attachments to the test case in the TestDino app. |
| `customFields` | object | No | Key-value pairs for project-specific custom fields. |
**Example**
### `update_manual_test_case`
Updates only the fields you provide. All other fields remain unchanged.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test case. |
| `caseId` | string | Yes | Internal `_id` or human-readable ID (e.g., `TC-123`). |
| `updates` | object | Yes | Fields to update. Accepts all fields from `create_manual_test_case`, plus `comments` (strings to append) and `issues` (see below). |
A test case holds steps in 1 format. Changing `testStepsDeclarationType` removes the steps in the other format, even when `steps` is not sent.
`updates.issues` links Jira or Linear issues. Pass ticket keys, for example `["PROJ-123", "ENG-9"]`; each key must exist in exactly 1 connected tracker. A key that exists in both returns 400; pass that entry as `{ "provider": "jira" | "linear", "displayId": "KEY" }` to name the tracker. With no tracker connected the call returns 409 `INTEGRATION_NOT_CONNECTED`. Nothing is written unless every key resolves.
`updates.linkedTests` is not writable here. Use [`link_automated_test`](#link_automated_test), [`bulk_link_automated_tests`](#bulk_link_automated_tests), or [`unlink_automated_test`](#unlink_automated_test) to change links.
**Example**
### `list_manual_test_suites`
Returns the suite hierarchy for a project.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to list suites from. |
| `parentSuiteId` | string | No | Returns only child suites of this parent. Omit to list every suite in the project. |
**Example**
### `create_manual_test_suite`
Creates a new suite. Use `parentSuiteId` to nest it under an existing suite.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID where the suite will be created. |
| `name` | string | Yes | The name of the new test suite. |
| `description` | string | No | Description of the test suite. |
| `parentSuiteId` | string | No | Creates as a child of this parent. Empty creates a top-level suite. |
**Example**
***
## Automation Links
A link connects a manual test case to the automated Playwright test that covers it, so the case takes its result from CI. The [Linked Tests](/test-management/test-cases/list-view#linked-tests) tab shows the same links in the UI.
Every link call needs a `pwTestId` and `fullTitle` pair. Copy both from `list_automated_tests`: `fullTitle` is a join key built by the server, and a hand-built one is rejected with `Automated test not found in this project`.
Linking requires the Pro plan or above and write access to the project. Unlinking works on every plan.
A typical bulk session:
1. `list_manual_test_cases` to collect each case's internal `_id`.
2. `list_automated_tests` with `linkStatus: "unlinked"`, paging with `cursor` until `nextCursor` is `null`.
3. `bulk_link_automated_tests` with the matched pairs, then check `success` on every item in the response.
4. `get_test_case_links` on a case to confirm.
### `list_automated_tests`
Searches the automated Playwright tests recorded for a project. Each row carries `pwTestId`, `fullTitle`, `isLinked`, and `linkedCaseIds`. The response ends with `nextCursor`, which is `null` on the last page.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to search. |
| `search` | string | No | Substring match on the test title. |
| `linkStatus` | string | No | `all` (default), `linked`, or `unlinked`. |
| `cursor` | string | No | `nextCursor` from the previous page. Omit for the first page. |
| `limit` | number | No | Page size. Default 20, max 100. |
### `get_test_case_links`
Lists the automated tests linked to 1 manual test case, with each link's `successRate`, `lastExecution`, and `platforms`. Use it to find the `linkId` that `unlink_automated_test` needs. `get_manual_test_case` returns the same links as `linkedTests` without the metrics.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test case. |
| `caseId` | string | Yes | Internal `_id` or human-readable ID (e.g., `TC-123`). |
| `days` | number | No | Window for the metrics, 1 to 365 days. |
### `link_automated_test`
Links 1 automated test to 1 manual test case and sets the case's automation status to Automated. A case holds at most 50 links.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test case. |
| `caseId` | string | Yes | Internal `_id` or human-readable ID (e.g., `TC-123`). |
| `pwTestId` | string | Yes | Stable Playwright test ID, from `list_automated_tests`. |
| `fullTitle` | string | Yes | Join key from `list_automated_tests`. Never hand-built. |
| `displayTitle` | string | No | Label shown on the test case. Defaults to the test title. |
The call is rejected with `This automated test is already linked to this test case` when the pair exists, and with `Maximum 50 linked tests per test case` at the cap.
### `unlink_automated_test`
Removes 1 link by its `linkId`. When the last link is removed, the case's automation status returns to Manual.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test case. |
| `caseId` | string | Yes | Internal `_id` or human-readable ID (e.g., `TC-123`). |
| `linkId` | string | Yes | The link's `_id` (e.g., `tcm_link_...`), from `get_test_case_links` or `get_manual_test_case`. |
### `bulk_link_automated_tests`
Links up to 500 manual test case and automated test pairs in 1 call. The response holds 1 result per pair with `manualTestCaseId`, `fullTitle`, and `success`, plus `link` when the pair linked or `error` when it did not. A failed pair does not stop the rest, so check `success` on every item.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the test cases. |
| `links` | array | Yes | 1 to 500 objects of `{ manualTestCaseId, pwTestId, fullTitle, displayTitle? }`. |
`manualTestCaseId` is the case's internal `_id` (e.g., `tcm_tc_...`) as returned by `list_manual_test_cases`, not the `TC-123` ID.
***
## Releases
Releases track milestones, sprints, and versions for a project. They nest up to 3 levels deep. Reference releases using counter-style IDs like `MS-12`.
### `list_releases`
Returns releases for a project with filtering by type, status, completion, and name.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to list releases from. |
| `type` | string | No | `release`, `version`, `sprint`, `iteration`, `plan`, `cycle`, or `feature`. Projects can define custom types in Project Settings. |
| `status` | string | No | Release status. Values are project-specific. |
| `isCompleted` | boolean | No | `true` to return only completed releases. |
| `parentReleaseId` | string | No | Returns only direct children of this release. |
| `search` | string | No | Match by release name. |
| `sortBy` | string | No | `createdAt`, `startDate`, `endDate`, or `name`. |
| `sortOrder` | string | No | `asc` or `desc`. |
| `limit` | number | No | Results per page (Default 25, max 200). |
| `page` | number | No | Page number (default: 1). |
### `get_release`
Returns full details for one release: dates, status, linked issues, parent/root release, and rolled-up progress stats across all runs in the release and its descendants.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the release. |
| `releaseId` | string | Yes | Internal `_id` or counter-style ID (e.g., `MS-12`). |
### `create_release`
Creates a release or milestone. Use `parentReleaseId` to nest under an existing release (max 3 levels deep).
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID where the release will be created. |
| `name` | string | Yes | Release name. |
| `type` | string | No | `release`, `version`, `sprint`, `iteration`, `plan`, `cycle`, or `feature`. |
| `description` | string | No | Release description. |
| `note` | string | No | Rich HTML note. |
| `startDate` | string | No | ISO date, e.g., `2025-07-01`. |
| `endDate` | string | No | ISO date, e.g., `2025-09-30`. |
| `isStarted` | boolean | No | Mark release as started. |
| `isCompleted` | boolean | No | Mark release as completed. |
| `branch` | string | No | Source branch this release ships from. |
| `environment` | string | No | Target environment label, e.g., `staging`. |
| `buildTarget` | object | No | `{platform, version, buildNumber, source, deployUrl}`. Platform: `web`, `ios`, `android`, or `api`. |
| `testers` | array | No | User `_id`s assigned as testers. Must be org members. |
| `parentReleaseId` | string | No | Nests this release under the specified parent. |
### `update_release`
Updates only the fields you provide inside the `updates` object. All other fields remain unchanged.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the release. |
| `releaseId` | string | Yes | Internal `_id` or counter-style ID (e.g., `MS-12`). |
| `updates` | object | Yes | Fields to update. Accepts all fields from `create_release`. |
***
## Manual Test Runs
Manual test runs track the execution of test cases by a team. Each run belongs to a project and attaches optionally to a release. Reference runs using counter-style IDs like `RUN-12`.
### `list_manual_runs`
Returns manual test runs for a project with filtering by status, state, environment, release, and tags.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to list runs from. |
| `status` | string | No | `active` or `closed`. |
| `state` | string | No | One of your project's run states. Defaults: `New`, `In Progress`, `Under Review`, `Rejected`, `Done`. |
| `environment` | string | No | Environment label, e.g., `staging`. |
| `releaseId` | string | No | Filter runs linked to this release. Pass `none` for unlinked runs. |
| `tags` | string | No | Single tag or comma-separated tags. |
| `search` | string | No | Match by run name. |
| `sortBy` | string | No | `createdAt`, `updatedAt`, or `name`. |
| `sortOrder` | string | No | `asc` or `desc`. |
| `limit` | number | No | Results per page (Default 25, max 200). |
| `page` | number | No | Page number (default: 1). |
### `get_manual_run`
Returns full details for one manual test run: name, status, state, environment, linked release, test stats (total/passed/failed/blocked/untested), contributors, attachments, and linked issues.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the run. |
| `runId` | string | Yes | Internal `_id` or counter-style ID (e.g., `RUN-12`). |
### `create_manual_run`
Creates a manual test run. By default, all test cases in the project are included. You can optionally provide `testCaseIds` or `suiteIds` to limit the run to a specific subset.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID where the run will be created. |
| `name` | string | Yes | Run name. |
| `selectionMode` | string | No | `all` (default) or `selected`. |
| `testCaseIds` | array | No | Case IDs to include when `selectionMode="selected"`. |
| `suiteIds` | array | No | Suite IDs whose cases are included when `selectionMode="selected"`. |
| `includeUnsorted` | boolean | No | Include cases with no suite when `selectionMode="selected"`. |
| `releaseId` | string | No | Attach this run to a release. |
| `environment` | string | No | Environment label, e.g., `staging`. |
| `state` | string | No | One of your project's run states; defaults to `New`. Defaults: `New`, `In Progress`, `Under Review`, `Rejected`, `Done`. |
| `note` | string | No | Rich HTML note. |
| `forecast` | number | No | Numeric target for the run. |
| `tags` | array | No | Array of tag strings, e.g., `["smoke", "regression"]`. Not comma-separated. |
| `linkedIssues` | array | No | `{ provider, displayId, url?, title? }` objects. Without `url`, `provider` must be `jira` or `linear` and the key is looked up there; unknown key returns 400, tracker not connected returns 409. |
| `links` | array | No | Array of `{title, url}` link objects. |
### `update_manual_run`
Updates only the fields you provide inside the `updates` object.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the run. |
| `runId` | string | Yes | Internal `_id` or counter-style ID (e.g., `RUN-12`). |
| `updates` | object | Yes | Fields to update: `name`, `note`, `environment`, `releaseId`, `state`, `forecast`, `tags`, `linkedIssues`, `links`. Pass `status="closed"` to close the run. |
**Warning**
Passing `updates.status="closed"` closes the run. This freezes results and is not reversible via MCP. Closed runs are read-only except for `releaseId`.
### `list_run_test_cases`
Returns per-case execution records inside a manual run. Each record shows the test case identity (`caseKey` like `TC-156`), current assignee, and current result.
Call this before `update_run_test_case` to get the `rtcRef` for each case you want to update.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the run. |
| `runId` | string | Yes | Internal `_id` or counter-style ID (e.g., `RUN-12`). |
| `result` | string | No | Filter by result: `untested`, `passed`, `failed`, `blocked`, `skipped`, or `retest`. |
| `assignee` | string | No | Filter by assignee, User `_id` or email address. |
| `search` | string | No | Match by case title or `caseKey`. |
| `sortBy` | string | No | `createdAt`, `updatedAt`, `status`, or `caseKey`. |
| `sortOrder` | string | No | `asc` or `desc`. |
| `limit` | number | No | Results per page (Default 25, max 200). |
| `page` | number | No | Page number (default: 1). |
### `update_run_test_case`
Updates a test case record within a manual run. You can set the outcome, assign it to a user, or include step results to capture a complete result entry.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the run. |
| `runId` | string | Yes | Internal `_id` or counter-style ID (e.g., `RUN-12`). |
| `rtcRef` | string | Yes | `caseKey` (e.g., `TC-156`), internal `tcm_rtc_...` ID, or test case `_id`. |
| `updates` | object | Yes | Quick verdict: `assigneeUserId`, `result`, `elapsed`. Detailed: `comment`, `linkedIssues`, `stepResults`. |
**Note**
Do not combine `assigneeUserId` with detailed result fields (`comment`, `linkedIssues`, `stepResults`) in a single call. The server rejects this. Make 2 separate calls: one to assign, one to record the detailed result.
***
## Exploratory Sessions
Exploratory sessions track unscripted testing against a mission or charter. Each session belongs to a project and attaches optionally to a release. Reference sessions using counter-style IDs like `SES-12`.
### `list_sessions`
Returns exploratory sessions for a project with filtering by status, state, session type, assignee, release, and tags.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to list sessions from. |
| `status` | string | No | `active` or `closed`. |
| `state` | string | No | `new`, `under_review`, `done`, or `rejected`. |
| `sessionType` | string | No | Free-text session type, e.g., `Exploratory`, `Regression`. |
| `assigneeUserId` | string | No | Filter by assignee, User `_id` or email address. |
| `releaseId` | string | No | Filter sessions linked to this release. Pass `none` for unlinked sessions. |
| `tags` | string | No | Single tag or comma-separated tags. |
| `search` | string | No | Match by session name. |
| `sortBy` | string | No | `createdAt`, `updatedAt`, or `name`. |
| `sortOrder` | string | No | `asc` or `desc`. |
| `limit` | number | No | Results per page (Default 25, max 200). |
| `page` | number | No | Page number (default: 1). |
### `get_session`
Returns full details for one exploratory session: name, mission, status, assignee, linked release, attachments, linked issues, and findings.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the session. |
| `sessionId` | string | Yes | Internal `_id` or counter-style ID (e.g., `SES-12`). |
### `create_session`
Creates an exploratory session. Use `mission` to define the testing charter and `releaseId` to attach the session to a release.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID where the session will be created. |
| `name` | string | Yes | Session name. |
| `mission` | string | No | Rich HTML mission or testing charter. |
| `sessionType` | string | No | Free-text type, e.g., `Exploratory`, `Regression`. |
| `assigneeUserId` | string | No | User `_id` or email address. |
| `releaseId` | string | No | Attach session to this release. |
| `environment` | string | No | Environment label, e.g., `staging`. |
| `state` | string | No | `new` (default), `under_review`, `done`, or `rejected`. |
| `estimate` | number | No | Estimated duration in minutes. |
| `tags` | array | No | Array of tag strings, e.g., `["exploratory", "auth"]`. Not comma-separated. |
| `linkedIssues` | array | No | `{ provider, displayId, url?, title? }` objects. Without `url`, `provider` must be `jira` or `linear` and the key is looked up there; unknown key returns 400, tracker not connected returns 409. |
**Note**
Findings are not available via MCP. Add findings in the TestDino UI after creating the session.
### `update_session`
Updates only the fields you provide inside the `updates` object.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID containing the session. |
| `sessionId` | string | Yes | Internal `_id` or counter-style ID (e.g., `SES-12`). |
| `updates` | object | Yes | Fields to update: `name`, `mission`, `sessionType`, `environment`, `releaseId`, `assigneeUserId`, `state`, `estimate`, `tags`, `linkedIssues`. Pass `status="closed"` to close the session. |
**Warning**
Passing `updates.status="closed"` closes the session. This is not reversible via MCP.
***
## Integrations
Connect issue trackers and file issues from TestDino entities. Supported providers: `jira`, `linear`, `asana`, `monday`, and `github`.
### `get_integration_status`
Checks whether a provider is connected for a project, and optionally returns the projects, issue types, and fields needed to create an issue.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to check. |
| `provider` | string | Yes | `jira`, `linear`, `asana`, `monday`, or `github`. |
| `includeCreateOptions` | boolean | No | Also return projects, issue types, and fields for issue creation. |
| `target` | object | No | Provider-specific values to resolve create options against a specific target, e.g. Jira `{ jiraProjectKey, issueType }`. |
**Example**
* "Is Jira connected for this project?"
* "Get Jira create options for project key TRX and Bug issue type."
### `connect_integration`
Starts an OAuth connection for a provider. Returns `already_connected`, or a connect URL to open.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID to connect. |
| `provider` | string | Yes | `jira`, `linear`, `asana`, `monday`, or `github`. |
| `orgId` | string | No | Usually inferred from the PAT scope. |
**Note**
Show the returned connect URL to the user. Do not open it programmatically.
**Example**
* "Connect Linear for this project."
### `create_external_issue`
Files a provider issue from a TestDino entity such as a test case, run, or manual case.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `provider` | string | Yes | `jira`, `linear`, `asana`, `monday`, or `github`. |
| `source` | object | Yes | `{ type, id, runId?, testRunId?, caseId? }`. |
| `summary` | string | No | Issue title. Derived from the source if omitted. |
| `description` | string | No | Issue body. Derived from the source if omitted. |
| `target` | object | No | Provider destination fields, e.g. Jira project key and issue type. |
| `linkBack` | boolean | No | Link the issue back to the source (Jira). |
| `idempotencyKey` | string | No | Stable key that makes retries safe (min length 1). |
| `preview` | boolean | No | Return the draft without creating the issue. |
`source.type` values: `test_run`, `test_suite`, `test_case`, `manual_test_case`, `manual_test_suite`, `release`, `manual_run`, `manual_run_test_case`, `session`.
**Example**
* "File a Jira bug for the failing test case `a1b2c3` in run #47 and link it back."
* "Preview the Linear issue you'd create for manual case TC-142."
### `get_external_issue`
Fetches one or more previously linked external issues.
| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `projectId` | string | Yes | The project ID. |
| `provider` | string | Yes | `jira`, `linear`, `asana`, `monday`, or `github`. |
| `issueIds` | string\[] | Yes | One or more IDs or keys, e.g. `["TD-17","TD-18"]`. |
| `target` | object | No | Read context, e.g. Jira `{ defaultApp }`. |
**Example**
* "Is Jira issue TD-17 still open?"
* "Check the status of TD-17, TD-18 and TD-19."
## Prompts
Prompts are guided workflows the MCP server exposes alongside its tools. Clients that support MCP prompts list them as slash commands, so you pick the workflow from a menu instead of describing it.
| Prompt | Answers | Arguments |
| :- | :- | :- |
| `fix_run` | Of these failures, what are the distinct problems and in what order? | `projectId` (required), `testrun_id` |
| `fix_case` | Why does this test case fail, and what change fixes it? | `projectId` (required), `testcase_name`, `testcase_id`, `testrun_id`, `suite_file_path` |
| `fix_flake` | Is this a code defect or a timing defect? | `projectId` (required), `testcase_id`, `testrun_id` |
Each prompt carries scope only, never test run data, so the assistant reads current state rather than a snapshot. `fix_run` groups a test run's failures by shared cause and orders them largest group first, because one fix there often closes many test cases at once. `fix_case` and `fix_flake` both close at `verify_fix`, so the assistant confirms the change against TestDino instead of judging its own work.
If you do not name a test case, `fix_case` lists the failing test cases first and asks which one to work on.
Prompt support varies by client. When your assistant does not list prompts, ask for the same workflow in your own words and name the test run or test case. The [Debug with AI](/guides/debug-playwright-failures/debug-with-ai) button copies an instruction that works either way.
An assistant asks for approval before it edits a file or runs a command, and approving one action does not approve the next. Fix suggestions are proposals to review, not changes to apply unread.
***
## Related
What the MCP server does and when to use it
Connect a hosted client with your PAT
Run the server on your own machine
Fix connection, auth, and tool call errors
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.