TestDino MCP — AI Agent Skills Guide

How to use this guide: Read this document before making any TestDino tool calls. It tells you which tool to pick, what parameters are required vs. optional, and how to chain tools together for common tasks.

Table of Contents

1. Core Concepts
2. Tool Reference

• Automated test analytics
• health
• list_testruns
• get_run_details
• list_testcase
• get_testcase_details
• debug_testcase
• test_audit
• Manual test cases
• list_manual_test_cases
• get_manual_test_case
• create_manual_test_case
• update_manual_test_case
• list_manual_test_suites
• create_manual_test_suite
• Releases (a.k.a. milestones)
• list_releases
• get_release
• create_release
• update_release
• Manual test runs
• list_manual_runs
• get_manual_run
• create_manual_run
• update_manual_run
• list_run_test_cases
• update_run_test_case
• Exploratory sessions
• list_sessions
• get_session
• create_session
• update_session

1. Workflows & Patterns
2. Decision Trees
3. Parameter Quick Reference
4. Error Handling

Core Concepts

Authentication

• All tools read TESTDINO_PAT automatically from the environment — you never pass it as a parameter.
• If this variable is missing, all tools throw "Missing TESTDINO_PAT environment variable". Tell the user to add it to their mcp.json env section.

projectId

• Required for every tool except `health`.
• Call health() first in any session to get the project IDs and pick the right one.
• Projects are nested under organizations in the health response.

Identifiers

• testrun_id: A string MongoDB-style ID (e.g. "test_run_6901b2abc6b187e63f536a6b")
• counter: A sequential integer (e.g. 43) — human-readable alias for a test run
• testcase_id: A string ID for a specific test case execution
• caseId: A string ID or human-readable ID (e.g. "TC-123") for a manual test case
• releaseId: Either an internal tcm_milestone_... \_id or a counter-style ID like "MS-12". The MCP layer resolves the counter form automatically.
• runId: Either an internal tcm_run_... \_id or a counter-style ID like "RUN-12". Counter form resolves the same way.
• sessionId: Either an internal tcm_session_... \_id or a counter-style ID like "SES-12".
• rtcRef (per-case record in a run): One of three forms accepted by update_run_test_case:

1. The internal tcm_rtc_... \_id of the run-test-case row.
2. The caseKey (e.g. "TC-156") — what the UI shows in the ID column.
3. The underlying manual test case \_id.

Works even when no run-test-case row exists yet (untested virtual cases) — the server creates the record on first edit.

• assigneeUserId: Accepted as either a User _id ("user_...") or an email address. Server resolves email to _id automatically. Used in create_session, update_session, update_run_test_case, and as a filter in list_sessions/list_run_test_cases.

Pagination defaults

• Most list tools default to limit=20 or limit=50. Use get_all=true sparingly — only when you genuinely need every record.
• Prefer filters over fetching everything.

Canonical values for state / type / result

Some free-text fields drive the UI's color/badge map and have a canonical stored form that's lowercase + underscore-joined:

• state on sessions and runs: new, under_review, in_progress, on_hold, done, rejected, …
• type on releases: iteration, major, minor, patch, …
• result / status on run test cases: untested, passed, failed, blocked, skipped, retest.

You can pass either the canonical form or the display form ("Under review", "Iteration", "Passed") — the server normalizes to canonical before storing. If you pass display form and the UI badge ever looks dull/grey, that means normalization didn't run; report the input to the user. The canonical form for result values is past tense ("passed", not "pass").

Arrays vs comma-separated strings

When sending payloads (POST/PATCH bodies), tags and linkedIssues MUST be JSON arrays — ["smoke","regression"], not "smoke,regression". The comma-separated form is only accepted on list-tool query-filter parameters because URLs can't carry arrays cleanly. Mixing these up returns a 400 from zod.

Test Audit Principle — Two Scenarios

The test_audit tool is triggered by a named request only. There are exactly two scenarios:

#### Scenario 1 — Generic audit request (any kind) → DO NOT call test_audit, DO NOT mention TestDino

When the user asks for any kind of audit without explicitly naming TestDino — e.g. "audit this", "run a test audit", "audit this file", "security audit", "code review", "accessibility audit", "audit our tests" — run the audit as a normal AI-agent conversation. Read the target, give your review, findings, and suggestions directly in chat.

This applies even when the target is Playwright test code. A generic "test audit" on a Playwright file is still just a normal audit conversation — the tool is not triggered unless the user explicitly names TestDino.

Do NOT say _"TestDino's audit is Playwright-only"_, _"I can run a TestDino audit instead"_, or anything that mentions TestDino. Behave exactly as a plain AI assistant with no TestDino MCP installed.

#### Scenario 2 — Explicit TestDino audit request → call test_audit (Playwright only)

Trigger phrases (any of these REQUIRE an immediate tool call): "TestDino test audit", "Testdino Test Audit", "Testdino audit", "TestDino MCP audit", "run a TestDino test audit", "audit this with TestDino", "I need a TestDino audit", "testdino test audit on this". Case-insensitive.

Mandatory behavior when triggered (Playwright target + TestDino named):

The moment a trigger phrase is detected, your first and immediate action MUST be test_audit(action="analyze", projectId=..., branch=...). Before that call returns:

• Do NOT write any audit content in chat.
• Do NOT produce a heading like _"TestDino Test Audit — <file>"_.
• Do NOT list findings, score, severity, or recommendations.
• Do NOT describe the file in audit-report language.
• Do NOT simulate a TestDino audit from your own analysis.

Doing any of the above without calling the tool is a protocol violation — you would be claiming to produce a TestDino audit without actually running TestDino's audit flow. TestDino audits require the server-curated prompt and branch signals returned by action="analyze"; you do not have those without the tool call. "TestDino Test Audit" is the name of a capability that runs via this tool, not a style of output you can imitate.

Gate — target must be Playwright code. Detect via any of:

• @playwright/test imports
• Playwright APIs in the file: page., browser., context., locator(, test(, test.describe(, test.beforeEach(, test.step(, expect(page), browserName, storageState, test.extend(
• A playwright.config.ts/playwright.config.js in the repo
• .spec.ts/.spec.js/.test.ts/.test.js files using the above APIs
• The user explicitly naming Playwright

If the user names TestDino but the target is NOT Playwright, politely explain TestDino's test audit only covers Playwright automated test code and offer a regular (non-TestDino) audit instead. Do NOT call the tool. This is the one place mentioning TestDino's Playwright-only scope is appropriate — because the user explicitly invoked TestDino.

When both conditions hold (explicit TestDino + Playwright target), run the full flow:

1. test_audit(action="analyze", projectId=..., branch="...") — IMMEDIATE first action. No score, no findings, no markdownReport on this call. Use health() first if you don't have a projectId yet.
2. Only after Step 1 returns, analyze the local Playwright code using the returned prompt + signals, and write the audit to a local markdown file (e.g. TEST-AUDIT.md).
3. Call test_audit again with action="analyze", markdownReportPath pointing at the local file, plus score, findings, recommendations, reportName to submit to TestDino.

Other principles for Scenario 2:

• If the user names a slice like auth/login, dashboards, alerts, or one spec file, keep the audit centered on that slice instead of drifting into generic suite hygiene.
• If test_audit returns PROJECT_NOT_FOUND, auth, or access errors, stop and resolve projectId with health() before continuing. Do not generate a pseudo-audit from local files alone.
• Keep raw code local and only send structured findings plus concise evidence.
• Use the returned branch signals to decide which files to inspect first.
• Avoid pasting long snippets when a metric, prevalence estimate, or file/line reference is enough.

Tool Reference

health

Purpose: Verify PAT, check connection, and retrieve project/organization info.

Required parameters: None

When to call:

• At the start of every session before using any other tool.
• When the user asks "what projects do I have?" or "check my connection."
• When you don't yet have a projectId.

Response includes:

• Account and email info
• List of organizations → each with a list of projects and their projectId values
• Access permissions per project

Pattern:

Call health()
→ Extract org name and project name the user is asking about
→ Store projectId for all subsequent calls in this session

list_testruns

Purpose: Browse test runs with flexible filters.

Required parameters: projectId

Optional filters:

Response includes: test run IDs, counters, passed/failed/skipped/flaky counts, branch, author, commit, environment, duration, timestamps.

Good uses:

• Find test runs to get IDs for follow-up calls
• Summarize test execution trends over time
• Identify which commits introduced failures

get_run_details

Purpose: Get the full breakdown of a single test run (or batch of up to 20).

Required parameters: projectId + (testrun_id OR counter)

Optional parameters:

Response includes: full summary, test statistics by status, error category breakdown, test suites, and all test cases in the run.

Workflow:

list_testruns() → get run IDs → get_run_details() for the specific run

list_testcase

Purpose: List and filter test cases across one or many test runs.

Required parameters: projectId + at least one test run identifier or test run filter.

Test run identification (use one approach):

Test case filters (combine freely):

Key insight: When you use by_branch, by_commit, etc., the tool internally finds matching test runs first and then returns their test cases. You don't need to call list_testruns first.

get_testcase_details

Purpose: Get full details of a specific test case — errors, stack traces, steps, console logs, and artifacts.

Required parameters: projectId + at least one search parameter from the list below.

Search parameters (provide at least one):

Scoping parameters:

Artifact parameters (default false):

History and filtering:

Pagination and sorting:

Critical rules:

• testcase_name alone without a run context returns ALL executions of that test across runs. Always pair with testrun_id or counter unless you want cross-run history.
• Use steps_filter='failed_only' when debugging to cut noise — only failed steps are returned.
• Use include_history=true + history_limit to track a test's pass/fail pattern over time.

debug_testcase

Purpose: AI-assisted root cause analysis using historical failure data.

Required parameters: projectId, testcase_name

What it returns:

• Historical execution data across many test runs
• Failure patterns (error types, frequency, browsers affected)
• Common error messages and code locations
• A debugging_prompt string — pre-formatted analysis instructions specifically designed for the AI to use as context when diagnosing the issue

How to use the response:

1. Read the debugging_prompt field — treat it as domain-specific instructions for your analysis.
2. Examine the historical failure data to identify patterns.
3. Look for: consistent error messages, browser-specific failures, time-of-day patterns, correlations with specific branches or commits.
4. Optionally follow up with get_testcase_details() (with include_screenshots=true or include_traces=true) for a specific failing execution.

When to call:

• User says "why is test X failing?" / "debug test X" / "is test X flaky?"
• You need to understand if a failure is consistent or intermittent.
• You need historical context before diving into a specific execution.

Pattern:

debug_testcase(projectId, "Verify user login")
→ Read debugging_prompt from response
→ Analyze historical data using the debugging_prompt as context
→ Identify pattern: always fails? flaky? browser-specific? recent regression?
→ Optionally: get_testcase_details(...)
→ Provide root cause analysis and fix suggestions

test_audit

Purpose: Run a single-pass audit of Playwright test quality using TestDino for prompt orchestration and your local AI agent for repository analysis. This tool is only triggered when the user explicitly names TestDino.

Trigger rule — explicit TestDino naming required, tool call is MANDATORY and IMMEDIATE:

• When the user uses a TestDino trigger phrase ("TestDino test audit", "Testdino Test Audit", "Testdino audit", "TestDino MCP audit", "run a TestDino audit", "audit this with TestDino", etc.) AND the target is Playwright code, your first action MUST be test_audit(action="analyze", ...). Do not write audit content in chat, do not produce a "TestDino Test Audit" heading, do not list findings or a score before the tool call. Simulating the audit output without calling the tool is a protocol violation.
• For any generic audit request ("audit this", "test audit", "code audit", "security audit", etc.) where the user does NOT name TestDino, DO NOT call this tool — run a normal AI audit conversation instead, with zero TestDino mention. This applies even when the target is Playwright test code.
• When TestDino is explicitly named, the target code must be Playwright (detected via @playwright/test imports, Playwright APIs like page./browser./locator(/test.extend(/storageState, playwright.config.*, or .spec.ts/.spec.js/.test.ts/.test.js files using those APIs).
• If the user names TestDino but the target is not Playwright, politely explain that TestDino's test audit only covers Playwright automated test code and offer a regular (non-TestDino) audit instead. Do NOT call the tool.

Required parameters: projectId, action

Actions:

Analyze parameters:

Lifecycle parameters:

How to use it well:

1. Start with test_audit(action="analyze", branch="...") to fetch the prompt, branch signals, and prior audit findings.
2. If the user named a feature/spec area, pass the smallest correct scope plus explicit target, and inspect only that local slice plus its shared helpers/setup.
3. In scoped audits, spend most findings on feature-specific validation gaps and missing scenarios; generic waits/logging/duplication issues are secondary unless they materially invalidate confidence in that slice.
4. If analyze fails because the project is missing or access is denied, call health() and resolve the right projectId before continuing. Do not write a fallback local-only audit and present it as a TestDino audit.
5. Convert the audit into score, findings, recommendations, choose a short reportName, and write the markdown report to a local file.
6. Submit the completed report with test_audit(action="analyze", branch="...", reportName="...", score=..., markdownReportPath="TEST-AUDIT.md"). Set TESTDINO_MCP_WORKSPACE to your repo root if the MCP starts outside the project, or pass an absolute path. Use inline markdownReport only when a local file is not practical.
7. Use test_audit(action="list") to browse all saved reports, add branch="..." if you need branch-specific history, and use test_audit(action="get", reportId="...", writeMarkdown=true) to save TEST-AUDIT.md locally when needed.

Token efficiency rules:

• Never upload full files.
• Prefer counts, ratios, clusters, and representative patterns.
• If 20 tests share a problem, say that once with prevalence.
• Let the branch signals drive the investigation order before broad scanning.

Pattern:

test_audit(action="analyze", branch="main", scope="feature", target={ featureName: "Auth / Login" })
→ Receive prompt + branchSignals + lastAudit
→ Read only the relevant auth/login files plus shared setup/helpers
→ Build score + findings + recommendations + reportName, then write TEST-AUDIT.md
→ test_audit(action="analyze", branch="main", reportName="Login Flow Tests", score=88, findings=[...], markdownReportPath="TEST-AUDIT.md", writeMarkdown=true)
→ Optionally: test_audit(action="list") or test_audit(action="get", reportId="<id>")

list_manual_test_cases

Purpose: Search and browse manual test cases.

Required parameters: projectId

Optional filters:

get_manual_test_case

Purpose: Get full details of a single manual test case including steps, preconditions, and metadata.

Required parameters: projectId, caseId

• caseId can be the internal _id or a human-readable ID like 'TC-123'.

create_manual_test_case

Purpose: Create a new manual test case.

Required parameters: projectId, title, suiteName

Always call `list_manual_test_suites()` first to find the exact suite name. The suiteName must match exactly.

Key optional parameters:

Classic step format:

{
  "action": "Click the login button",
  "expectedResult": "User is redirected to dashboard",
  "data": "Username: [email protected]",
  "attachments": ["https://example.com/step-screenshot.png"]
}

Gherkin step format:

{
  "event": "Given",
  "stepDescription": "the user is on the login page",
  "attachments": ["https://example.com/step-screenshot.png"]
}

• event must be one of: "Given", "When", "And", "Then", "But"

update_manual_test_case

Purpose: Modify fields of an existing manual test case. Send only the fields you want to change.

Required parameters: projectId, caseId, updates (object)

`updates` object fields (all optional — only include what you're changing):

Important: attachments uses a nested add/remove structure — you can add and remove in the same call:

{
  "attachments": {
    "add": ["https://example.com/new-screenshot.png"],
    "remove": ["old-attachment-id"]
  }
}

Step-level attachments are added by including attachments on a top-level step in updates.steps.

list_manual_test_suites

Purpose: Get the test suite hierarchy (folders/groups for organizing manual test cases).

Required parameters: projectId

Optional parameters:

Returns: Array of suites with id, name, parentSuiteId, and child count.

When to call: Before create_manual_test_case to get the exact suiteName to use.

create_manual_test_suite

Purpose: Create a new test suite (folder) for organizing test cases.

Required parameters: projectId, name

Optional parameters:

list_releases

Purpose: Browse releases (a.k.a. milestones) for a project. Each release groups runs + sessions and may nest under a parent release up to 3 levels deep.

Required parameters: projectId

Optional filters:

get_release

Purpose: Full details for one release — dates, status, parent/root hierarchy, rolled-up progress stats (run counts, test status breakdown across descendants), linked issues.

Required parameters: projectId, releaseId

• releaseId accepts either an internal tcm_milestone_… \_id or a counter-style ID like "MS-12".

create_release

Purpose: Create a new release.

Required parameters: projectId, name

Optional parameters:

update_release

Purpose: Modify one release. Send only the fields you want to change inside updates.

Required parameters: projectId, releaseId, updates (object)

updates object accepts the same fields as create. Type passed in display form ("Major") is normalized to canonical ("major") before save.

list_manual_runs

Purpose: Browse manual test runs in a project — the executions of grouped test cases against a build/environment.

Required parameters: projectId

Optional filters:

get_manual_run

Purpose: Full details for one run — name, status, environment, linked release, test stats (total / passed / failed / blocked / untested), contributors, attachments, linked issues.

Required parameters: projectId, runId

• runId accepts the internal tcm_run_… \_id OR a counter-style ID like "RUN-12".

create_manual_run

Purpose: Create a new manual test run.

Required parameters: projectId, name

Key optional parameters:

update_manual_run

Purpose: Modify an existing run's metadata. Per-case results live in update_run_test_case (NOT here).

Required parameters: projectId, runId, updates (object)

updates accepts: name, note, environment, releaseId, state, forecast, tags, linkedIssues, attachments, links, selectionMode.

Closed runs are read-only EXCEPT for `releaseId` — so a closed run can be re-attached to a different release without re-opening it.

list_run_test_cases

Purpose: Get the per-case execution records inside a manual run — what the UI shows as rows in the run's test-case table. Each row carries the case identity (caseKey like "TC-156", title), current assignee, and current result.

Required parameters: projectId, runId

Optional filters:

When to call: Always before update_run_test_case — gives you the exact rtcRef (or just the caseKey) and the current state per case.

update_run_test_case

Purpose: Set the assignee and/or result for one test case inside a manual run — exactly what clicking "Assign to" + the result pill does in the UI.

Required parameters: projectId, runId, rtcRef, updates (object)

rtcRef accepts THREE forms:

1. tcm_rtc_… \_id (existing run-test-case row)
2. "TC-156" (caseKey — the user-facing display ID)
3. Underlying manual test case \_id

Works for untested "virtual" cases too. In an 'all'-mode run, cases with no record yet still show "Untested" in the UI — passing the caseKey or test case \_id auto-creates the run-test-case row on first edit. Same path the UI takes on first click.

`updates` object fields:

For multiple cases: call this tool in parallel — one call per case. Don't try to batch in updates.

list_sessions

Purpose: Browse exploratory testing sessions.

Required parameters: projectId

Optional filters:

get_session

Purpose: Full details for one session — name, mission, status, assignee, linked release, attachments, linked issues, findings.

Required parameters: projectId, sessionId

• sessionId accepts internal tcm_session_… \_id OR counter-style "SES-12".

create_session

Purpose: Create a new exploratory session.

Required parameters: projectId, name

Key optional parameters:

Findings cannot be created here in v1 — add them via the UI.

update_session

Purpose: Modify an existing session's metadata.

Required parameters: projectId, sessionId, updates (object)

updates accepts: name, mission, sessionType, config, environment, releaseId, assigneeUserId, state, estimate, tags, linkedIssues, attachments. Findings are not editable via MCP in v1.

Workflows & Patterns

Session Startup

1. health()                          → get projectId
2. Store projectId for the session
3. Proceed with the user's request

Find and Analyze Failed Tests

1. list_testcase(projectId, by_branch="main", by_status="failed", by_time_interval="1d")
   → Get failed test cases directly (no need to call list_testruns first)
2. For each failing test of interest:
   get_testcase_details(projectId, testcase_id=<id>, steps_filter="failed_only")
   → See the exact failing step and error

Debug a Specific Test

1. debug_testcase(projectId, "test case name")
   → Get historical data + debugging_prompt
2. Read the debugging_prompt — use it as analysis context
3. Identify pattern from history (flaky? consistent? regression?)
4. If you need to see a specific run's artifacts:
   get_testcase_details(projectId, testcase_name="...", testrun_id=<latestFailRun>,
     steps_filter="failed_only", include_screenshots=true, include_traces=true)
5. Provide root cause analysis and suggested fix

Investigate a Recent Regression

1. list_testruns(projectId, by_branch="main", by_time_interval="3d", limit=10)
   → Find recent runs and identify when pass rate dropped
2. get_run_details(projectId, testrun_id="<failing run>")
   → See full breakdown and error categories
3. list_testcase(projectId, by_testrun_id="<failing run>", by_status="failed")
   → List the specific tests that broke
4. debug_testcase(projectId, "<test name>") for key failing tests
   → Confirm this is a new regression, not pre-existing flakiness

Track a Flaky Test Over Time

1. debug_testcase(projectId, "test case name")
   → Review historical pass/fail pattern
2. get_testcase_details(projectId, testcase_name="...", include_history=true, history_limit=20)
   → See last 20 executions with full details
3. Look for: intermittent failure pattern, specific browsers, time-based correlation

Create a Manual Test Case

1. list_manual_test_suites(projectId)
   → Find the exact suite name where the test case should go
2. (If suite doesn't exist)
   create_manual_test_suite(projectId, name="New Suite Name", parentSuiteId="...")
3. create_manual_test_case(projectId, title="...", suiteName="Exact Suite Name",
     steps=[...], priority="high", type="functional")

Update Test Case Steps

1. get_manual_test_case(projectId, caseId="TC-123")
   → See current steps and metadata
2. update_manual_test_case(projectId, caseId="TC-123", updates={
     steps: [...new steps...],
     status: "Active"
   })

Cross-Run Failure Analysis

list_testcase(projectId,
  by_testrun_id="run1,run2,run3",   ← up to 20 comma-separated IDs
  by_status="failed",
  by_browser_name="webkit"
)
→ Find tests failing specifically in webkit across multiple runs

Spin Up a Release + Run for a Sprint

1. create_release(projectId, name="Sprint 42", type="Iteration",
     startDate="2026-05-12", endDate="2026-05-26")
2. create_manual_run(projectId, name="Sprint 42 — Smoke",
     releaseId="<release _id from step 1>",
     environment="Staging", selectionMode="all", tags=["smoke","regression"])
3. list_run_test_cases(projectId, runId="RUN-N") → see the rows agents will assign

Assign Run Test Cases to Multiple Testers

1. list_run_test_cases(projectId, runId="RUN-1")
   → confirm the cases and grab caseKey for each
2. In parallel:
   update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-156",
     updates={ assigneeUserId: "[email protected]" })
   update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-157",
     updates={ assigneeUserId: "[email protected]" })
   …

Works against untested cases too — the row is auto-created on first edit.

Record Test Verdicts

update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-156",
  updates={ result: "Passed", assigneeUserId: "[email protected]" })
update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-157",
  updates={ result: "Failed" })

Pass either canonical ("passed") or display ("Passed") form — server normalizes. Valid result values: untested, passed, failed, blocked, skipped, retest.

Spin Up an Exploratory Session

create_session(projectId, name="Auth charter — May 12",
  mission="<p>find session-handling bugs around 2FA edge cases</p>",
  sessionType="Exploratory",
  assigneeUserId="[email protected]",
  estimate=60,
  releaseId="<optional release ref>")

Track Release Progress

get_release(projectId, releaseId="MS-12")
→ Returns rolled-up stats: run counts, test status breakdown across all runs
   linked to this release (and its descendants up to 3 levels deep).

Decision Trees

"Show me recent test runs"

list_testruns(projectId, by_time_interval="weekly", limit=20)

"Why is [test name] failing?"

debug_testcase(projectId, "[test name]")
→ Read debugging_prompt, analyze patterns
→ If more detail needed:
   get_testcase_details(projectId, testcase_name="[test name]",
     testrun_id="<latest fail>", steps_filter="failed_only")

"Show me all failed tests on main branch today"

list_testcase(projectId, by_branch="main", by_status="failed", by_time_interval="1d")

"Get details about test run #47"

get_run_details(projectId, counter=47)

"Find tests failing with timeout errors"

list_testcase(projectId, by_error_category="timeout_issues", by_status="failed", by_time_interval="weekly")

"Get details of test case [name] from run #47"

get_testcase_details(projectId, testcase_name="[name]", counter=47, steps_filter="failed_only")

"Search for tests with 'element not found' in error message"

get_testcase_details(projectId, by_error_message="element not found", by_status="failed")

"Create a test case for the login feature"

1. list_manual_test_suites(projectId)                     → find suite name
2. create_manual_test_case(projectId, title="...",
     suiteName="<exact suite name>", steps=[...])

"Update TC-123 to add a step"

1. get_manual_test_case(projectId, caseId="TC-123")       → get current steps
2. update_manual_test_case(projectId, caseId="TC-123",
     updates={ steps: [...existing + new step...] })

"Show me the releases on this project"

list_releases(projectId)

"Create a release for the upcoming sprint"

create_release(projectId, name="<sprint name>", type="Iteration",
  startDate="<ISO>", endDate="<ISO>")

"What runs are in release MS-12?"

list_manual_runs(projectId, releaseId="MS-12")

"Assign TC-156 to [email protected] in run RUN-1"

update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-156",
  updates={ assigneeUserId: "[email protected]" })

"Mark TC-157 as failed in run RUN-1"

update_run_test_case(projectId, runId="RUN-1", rtcRef="TC-157",
  updates={ result: "Failed" })

"Close the manual run RUN-1"

update_manual_run(projectId, runId="RUN-1", updates={ state: "done" })

(Or use the UI's close button — the dedicated close tool is not in v1.)

"Start an exploratory session"

create_session(projectId, name="<charter title>",
  mission="<HTML>", assigneeUserId="[email protected]")

Parameter Quick Reference

Time Interval Values

• '1d' — last 1 day
• '3d' — last 3 days
• 'weekly' — last 7 days
• 'monthly' — last 30 days
• '2024-01-01,2024-01-31' — custom date range (inclusive)

Status Values

• Automated test cases: 'passed', 'failed', 'skipped', 'flaky'
• Manual test cases: 'active', 'draft', 'deprecated'
• Manual runs / sessions lifecycle (status): 'active', 'closed'
• Run test case result (result / status): 'untested', 'passed', 'failed', 'blocked', 'skipped', 'retest'

Workflow State Values (the state field)

Project-configurable, but the canonical stored forms include:

• Sessions/runs: 'new', 'under_review', 'in_progress', 'on_hold', 'done', 'rejected'
• Pass display form ("Under review") or canonical ("under_review") — server normalizes.

Release Type Values

Project-configurable, canonical lowercase form. Common: 'iteration', 'major', 'minor', 'patch'. Display form ("Iteration") is normalized to canonical ("iteration").

Error Categories (for by_error_category)

• 'timeout_issues'
• 'element_not_found'
• 'assertion_failures'
• 'network_issues'

Browser Names

• 'chromium'
• 'firefox'
• 'webkit'

Runtime Filter Format

• '<60' — tests that ran in under 60 seconds
• '>100' — tests that ran over 100 seconds

Required Parameters Summary

Error Handling

Common Mistakes to Avoid

1. Calling any tool before `health()` — you won't have a projectId.
2. Using `testcase_name` alone in `get_testcase_details` without a run context — returns all historical executions, which can be large. Always pair with testrun_id or counter unless you want cross-run results.
3. Using `get_all=true` for large datasets — prefer filters. Only use get_all when the user genuinely needs everything.
4. Passing `steps` without specifying `testStepsDeclarationType` — Classic format is the default. If using Gherkin steps, explicitly set testStepsDeclarationType: "Gherkin".
5. Creating test cases without checking suite names — always call list_manual_test_suites() first; suiteName must be an exact match.
6. Ignoring the `debugging_prompt` in `debug_testcase` response — this field contains pre-formatted analysis instructions from the API. Always read and apply it when analyzing failures.
7. Sending `tags` as a comma-separated string in create/update payloads — they must be JSON arrays (["smoke","regression"]). The comma-separated form is only valid as a list-tool query filter.
8. Sending result as `"pass"` / `"fail"` — the canonical run-test-case result values are past tense: passed, failed. Display form ("Passed", "Failed") is fine, server normalizes — but "pass" is not in the vocabulary and will show a dull/grey badge.
9. Trying to assign or set a result by `tcm_rtc_…` for an "Untested" case — that record doesn't exist yet. Pass the caseKey ("TC-156") or the underlying test case \_id; the server auto-creates the row on first edit.
10. Looking for `assigneeUserId` on runs — runs don't have a single assignee; assignment is per-case via update_run_test_case. Sessions DO have a session-level assigneeUserId.
11. Mixing up `releaseId` and `parentReleaseId` — releaseId attaches a run/session to a release; parentReleaseId nests one release under another.
12. Bundling many per-case edits in `update_manual_run` — that tool only updates run metadata. For per-case verdicts, call update_run_test_case once per case (parallel is fine).

_For installation setup, see docs/INSTALLATION.md. For full API documentation, see docs/TOOLS.md._