TestDino MCP Tools Reference Guide

Parameters, examples, and usage notes for all 33 TestDino MCP tools across test runs, audits, releases, manual runs, and integrations.

Parameters and usage examples for each TestDino MCP tool.

Tool Index

Category	Tool	Description
Connection	health	Verify server status and token access
Analysis	list_testruns	List and filter test runs
	get_run_details	Full report for one or more runs
	get_run_error_clusters	Group a run’s failures by error signature
	list_testcase	List and filter test cases across runs
	get_testcase_details	Full debug context for a single test case
	debug_testcase	Root cause analysis and fix recommendations
Test Audit	get_audit_report	Read audit context, list past reports, or fetch one
	submit_audit_report	Submit a completed audit report
Test Case Management	list_manual_test_cases	Search manual test cases
	get_manual_test_case	Fetch a manual test case with steps
	create_manual_test_case	Create a manual test case
	update_manual_test_case	Update fields on a manual test case
	list_manual_test_suites	List suite hierarchy
	create_manual_test_suite	Create a new suite
Releases	list_releases	Browse releases and milestones
	get_release	Full details for one release
	create_release	Create a release or milestone
	update_release	Update release fields
Manual Test Runs	list_manual_runs	Browse manual test runs
	get_manual_run	Full details for one run
	create_manual_run	Create a manual test run
	update_manual_run	Update run fields or close a run
	list_run_test_cases	List test cases within a run
	update_run_test_case	Set result for a test case in a run
Exploratory Sessions	list_sessions	Browse exploratory sessions
	get_session	Full details for one session
	create_session	Create an exploratory session
	update_session	Update session fields or close a session
Integrations	get_integration_status	Check a provider connection and create options
	connect_integration	Connect a provider via OAuth
	create_external_issue	File a provider issue from a TestDino entity
	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_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

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

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.

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	Yes	Completed markdown report body.
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.

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	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 or 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.
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.
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 or Automated.
tags	string	No	Comma-separated tags.
flags	array	No	Any of Is flaky, Muted.
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 _ids 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.

---

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

Related

MCP Overview

What the MCP server does and when to use it

Remote MCP

Connect a hosted client with your PAT

Local MCP

Run the server on your own machine

MCP Troubleshooting

Fix connection, auth, and tool call errors