> ## 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
> Complete reference for all 27 TestDino MCP tools: parameters, examples, and usage notes for test runs, releases, manual runs, and exploratory sessions.
**What you'll learn**
* All 27 MCP tools across test runs, test cases, releases, manual runs, and exploratory sessions
* Input parameters and output formats for each tool
* Usage examples for querying and debugging
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 |
| | [`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 |
| **Test Audit** | [`test_audit`](#test_audit) | Run a Playwright test-quality audit and submit it to TestDino |
| **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 |
| **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 |
***
## 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_time_interval` | string | No | `1h`, `2h`, `6h`, `12h`, `1d`, `3d`, `weekly`, `monthly`, or date range `YYYY-MM-DD, YYYY-MM-DD`. |
| `by_author` | string | No | Commit author name; case-insensitive partial match. |
| `by_commit` | string | No | Commit hash (full or partial). |
| `by_environment` | string | No | Environment, e.g., `production`, `staging`, `development`. |
| `limit` | number | No | Results per page (Default 20, max 1000). |
| `page` | number | No | Page number for pagination (default: 1). |
| `get_all` | boolean | No | Retrieve all results up to 1000. |
**Note**
Filters can be combined. Pagination uses `page` and `limit`. `get_all=true` fetches up to 1000 records.
**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. |
**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**
### `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`, `skipped`, `flaky`. |
| `by_spec_file_name` | string | No | Filter by spec file name. |
| `by_error_category` | string | No | Error category name. |
| `by_browser_name` | string | No | Browser name, e.g., `chromium`. |
| `by_tag` | string | No | Tag or comma-separated tags. |
| `by_total_runtime` | string | No | Time filter using operators, e.g., `<60`, `>100`. |
| `by_artifacts` | boolean | No | `true` to only return cases with artifacts. |
| `by_error_message` | string | No | Partial match on error message. |
| `by_attempt_number` | number | No | Filter by attempt number. |
| `by_branch` | string | No | Branch name; filters runs first, then returns cases. |
| `by_time_interval` | string | No | `1d`, `3d`, `weekly`, `monthly`, or date range. |
| `limit` | number | No | Results per page (Default 1000, max 1000). |
| `page` | number | No | Page number (default: 1). |
| `get_all` | boolean | No | Get all results up to 1000. |
\* 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`. |
\* 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. |
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.
***
## Test Audit
### `test_audit`
Runs a single-pass Playwright test-quality audit on the local repo and submits the report to TestDino. Use it to surface shallow assertions, false-confidence tests, and flakiness or maintainability risks across a Playwright suite.
**Trigger only on explicit TestDino mention**
This tool fires 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 tool 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 `.spec.ts` / `.spec.js` / `.test.ts` / `.test.js` using Playwright APIs), explain that TestDino's audit only covers Playwright and offer a regular audit instead — do not call the tool.
Typical asks that should trigger it:
* "How shallow is this Playwright suite?"
* "Which Playwright tests are giving us false confidence?"
* "What are the biggest maintainability and flakiness risks in our Playwright tests?"
| Parameter | Type | Required | Description |
| :------------------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` | string | Yes | Project ID. |
| `action` | string | Yes | `analyze`, `list`, or `get`. |
| `branch` | string | No | Branch to audit. Required for `analyze` unless detectable from git. Optional filter for `list`. |
| `scope` | string | No | `testcase`, `feature`, `spec_file`, or `suite`. |
| `target` | object | No | Structured target such as feature area or spec path. |
| `reportName` | string | No | Short, human-readable title for the saved report. |
| `score` | number | No | Final audit score. Include with `markdownReport` or `markdownReportPath` to submit a completed report. |
| `findings` | array | No | Structured findings for the submitted report. |
| `recommendations` | array | No | Recommendation strings for the submitted report. |
| `markdownReport` | string | No | Completed markdown report body. Required when submitting if `markdownReportPath` is not used. |
| `markdownReportPath` | string | No | Local markdown file to read for submission. Relative paths resolve from `TESTDINO_MCP_WORKSPACE` when set, otherwise from the MCP process cwd. Absolute paths allowed. |
| `reportId` | string | No | Required for `get`. |
| `limit` | number | No | Page size for `list`. |
| `page` | number | No | Page number for `list`. |
| `writeMarkdown` | boolean | No | Save the returned markdown report locally. |
| `outputPath` | string | No | Relative path for the local markdown report. Defaults to `TEST-AUDIT.md` when `writeMarkdown=true`. |
**Recommended workflow**
1. `test_audit(action="analyze", branch="main")` — fetch the server-curated audit prompt, branch signals, and the previous audit summary for the branch.
2. If the user named a feature or spec, set `scope` and `target` so the audit stays focused on that slice.
3. 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.
4. Build the final `score`, `findings`, `recommendations`, choose a short `reportName`, and write the markdown locally (e.g. `TEST-AUDIT.md`).
5. Submit: `test_audit(action="analyze", branch="main", reportName="...", score=..., markdownReportPath="TEST-AUDIT.md")`. Set `TESTDINO_MCP_WORKSPACE` to the repo root if the MCP starts outside the project, or pass an absolute path. Use inline `markdownReport` only as a fallback.
6. `test_audit(action="list")` (or with `branch="..."`) to browse history. `test_audit(action="get", reportId="...")` to retrieve one report.
**Best practices**
* Use branch signals from the `analyze` response to prioritize the tests and config that need attention first.
* If `analyze` 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.
* Set `writeMarkdown=true` on submissions or `get` responses to persist `TEST-AUDIT.md` locally.
***
## 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 | `1h`, `2h`, `6h`, `12h`, `1d`, `3d`, `weekly`, `monthly`, or date range `YYYY-MM-DD, YYYY-MM-DD`. |
| `search` | string | No | Match against title, description, 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`. |
| `severity` | string | No | `Blocker`, `Critical`, `Major`, `Normal`, `Minor`, `Trivial`, or `Not set`. |
| `type` | string | No | `Functional`, `Smoke`, `Regression`, `Security`, `Performance`, `E2E`, `Integration`, `API`, `Unit`, `Accessibility`, `Compatibility`, `Acceptance`, `Exploratory`, `Usability`, or `Other`. |
| `layer` | string | No | `E2E`, `API`, `Unit`, or `Not set`. |
| `behavior` | string | No | `Positive`, `Negative`, `Destructive`, or `Not set`. |
| `automationStatus` | string | No | `Manual`, `Automated`, or `To be automated`. |
| `tags` | string | No | Comma-separated tags. Example: `smoke,regression`. |
| `isFlaky` | boolean | No | `true` for flaky only, `false` for non-flaky. |
| `limit` | number | No | Max results (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. |
| `suiteId` | string | Yes | The suite ID. Use `list_manual_test_suites` to find IDs. |
| `description` | string | No | Description of what the test covers. |
| `status` | string | No | `Active`, `Draft`, or `Deprecated`. |
| `stepsDeclarationType` | 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`. |
| `severity` | string | No | `Blocker`, `Critical`, `Major`, `Normal`, `Minor`, `Trivial`, or `Not set`. |
| `type` | string | No | `Functional`, `Smoke`, `Regression`, `Security`, `Performance`, `E2E`, `Integration`, `API`, `Unit`, `Accessibility`, `Compatibility`, `Acceptance`, `Exploratory`, `Usability`, or `Other`. |
| `layer` | string | No | `E2E`, `API`, `Unit`, or `Not set`. |
| `behavior` | string | No | `Positive`, `Negative`, `Destructive`, or `Not set`. |
| `automationStatus` | string | No | `Manual`, `Automated`, or `To be automated`. |
| `tags` | string | No | Comma-separated tags. |
| `automation` | object | No | `{toBeAutomated, isFlaky, muted}`, all boolean. |
| `attachments` | array | No | File attachments. Max 10 MB per file. |
| `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`. |
**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. Empty returns top-level suites. |
**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**
***
## 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 | `new`, `in_progress`, `on_hold`, or `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 | `new` (default), `in_progress`, `on_hold`, or `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 | Linked issue objects. |
| `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 two 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 | Linked issue objects. |
**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.