Skip to main content
Glama
mungowang

jira-mcp

by mungowang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

create_test_run

Create a Zephyr Scale test run with its complete test case list and execution results in one call. Define the run composition at creation because it cannot be changed later via the public API.

Instructions

Create a test run / test cycle (POST /testrun). Pass the COMPLETE list of test cases in items now — API v1 limitation: a test run is IMMUTABLE — there is no PUT /testrun, so it cannot be renamed, moved or have cases added/removed through the public API; its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, new key) or the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key, require ZEPHYR_ALLOW_INTERNAL_API=true). Each item may also carry its execution result (status, executedBy, executionTime, actual dates, per-step scriptResults, …), which imports a run together with its results in one call; afterwards use the test result tools. A run folder is of type TEST_RUN. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. The run's own status is derived by the server from its item statuses and uses a different vocabulary from the execution statuses above ('Not Executed' / 'In Progress' / 'Done'). A run CANNOT be linked to Jira issues: issueLinks is rejected locally because the API has no such field on a run — link the issues on the test cases instead. Returns { key } of the new run.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesTest run name; it cannot be changed later through the public API
itemsNoTest cases to include — the ONLY place where the composition of a run can be set. Each entry requires testCaseKey and may carry the execution result fields of that item (status, environment, executedBy, assignedTo, comment, executionTime, actualStartDate, actualEndDate, customFields, issueLinks, scriptResults).
ownerNoOwner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user.
folderNoFull path of an existing TEST_RUN folder from the root starting with "/", e.g. "/Regression"
versionNoFree-text version label
iterationNoFree-text iteration label
issueLinksNoNOT SUPPORTED for test runs and rejected locally: the API has no such field on its run DTO, so any value (an empty array included) makes POST /testrun answer HTTP 500 and create nothing. Link them with link_issues_to_test_run (internal API) or on the test cases (create_test_case / update_test_case with issueLinks).
projectKeyNoJira project key, e.g. "PROJ"; defaults to ZEPHYR_DEFAULT_PROJECT_KEY when omitted
testPlanKeyNoTest plan to associate the run with, e.g. PROJ-P123
customFieldsNoCustom field values keyed by field name
plannedEndDateNoISO 8601 (passed through as-is)
plannedStartDateNoISO 8601, e.g. 2026-07-20T00:00:00Z (passed through as-is)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.5

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so richly: immutability, absence of PUT /testrun, items fixed at creation, status derived server-side from item statuses, the distinct status vocabularies, folder non-creation, and local rejection of issueLinks (HTTP 500). These are exactly the behavioral traits an agent needs before invoking a mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is dense and long, but front-loaded with the core action and the immutability constraint, and virtually every sentence encodes a real constraint (escape hatches, folder prerequisite, issueLinks rejection, return value). Slightly run-on in places, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter mutation tool with no output schema and no annotations, the description covers the composition rule, prerequisites, escape hatches, result-import path, and even the return shape ({ key }). An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema by stressing that items is the ONLY place a run's composition can be set and must be complete, and that each item may carry execution-result fields to import results in one call. The name parameter's immutability is also reinforced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Create a test run / test cycle') and even names the HTTP endpoint, making it instantly distinguishable from siblings like recreate_test_run_with_items, search_test_runs, and get_test_run.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool (pass the COMPLETE items list now, since the run is immutable) and routes the agent to concrete alternatives: recreate_test_run_with_items, and the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run with their precondition (ZEPHYR_ALLOW_INTERNAL_API=true). It also flags prerequisites (folder must exist, use create_folder first) and forbids linking issues on a run, redirecting to test cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools