This MCP server provides an interface for managing Zephyr Scale test assets on self-hosted Jira Server/Data Center via REST API v1, enabling AI agents to manage the full test lifecycle.
Test Cases: Create, read, update, search (TQL), delete, bulk create, add steps, set/replace script (STEP_BY_STEP, PLAIN_TEXT, BDD/Gherkin), link/unlink Jira issues, and get linked test cases.
Folders: Create folders with recursive parent auto-creation; rename folders by numeric ID.
Test Runs (Cycles): Create (with items and results), read, search (TQL), delete, get paginated results, and recreate with modified items (workaround for run immutability).
Test Results: Create new executions, update last result, bulk create, and get the latest result for a test case. Supports per-step results, environments, executors, custom fields, and issue links.
Test Plans: Full CRUD + search (TQL).
Attachments: Upload, list, and delete attachments for test cases, steps, runs, and results.
Automation: Upload automation results (Zephyr zip), upload Cucumber JSON results (zip), and download BDD feature files (zip).
Service & Utility: List/create environments, find Jira users by username/display name/email, and perform a health check.
Unofficial (opt-in): Get folder tree via internal API (requires ZEPHYR_ALLOW_INTERNAL_API=true).
Provides tools to manage test cases, folders, test runs, and test results in Zephyr Scale for Jira Server/Data Center. Supports creating, reading, updating, deleting test cases, adding test steps, searching via TQL, creating test runs with results, and managing environments and users.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zephyr-scale-mcp Create a test case for user login"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Zephyr Scale on self-hosted Jira Server / Data Center (formerly TM4J). It gives an AI agent — Claude Code, Claude Desktop, Cursor, any MCP client — 54 tools over your test management: test cases, folders, test cycles, executions, test plans, attachments and automation imports, through the Zephyr Scale REST API v1 at {JIRA_BASE_URL}/rest/atm/1.0.
npm: zephyr-scale-mcp · MCP Registry: io.github.vilaabo/zephyr-scale-mcp · Русская версия →
⚠️ Scope: Server / Data Center only. Zephyr Scale Cloud (API v2) and Zephyr Squad are different APIs and are out of scope — this server will not work against them.
Most Zephyr MCP servers target the Cloud API. If your Jira is on-premise you get the v1 API instead, and v1 has teeth: test runs are immutable after creation, folders cannot be listed, statuses are case-sensitive internal names, BDD scripts reject a Feature: header, and older plugin builds are missing whole endpoints. This server encodes that knowledge instead of leaving the agent to discover it one 400 at a time.
54 tools (42 public + 12 opt-in internal-API tools), each with a description that states the endpoint, the constraints a caller cannot guess, and the exact response shape.
Composite tools for the API's blind spots — add_test_steps merges steps by id (read → merge → write) so nothing is silently deleted; recreate_test_run_with_items works around run immutability and can carry the last results over; get_issue_test_coverage, get_test_run_summary, clone_test_case, move_test_cases_to_folder.
Degradation on older builds — automatic fallback when the paginated results endpoint is absent, and a per-item fallback when the bulk create endpoint is broken. Both were found on a real legacy instance, not in a changelog.
Plumbing that fails loudly — strict zod input validation, Retry-After-aware retries with exponential backoff, error messages carrying actionable hints, read-only mode, secrets kept out of logs and tool output.
1181 unit and contract tests (vitest + msw, no network) plus a gated end-to-end scenario against a real instance.
Related MCP server: mcp-zephyr-scale
Requirements: Node.js >= 20, Jira Server/DC with the Zephyr Scale plugin, and a Personal Access Token (Jira 8.14+) or a username/password pair.
Nothing to clone — the package is on npm. Claude Code:
claude mcp add zephyr-scale \
--env JIRA_BASE_URL=https://jira.example.com \
--env JIRA_PAT=<personal access token> \
--env ZEPHYR_DEFAULT_PROJECT_KEY=PROJ \
--env ZEPHYR_ALLOW_INTERNAL_API=true \
-- npx -y zephyr-scale-mcpClaude Desktop / any MCP client (claude_desktop_config.json, .mcp.json):
{
"mcpServers": {
"zephyr-scale": {
"command": "npx",
"args": ["-y", "zephyr-scale-mcp"],
"env": {
"JIRA_BASE_URL": "https://jira.example.com",
"JIRA_PAT": "<personal access token>",
"ZEPHYR_DEFAULT_PROJECT_KEY": "PROJ",
"ZEPHYR_ALLOW_INTERNAL_API": "true"
}
}
}
}git clone https://github.com/vilaabo/zephyr-scale-mcp.git
cd zephyr-scale-mcp
npm install
npm run build # -> dist/index.jsThen point the client at the build: "command": "node", "args": ["/path/to/zephyr-scale-mcp/dist/index.js"].
ZEPHYR_ALLOW_INTERNAL_API=trueis optional and recommended. It registers 12 extra tools that reach the things the public API cannot do at all: editing a test run in place — renaming or moving it (update_test_run) and adding or removing cases without changing its key (add_test_cases_to_run,remove_test_cases_from_run) — plus listing the folder tree (get_folder_tree), deleting folders (delete_folder), editing older executions (update_test_result_by_id) and reading the exact status names the API silently expects (get_status_options). These call the same undocumented/rest/tests/1.0endpoints the Jira UI itself uses; the vendor does not support them and they may differ or be absent on another Zephyr Scale version. Leave the flag off if that trade-off is not acceptable — the other 42 tools are unaffected.
Then ask the agent to run health_check. It verifies connectivity and credentials via GET /rest/api/2/myself and, when ZEPHYR_DEFAULT_PROJECT_KEY is set, that the Zephyr plugin answers on /rest/atm/1.0.
"Create the folder /Regression/Payments and add step-by-step test cases for the checkout flow described in this document."
"Find every Draft case in /Regression, review them, and set the ready ones to Approved."
"Create a cycle for sprint 42 with all smoke cases, then record the results from this report — step by step where the script has steps."
"Which test cases cover PROJ-123, and when did each of them last pass?" — traceability from the issue to its cases and their latest executions.
"Take this ZIP of Cucumber JSON reports and publish it as a new cycle in PROJ." — automation import; scenarios are matched to BDD cases by their @TestCaseKey=PROJ-T1 tag.
"Add two steps to PROJ-T55 after step 3." — existing steps and their ids survive.
"Recreate cycle PROJ-R7 with three more cases, keep the results, and delete the original."
Variable | Required | Default | Purpose |
| yes | — | Jira base URL without a trailing |
| no |
|
|
| with | — | Jira Server/DC Personal Access Token |
| with | — | Basic-auth credentials |
| no |
| Per-request timeout |
| no |
| Retries for GET and for any |
| no |
|
|
| no | — | Used whenever a tool is called without |
| no |
|
|
| no |
|
|
| no |
|
|
Two guarantees the tests cover: JIRA_PAT and JIRA_PASSWORD never appear in logs, tool output or error messages — in any encoding they can take on the way out: raw, JSON-escaped, or the base64 basic-auth token (error text carries the method and path only — never the query string, which may contain data) — and stdout is reserved for the MCP protocol, every log line goes to stderr. One deliberate exception: a secret shorter than six characters is left alone, because redacting it would corrupt unrelated output while protecting nothing; the server warns about it at startup.
Configuration is validated at startup: all problems are reported at once and the process exits with a non-zero code rather than starting half-configured.
54 tools. The 42 public ones are always registered; the 12 in the last group only with ZEPHYR_ALLOW_INTERNAL_API=true.
Tool | What it does |
| Create a case with a |
| Read a case, optionally narrowed by |
| TQL search with pagination; a query longer than 1500 characters is sent as |
| Partial update; |
| Insert steps at a position without losing the existing ones — read, merge by id, write back |
| Replace the whole script or change its format; destructive by design |
| Copy a case inside its project with fresh step ids; links, attachments and history are not copied |
| Bulk-move by explicit keys or by source folder; a failing case does not abort the rest |
| Permanent delete of the case, its script and its history |
| Create many cases in one call, with a per-case fallback on broken bulk endpoints |
| Bulk-link cases to Jira issues (additive) |
| Reverse lookup: issue → cases |
| Traceability report: issue → linked cases → latest execution of each |
Tool | What it does |
| Create a cycle with its complete item list — optionally with each item's execution result in the same call |
| Read a cycle including its items |
| TQL search — for runs only |
| Permanent delete of the cycle and all its results |
| Page through the executions of a cycle, with the legacy flat-endpoint fallback |
| Last execution per item: |
| The public workaround for run immutability: rebuild under a new key with cases added or removed, optionally carrying the last results over and deleting the original |
Tool | What it does |
| Append a new execution to a run item, including per-step |
| Partial update of the most recent execution of an item |
| Many executions for one cycle in a single call |
| The execution of a case with the greatest stored execution date, across all cycles — not necessarily the one recorded last |
Items that exist several times in a run (per environment or per assignee) are disambiguated with matchEnvironment / matchUserKey, sent as query parameters.
Tool | What it does |
| Create a plan; returns |
| Read a plan with its linked runs and issues |
| Partial update |
| Permanent delete |
| TQL search; the searchable field set varies by Zephyr Scale version |
Tool | What it does |
| Create a case / plan / cycle folder from a full path; with |
| Rename one folder segment by its numeric id (and optionally set its custom fields) |
Tool | What it does |
| Attach a local file to a case, a case step, a cycle, a result or a result step (multipart) |
| List the attachments of any of those targets; each record carries the id and url the other tools need |
| Save an attachment by id or by the url |
| Permanently delete one attachment by numeric id |
Tool | What it does |
| Publish a ZIP of results in Zephyr's custom JSON format; always creates a new cycle |
| Publish a ZIP of Cucumber JSON reports; scenarios are matched by their |
| Export BDD cases as a ZIP of |
Tool | What it does |
| Jira reachability, credentials, and whether the Zephyr plugin answers |
| The project's environments — the exact case-sensitive names results reference |
| Create an environment in the project |
| Resolve the Jira user key ( |
Registered only with ZEPHYR_ALLOW_INTERNAL_API=true. These call /rest/tests/1.0, the undocumented API behind the Jira UI. The vendor does not support it: endpoints may differ or be absent on another Zephyr Scale version, and a 404/405 from one of these tools means exactly that. Every request shape below was either captured from the Jira UI's own traffic or verified live against a real instance — never guessed. Errors from this layer carry a hint saying so.
Tool | What it does |
| Rename a cycle, move it to another folder (by numeric folder id) or change its planned dates in place, keeping its key, items and results. No |
| Append cases to an existing cycle in place; the key and the existing results survive |
| Remove items from an existing cycle in place — their whole execution history dies with them |
| Reorder the items of an existing cycle; a cycle already in the requested order makes no write at all |
| Link Jira issues to an existing cycle — the public API rejects an |
| Associate an existing cycle with a test plan after creation (the public API accepts |
| Delete individual executions by numeric id. The last execution of an item cannot be deleted |
| Edit any execution in an item's history, including older ones; |
| The full folder tree of a project with the numeric ids |
| The exact internal names of the project's execution statuses, case statuses or priorities — the values the public API silently ignores when they are wrong |
| Custom field definitions per entity type: names, types, required flags, options |
| Delete a folder by numeric id. What happens to a non-empty folder is version-specific — empty it first |
These are the constraints the server is built around. Every tool description repeats the ones relevant to it, so the agent sees them at call time.
Test runs are immutable. There is no PUT /testrun: a run cannot be renamed, moved, or have cases added or removed. Its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, produces a new key) or the internal update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key).
Folders are never created implicitly. create_test_case, create_test_run and create_test_plan fail with 400 on an unknown folder. Folders also cannot be listed through the public API, and renaming needs the numeric id returned by create_folder — or get_folder_tree with the internal API enabled.
owner / executedBy / assignedTo take a Jira user key (JIRAUSER10000), never a username or an e-mail. find_jira_user resolves it.
TQL is strict: spaces around operators are mandatory, string values go in double quotes, AND is the only connector (no OR), and folder paths start with /. Test runs are searchable by projectKey and folder only. For single/multi-choice custom fields = does not work — use IN.
Statuses, priorities and environments are case-sensitive internal names. Built-in statuses are shown localized in the UI (the label you see for Draft may be a translation) while custom ones use their literal names — get_status_options shows what the API actually expects. A wrong execution status is silently ignored by the public API.
A BDD script is the scenario body only — bare Given / When / Then / And / But lines. Text wrapped in Feature: / Scenario: is rejected with 400 Invalid BDD Script; the wrapper is generated on export.
STEP_BY_STEP steps are synchronized by id on PUT: a step without an id is created, a step with an id is updated, and every stored step missing from the list is deleted. Always send the complete final list with ids carried over from get_test_case — or let add_test_steps do the read-merge-write.
Deprecated fields are intentionally not accepted: use issueLinks instead of issueKey, actualEndDate instead of executionDate, executedBy instead of userKey.
All of the following was observed live on a real legacy Zephyr Scale Server instance and is covered by tests.
Cycle keys may use the -C prefix (PROJ-C34) instead of -R. Every run-key parameter takes the key as-is, so pass whatever your instance shows.
GET /testrun/{key}/testresults/page may not exist. get_test_run_results and get_test_run_summary fall back to the deprecated flat endpoint and paginate client-side, adding a note to the response. A run that genuinely does not exist still surfaces as a 404.
An overall status sent together with scriptResults is ignored. Send the step results first, then set the overall status with update_last_test_result.
POST /testcase/link-issues may answer 500. Link through update_test_case with issueLinks instead.
POST /testcase/bulk may answer HTTP 500 with an empty body for any payload while single creation works. create_test_cases_bulk falls back to creating the cases one by one — on any 5xx, and on a JSON 404 (which means "no such endpoint on this build", unlike the HTML 404 Jira serves when the plugin is absent) — and reports which ones succeeded (#1). Every other 4xx is a payload error and is not retried.
Posting a result for a case that is not among the run's items silently adds it to the run on this build; other builds reject the call with 400/404. The result tools document both.
The custom automation-results format is validated strictly. {"version": 1, "executions": [{"source", "result", "testCase": {"key"}}]} works; extra per-execution fields such as executionTime are rejected with Invalid Custom Format JSON file. Cucumber JSON reports work as-is when the scenario carries @TestCaseKey=PROJ-T1.
download_feature_files requires the tql query parameter — the API rejects the call without it.
The last execution of a run item cannot be deleted. delete_test_results rejects it; remove the item instead.
Custom fields may be absent entirely — the definitions endpoint then returns [].
npm run typecheck # tsc --noEmit, strict
npm test # 1181 unit + contract tests (vitest + msw), no network
npm run build # tsup -> dist/index.js
npm run smoke # 13 end-to-end tests, ZEPHYR_E2E=1, real instance requiredThe smoke scenario is skipped unless ZEPHYR_E2E=1. It needs a real JIRA_BASE_URL, credentials and a dedicated ZEPHYR_DEFAULT_PROJECT_KEY — it creates and deletes real entities and leaves /mcp-smoke-* folders behind, since the public API cannot delete folders.
src/
├── index.ts # bootstrap: config, tool registration, stdio transport
├── config.ts # environment validation
├── http.ts # fetch wrapper: auth, timeouts, retries, error normalization,
│ # multipart and binary bodies
├── schemas.ts # shared parameter schemas, field shapes, recurring description constants
├── toolkit.ts # defineTool(): strict zod input, read-only guard,
│ # JSON / isError response shaping, shared helpers
├── internal.ts # the UNOFFICIAL /rest/tests/1.0 layer: key -> id resolution,
│ # run-item plumbing, status resolution, error hints
├── runResults.ts # paged run results with the legacy fallback
├── log.ts # leveled logger, stderr only
└── tools/ # one module per tool family: testCases, testRuns, testResults,
# testPlans, folders, attachments, automation, misc,
# runMaintenance, resultsMaintenance, internalRefs
test/ # one test module per source module + negative contract tests
# and the gated smoke scenarioVersion 1.0.0. Tool names, parameter names and response shapes are a public contract from this release on and change only in a major version. See CHANGELOG.md.
Add steps to a STEP_BY_STEP test case without losing the existing ones. Composite operation: reads the test case, merges the new steps at the requested position while preserving existing step ids (so nothing is deleted), and writes the full list back. position: 'append' (default) adds after the last step, 'prepend' before the first, an integer inserts at that 0-based index (clamped to the current length). Only valid when the current script is STEP_BY_STEP or the test case has no script yet (a step-by-step script is then created); for a PLAIN_TEXT or BDD script use set_test_script instead. Returns { key, totalSteps }.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | New steps to insert, in order (no ids). A step carrying testCaseKey is a "Call to Test". | |
| position | No | 'append' (default), 'prepend', or a 0-based insertion index into the existing steps (clamped to the list length) | |
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully covers behavioral traits: composite operation (read, merge, write), position behavior (append/prepend/clamped integer), preservation of existing step ids, and return value { key, totalSteps }.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, front-loaded with purpose, efficient and no wasted words. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the operation (composite read-merge-write, position logic, script type restrictions) and lack of output schema, the description covers all necessary context completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining position options in detail, clarifying that steps carry no ids, and noting the 'Call to Test' special step.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Add steps to a STEP_BY_STEP test case without losing the existing ones.' It clearly distinguishes from sibling tools like set_test_script, which is for other script types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: only when the script is STEP_BY_STEP or no script yet. Provides a clear alternative: for PLAIN_TEXT or BDD scripts, use set_test_script instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone a Zephyr Scale test case within its project — composite read+create: reads the source test case and creates a copy with the same objective, precondition, status, priority, owner, labels, custom fields, parameters and (by default) test script. Step ids are never carried over (the copy gets fresh steps), and execution history/attachments are NOT copied. The copy's name defaults to ' (copy)'; folder defaults to the source folder. Returns { key, url, sourceKey }.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the copy (defaults to '<source name> (copy)') | |
| folder | No | Folder path for the copy, starting with '/' (defaults to the source folder; must exist) | |
| testCaseKey | Yes | Key of the SOURCE test case, e.g. PROJ-T123 | |
| includeScript | No | Copy the test script too (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and excels: it discloses the composite operation, what is copied (objective, precondition, status, etc.), what is not (step ids, execution history, attachments), defaults for name and folder, and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly verbose; however, every sentence adds value and the structure is logical, starting with the main action then detailing specifics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a clone tool with 4 parameters and no output schema, the description is fully complete: it explains the return format ({ key, url, sourceKey }), covers all behaviors, and provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains that folder must exist, name defaults to '<source name> (copy)', includeScript defaults true, and provides context for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones a Zephyr Scale test case within its project, distinguishing it from siblings like create_test_case or update_test_case by specifying it's a composite read+create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use the tool and explicitly lists what is not copied (execution history, attachments), but could be more explicit about when not to use it or point to alternative tools for copying attachments/history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Zephyr Scale folder for test cases, test plans or test runs (test cycles). name is the FULL path from the root and must start with "/", e.g. "/Regression/Payments". With recursive=true (default) missing parent folders are created automatically: if the API rejects the full path with 400, every parent prefix is created from the root and the full path is retried. Folders are NOT auto-created by create_test_case / create_test_run — create them with this tool first. The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder needs it (otherwise the id can only be found in the Jira UI).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Full folder path from the root, starting with "/", e.g. "/Regression/Payments" | |
| type | Yes | Folder kind: TEST_CASE (test case folders), TEST_PLAN (test plan folders) or TEST_RUN (test cycle folders) | |
| recursive | No | Create missing parent folders automatically on a 400 response (default true). Handled client-side, never sent to the API. | |
| projectKey | No | Jira project key; defaults to ZEPHYR_DEFAULT_PROJECT_KEY |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, description fully covers behavior: recursive handled client-side, auto-creation on 400, no auto-creation by other tools, and API limitation (cannot list folders). Discloses that id must be saved for later use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence adds value. It is well-structured: purpose first, then parameter details, then behavioral notes. Could be slightly more concise, but justified given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters (2 required), the description covers all necessary context: usage, parameter semantics, behavioral quirks, dependencies (rename_folder). Complete guidance for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds significant context: explains name must be full path from root, recursive default true and client-side handling, projectKey defaults to environment variable. This goes beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Zephyr Scale folder for test cases, test plans, or test runs. It specifies the resource and action, and distinguishes from sibling tools like create_test_case and create_test_run by noting they do not auto-create folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: when to use (before test case/run creation), name format (absolute path starting with /), recursive behavior, and hierarchical name convention. Also advises keeping the numeric id since the API cannot list folders, and notes rename_folder needs it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Zephyr Scale test case (POST /testcase). Returns { key, url } with a key like PROJ-T123. Constraints: the folder, if given, MUST already exist — the API never creates folders (use create_folder first); status and priority are case-sensitive internal names (defaults 'Draft'/'Approved'/'Deprecated' and 'High'/'Normal'/'Low'; instances may define custom ones); owner is a Jira user key like JIRAUSER10000 (resolve with find_jira_user); estimatedTime is in milliseconds. testScript formats: STEP_BY_STEP with steps (a step carrying testCaseKey is a 'Call to Test' that inlines another test case), PLAIN_TEXT with text, or BDD with text holding ONLY Gherkin step lines (Given/When/Then/And/But, stored verbatim) — do NOT include 'Feature:'/'Scenario:' headers, the API rejects them with 400 'Invalid BDD Script'.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Test case name | |
| owner | No | Owner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| folder | No | Full folder path from the root starting with "/", e.g. "/Regression/Payments". The folder MUST already exist (create it with create_folder). | |
| labels | No | Labels; the API replaces spaces with underscores | |
| status | No | Test case status. Defaults: 'Draft', 'Approved', 'Deprecated' — case-sensitive; instances may define custom ones. | |
| priority | No | Priority. Defaults: 'High', 'Normal', 'Low' — case-sensitive; instances may define custom ones. | |
| component | No | Name of a Jira component of the project | |
| objective | No | Objective (HTML allowed) | |
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| parameters | No | Test case parameters: { variables: [{name, type: FREE_TEXT | DATA_SET, dataSet?}], entries: [{<variable>: <value>}] } | |
| projectKey | No | Jira project key; defaults to ZEPHYR_DEFAULT_PROJECT_KEY | |
| testScript | No | Test script. STEP_BY_STEP: {type, steps: [{description?, testData?, expectedResult?, testCaseKey?}]}; PLAIN_TEXT/BDD: {type, text}. | |
| customFields | No | Custom field values keyed by field name | |
| precondition | No | Precondition (HTML allowed) | |
| estimatedTime | No | Estimated duration in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: return value format, folder creation avoidance, case sensitivity of status/priority, owner key format, estimatedTime unit, and API rejection of invalid BDD scripts. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single long paragraph but front-loaded with purpose. It packs much necessary detail without excessive verbosity. Some redundancy with schema descriptions could be trimmed, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (15 params, nested objects) and no output schema, the description covers return values, constraints, error responses, and parameter specifics. It addresses all likely questions an agent might have.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description adds extra clarity on testScript formats (e.g., 'Call to Test', BDD restrictions) and relationships between parameters like folder and owner. This adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Create a Zephyr Scale test case' specifying the verb and resource, and includes the HTTP method and return format. It clearly distinguishes from siblings like clone_test_case, update_test_case, and create_folder by referencing them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit constraints and prerequisites: folder must exist (use create_folder), owner must be a Jira user key (resolve with find_jira_user), and warns against incorrect BDD format. While it doesn't explicitly say when not to use this tool or list alternatives, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Zephyr Scale test plan (POST /testplan). Returns { key } with a key like PROJ-P123 (no UI url — it cannot be built reliably for test plans). Constraints: the folder, if given, MUST be an existing folder of type TEST_PLAN — the API never creates folders (use create_folder with type TEST_PLAN first); status is a case-sensitive internal name (defaults 'Draft'/'Approved'/'Deprecated'; instances may define custom ones); owner is a Jira user key like JIRAUSER10000 (resolve with find_jira_user).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Test plan name | |
| owner | No | Owner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| folder | No | Full TEST_PLAN folder path from the root starting with "/", e.g. "/Releases/2026". The folder MUST already exist — create it first with create_folder using type TEST_PLAN. | |
| labels | No | Labels; the API replaces spaces with underscores | |
| status | No | Test plan status. Defaults: 'Draft', 'Approved', 'Deprecated' — case-sensitive; instances may define custom ones. | |
| objective | No | Objective (HTML allowed) | |
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| projectKey | No | Jira project key; defaults to ZEPHYR_DEFAULT_PROJECT_KEY | |
| customFields | No | Custom field values keyed by field name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return format ({ key }), notes that no UI URL can be built, and lists constraints (folder existence, status case-sensitivity). However, it does not mention idempotency, rate limits, or potential side effects beyond resource creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action and return, then constraints. It is informative but slightly verbose with multiple parenthetical asides. Every sentence adds value, though some could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return format. It covers creation constraints, parameter special cases, and provides necessary context for a complex creation tool with 9 parameters and nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema: it clarifies that folder MUST exist (schema only says 'full path'), status is case-sensitive (schema only lists defaults), and owner must be a resolved Jira user key (schema hints but description directs to find_jira_user).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a Zephyr Scale test plan' and specifies the HTTP method (POST /testplan). It distinguishes this tool from siblings like 'create_folder' and 'find_jira_user' by referencing them in constraints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: folder must already exist (ties to create_folder), status is case-sensitive and has defaults, owner is a Jira user key (ties to find_jira_user). It tells when to use alternatives (create_folder first) and includes constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create NEW executions (test results) for several test cases of one test run in a single call. Every element's testCaseKey must already be one of the run's items — the run's item list is fixed when the run is created and this tool cannot extend it. In each element only the fields you pass are sent. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. Durations (executionTime) are in milliseconds; dates are ISO 8601. scriptResults record per-step outcomes as { index (0-based), status, comment? }. matchEnvironment / matchUserKey apply to the whole batch and disambiguate run items when the same test case is included in the run several times. Returns the array of created result ids.
| Name | Required | Description | Default |
|---|---|---|---|
| results | Yes | One entry per result to create; each targets an existing run item by testCaseKey | |
| testRunKey | Yes | Test run (cycle) key, e.g. PROJ-R123 | |
| matchUserKey | No | Run-item selector, sent as the 'userKey' QUERY parameter (never in the body): when the same test case is included in the run as several items, targets the item by its executor's Jira user key (e.g. 'JIRAUSER10000'). | |
| matchEnvironment | No | Run-item selector, sent as the 'environment' QUERY parameter (never in the body): when the same test case is included in the run as several items, targets the item with this environment (case-sensitive). Distinct from the 'environment' body field, which sets the environment recorded on the result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries full burden. It discloses creation behavior, immutability of run items, optional field sending, default statuses, units (ms for time, ISO 8601 for dates), scriptResults format, and batch-level disambiguation via matchEnvironment/matchUserKey as query parameters. Lacks error case disclosure but is otherwise thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-organized paragraph of around 150 words. It front-loads the main purpose and every sentence provides necessary detail without redundancy. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (bulk creation, multiple parameters, nuanced behavior), the description is largely complete: it covers prerequisites, default statuses, units, date format, per-step results, disambiguation, and return value. Lack of error handling or permission notes is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond schema by clarifying the batch application of matchEnvironment/matchUserKey as query parameters, the requirement that testCaseKey be a run item, and the format of scriptResults. It enriches understanding of parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create NEW executions (test results) for several test cases of one test run in a single call.' It specifies the verb (create), resource (executions/test results), and scope (bulk), distinguishing it from single-creation sibling create_test_result and other bulk tools for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use: for bulk creation of results within a single run, with the constraint that testCaseKeys must already be run items. It implies exclusion of single-result operations but does not explicitly name alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Zephyr Scale test run (test cycle; key like PROJ-R123). IMPORTANT API v1 limitation: a test run is IMMUTABLE after creation — there is no PUT /testrun/{key}. A run cannot be renamed, moved to another folder, and test cases cannot be added to or removed from it later; the set of items is fixed ONLY at creation time. The run status is computed automatically from the statuses of its items and cannot be set directly. Therefore pass the COMPLETE list of test cases in items now — each item may also carry full execution result fields (status, executedBy, executionTime, actualStartDate/actualEndDate, per-step scriptResults, etc.), which allows importing a run together with its results in a single call. To record or update executions of the included items afterwards, use the test result tools. Item/result statuses default to 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' (case-sensitive; instances may define custom ones).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Test run name (cannot be changed after creation) | |
| items | No | Test cases to include in the run — this is the ONLY place where the run composition can be set. Each item requires testCaseKey and may carry full execution result fields (status, environment, executedBy, assignedTo, comment, executionTime, actualStartDate, actualEndDate, customFields, issueLinks, scriptResults). | |
| owner | No | Owner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| folder | No | Full path of a TEST_RUN folder starting with "/", e.g. "/Regression". The folder MUST already exist (create it with create_folder, type TEST_RUN); it is not created automatically. | |
| version | No | ||
| iteration | No | ||
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| projectKey | No | Jira project key; defaults to ZEPHYR_DEFAULT_PROJECT_KEY | |
| testPlanKey | No | Key of the test plan to associate the run with, e.g. PROJ-P123 | |
| customFields | No | Custom field values keyed by field name | |
| plannedEndDate | No | ISO 8601 (passed through as-is) | |
| plannedStartDate | No | ISO 8601, e.g. 2026-07-20T00:00:00Z (passed through as-is) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: immutability, automatic status computation, case-sensitive status values, and the inability to rename or move. It also explains the default statuses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear 'IMPORTANT' section and front-loads critical limitations. However, it is somewhat verbose; a slightly more concise version would improve readability without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, nested objects, no output schema), the description is comprehensive. It covers creation constraints, parameter details, defaults, and references sibling tools, leaving minimal gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), but the description adds meaningful context beyond the schema, such as the requirement for Jira user keys, folder existence precondition, and case sensitivity of statuses. This adds value while the schema already documents most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Zephyr Scale test run, specifying the key format (PROJ-R123). It distinguishes from siblings by explaining that after creation, updates to executions should use test result tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the API v1 limitation: the test run is immutable after creation. It advises passing the complete list of items now and points to test result tools for later updates, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a Zephyr Scale test plan (DELETE /testplan/{testPlanKey}). This cannot be undone. Returns { deleted: true, key }.
| Name | Required | Description | Default |
|---|---|---|---|
| testPlanKey | Yes | Test plan key, e.g. PROJ-P123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds 'This cannot be undone' and return value, going beyond the destructiveHint annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear action, endpoint, and consequence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key points: deletion, irreversibility, return value. Could mention permissions or side effects but adequate for low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage with example (PROJ-P123). Tool description adds no further parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (permanently delete) and resource (test plan), with the HTTP endpoint. Distinct from sibling tools like delete_test_case or delete_test_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for permanent removal but lacks explicit guidance on when to use vs alternatives or when not to use (e.g., if test plan is linked to other data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a Zephyr Scale attachment to a local file. Address it either by attachmentId (from list_attachments or an upload response) or by the exact url field that list_attachments returns — pass exactly one of the two. Note: Zephyr Scale serves attachment content from /rest/tests/1.0/attachment/{id}; that is the URL the official list endpoint itself hands out, so this tool follows it. For safety, a passed url must point at the configured Jira host — credentials are never sent elsewhere. The file is written to outputPath on the machine running this MCP server (the parent directory must exist). Returns { savedTo, bytes }.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Exact download url as returned by list_attachments; must be on the configured Jira host | |
| outputPath | Yes | Local path to write the file to (the parent directory must exist) | |
| attachmentId | No | Numeric attachment id (from list_attachments or an upload response) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavioral traits: mutual exclusion of parameters, URL safety check, file writing prerequisites, and return format. Adds value beyond the readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: first sentence states purpose, subsequent sentences detail usage and constraints. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers all necessary aspects: action, parameters, safety, output format, and prerequisites. No gaps given the tool's simplicity and presence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by explaining mutual exclusivity of attachmentId and url, and providing safety context. Schema coverage is 100% but description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Download a Zephyr Scale attachment to a local file', specifying verb and resource. Differentiates from siblings like upload_attachment and delete_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear instructions on addressing by attachmentId or url, safety constraints, and file writing requirements. Does not explicitly compare to alternatives but gives sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traceability report for a Jira issue: lists the Zephyr Scale test cases linked to the issue together with the latest execution result of each (composite read-only: GET /issuelink/{issueKey}/testcases, then per case GET /testcase/{key} and GET /testcase/{key}/testresult/latest). lastResult is null when the case has never been executed. Makes up to 2 HTTP calls per case — cap the volume with maxCases (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | Jira issue key, e.g. PROJ-123 | |
| maxCases | No | Maximum number of linked cases to expand (default 50) | |
| includeLastResults | No | Fetch the latest execution result per case (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses composite nature (up to 2 HTTP calls per case), default cap (50), and that lastResult is null when never executed. Confirms readOnlyHint annotation. This adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose, second explains technical details and caveats. No redundant information, front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (composite, multiple API calls) and no output schema, the description fully covers behavior: null results, volume cap, default behavior, and composite nature. It is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining default values (maxCases=50, includeLastResults=true) and the purpose of each parameter in context of the composite operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a traceability report listing linked test cases and their latest execution results. It distinguishes from the sibling 'get_test_cases_linked_to_issue' by including results and calling it a composite read-only operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining test coverage with results, and warns about the number of HTTP calls, advising to cap volume with maxCases. However, it does not explicitly state when not to use it (e.g., if only list is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the latest (most recent) execution result of a test case across ALL test runs (cycles). Use get_test_run_results to read the results of one specific run instead.
| Name | Required | Description | Default |
|---|---|---|---|
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, which is consistent. The description adds behavioral context: it returns the latest result across all runs, implying a broad scope. No destructive effects are mentioned, but none are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately states the core functionality, and includes a useful comparison. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no output schema, read-only operation), the description fully addresses what the agent needs to know. It covers purpose, scope, and alternative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema alone provides full coverage (100%) with a clear description for 'testCaseKey'. The tool description adds no extra semantic detail beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the most recent execution result across all test runs. It specifies the verb 'get', the resource 'execution result', and distinguishes from the sibling tool 'get_test_run_results', which targets a specific run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with the sibling tool 'get_test_run_results', telling the agent when to use each. It could mention other alternatives, but the provided guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Zephyr Scale test case by key (GET /testcase/{testCaseKey}). Optionally restrict the payload with fields. STEP_BY_STEP scripts come back with per-step ids — those ids are required to edit steps safely via update_test_case (add_test_steps handles them automatically).
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Return only these fields, e.g. ["key","name","status","testScript"]; sent to the API as a comma-separated list | |
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and description confirms read operation. Adds context about per-step ids and safe editing, going beyond the annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with primary action. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description hints at return values (per-step ids). Covers key usage context. Could briefly mention default return structure if fields not specified, but minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds that fields are sent as comma-separated list and that the parameter is optional, providing extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read a Zephyr Scale test case by key' with the API endpoint. Distinguishes from siblings like search_test_cases and update_test_case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains that fields parameter is optional and notes that per-step ids are required for safe editing via update_test_case. Provides helpful cross-tool context but lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Zephyr Scale test plan by key (GET /testplan/{testPlanKey}). Optionally restrict the payload with fields. The response includes linked test runs and issues when present.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Return only these fields, e.g. ["key","name","status"]; sent to the API as a comma-separated list | |
| testPlanKey | Yes | Test plan key, e.g. PROJ-P123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description confirms a read operation. It adds useful behavioral details about optional field restriction and response contents (linked test runs and issues).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence includes the HTTP method and endpoint, front-loading the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no output schema, the description covers the main functionality, options, and response content. It could mention that the response is a JSON object, but the tool's HTTP nature implies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters adequately. The description only briefly mentions optional field restriction, adding little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a test plan by key, uses HTTP GET, and specifies the endpoint. It distinguishes from siblings like search_test_plans which list multiple plans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives like search_test_plans or get_test_run. It does not state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Zephyr Scale test run (test cycle) by key, including its items. IMPORTANT API v1 limitation: a test run is IMMUTABLE after creation — there is no PUT /testrun/{key}. A run cannot be renamed, moved to another folder, and test cases cannot be added to or removed from it later; the set of items is fixed ONLY at creation time. The run status is computed automatically from the statuses of its items and cannot be set directly. Use get_test_run_results to page through the execution results of the run.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Restrict the response to these fields (serialized comma-separated), e.g. ["key", "name", "status"] | |
| testRunKey | Yes | Test run key, e.g. PROJ-R123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: immutability, absence of PUT endpoint, inability to rename/move/add/remove items, automatic status computation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-organized paragraphs: first gives core purpose, second details limitations and alternatives. Efficient with no redundant text. Could be slightly more concise, but structure is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 2 parameters and no output schema, the description provides all necessary context: what it does, limitations, and related tool. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions (100% coverage). The description adds valuable context about the return including items and status computation, which supplements the schema. Slightly above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('Zephyr Scale test run by key'), and the scope ('including its items'). It distinguishes this tool from siblings like get_test_run_results and create_test_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (to read a test run by key) and when not to (immutable after creation, no PUT). Provides alternative: use get_test_run_results for execution results. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the attachments of a Zephyr Scale test case, test run (cycle) or test result — optionally of a single step (GET /testcase/{key}[/step/{i}]/attachments, /testrun/{key}/attachments or /testresult/{id}[/step/{i}]/attachments). Addressing: target 'test_case' requires testCaseKey (stepIndex optional to address a specific step); target 'test_run' requires testRunKey (no step addressing — the API has no per-step endpoint for runs); target 'test_result' requires testResultId (stepIndex optional). Pass ONLY the identifier that matches the chosen target. Returns the attachment list as reported by the API; the numeric ids can be passed to delete_attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Kind of entity the attachment belongs to: test_case, test_run or test_result | |
| stepIndex | No | 0-based step index to address a single step instead of the whole entity (targets 'test_case' and 'test_result' only) | |
| testRunKey | No | Test run (cycle) key, e.g. PROJ-R123 — required when target is 'test_run' | |
| testCaseKey | No | Test case key, e.g. PROJ-T123 — required when target is 'test_case' | |
| testResultId | No | Numeric test result id — required when target is 'test_result'. Result ids are returned by create_test_result / update_last_test_result / get_test_run_results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint: true; the description confirms it's a read operation. Adds context about the return format ('list as reported by the API') and that ids are usable for deletion. No pagination or error details, but adequate for the complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense paragraph with clear front-loading of purpose followed by systematic breakdown of targets. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects for a list tool with multiple target types and step options. Mentions return value and downstream use of ids. No output schema, but description is self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the input schema: explains the addressing logic per target, where stepIndex is allowed, and where testResultId originates. Schema coverage is 100%, yet description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List the attachments') and the resources (test case, test run, test result, optionally per step). It differentiates itself from siblings like delete_attachment and download_attachment by specifying exactly what it lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use each target, which parameters are required ('Pass ONLY the identifier that matches the chosen target'), and how stepIndex applies. Mentions a sibling (delete_attachment) for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename an existing Zephyr Scale folder by its numeric id (and optionally update its custom fields). name is the new name of that single folder segment, NOT a path — it must not contain "/" or "". The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder needs it (otherwise the id can only be found in the Jira UI).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New folder name (a single segment without "/" or "\") | |
| folderId | Yes | Numeric folder id, as returned by create_folder (the API cannot list folders) | |
| customFields | No | Custom field values keyed by field name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true, which the description does not contradict. Beyond that, the description discloses the name format constraint ('must not contain "/" or "\"') and explains why the numeric id is necessary (API cannot list folders). This adds behavioral context beyond the idempotency hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states purpose and key parameters, second clarifies the name constraint, third explains the id sourcing limitation. No fluff, front-loaded with essential information. Every sentence serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameter constraints and a critical API limitation. However, it does not mention the return value or success/error behavior. Given no output schema, a brief note on expected output would improve completeness. Still, it provides enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description reinforces the name parameter's constraint ('single folder segment, NOT a path') and adds critical context about the folderId's origin ('as returned by create_folder'). This extra context goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb-resource pairing ('Rename an existing Zephyr Scale folder') and clearly identifies the required identifier ('numeric id'). It also distinguishes from sibling tools by noting the dependency on create_folder, which is the only way to obtain the id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the prerequisite: 'keep the numeric id returned by create_folder — rename_folder needs it (otherwise the id can only be found in the Jira UI).' This guides the agent on when to use this tool (after creation) and provides a critical constraint. Though alternatives are not listed, no sibling tool performs renaming, so no exclusion is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Zephyr Scale test plans with a TQL query (GET /testplan/search). Returns { startAt, maxResults, count, isLast, values }; isLast is the heuristic count < maxResults. Paginate with startAt (default 0) and maxResults (default 50; the API server-side default is 200). TQL syntax is strict: spaces around operators are mandatory, string values go in double quotes, and the only logical connector is AND (no OR). Commonly supported test plan fields are projectKey, folder, name and status (e.g. projectKey = "PROJ" AND status = "Approved") — the exact set varies by Zephyr Scale version.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | TQL query, e.g. projectKey = "PROJ" AND folder = "/Releases" | |
| fields | No | Return only these fields, e.g. ["key","name","status"]; sent to the API as a comma-separated list | |
| startAt | No | 0-based index of the first result to return (default 0) | |
| maxResults | No | Maximum number of results to return (default 50; the API server-side default is 200) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals the return structure with isLast heuristic, pagination behavior (defaults and server-side limit), and strict TQL syntax rules (spaces, quotes, AND only). It also notes field variability by Zephyr version, providing essential behavioral context for correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 6 sentences, front-loaded with the main purpose and endpoint. Every sentence provides essential information: purpose, return structure, pagination, TQL syntax, and common fields. No redundant or misleading statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully explains the return value structure. It covers pagination, TQL syntax, and field constraints. With 4 parameters all documented, and no nested objects or enums, the description is complete for a search tool. The sibling tools confirm this is a read operation, and the description aligns perfectly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for all 4 parameters. The description adds deeper meaning: explains the query parameter as TQL with syntax examples, clarifies the fields parameter is sent as comma-separated, and reveals the API server-side default for maxResults (200) which goes beyond the schema's stated default (50). This extra context justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches Zephyr Scale test plans using a TQL query via the GET /testplan/search endpoint. It distinguishes from sibling tools like search_test_cases and search_test_runs by specifying 'test plans' and providing detailed TQL syntax rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, including pagination parameters and TQL syntax rules. While it doesn't explicitly state when not to use or name alternatives, the tool name and context signals make it obvious for searching test plans. The guidance on commonly supported fields adds practical value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a test case's ENTIRE script or change its format (PUT /testcase/{testCaseKey} with a full testScript). WARNING — destructive: switching a STEP_BY_STEP script to PLAIN_TEXT or BDD irreversibly deletes all existing steps, and a STEP_BY_STEP replacement deletes every existing step omitted from the list. Pass text for PLAIN_TEXT/BDD (for BDD only Gherkin step lines Given/When/Then/And/But, stored verbatim — no 'Feature:'/'Scenario:' headers, the API rejects them); pass steps for STEP_BY_STEP. Returns { key, url }.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Script body — required for PLAIN_TEXT and BDD (Gherkin step lines only, no Feature:/Scenario: headers), not allowed for STEP_BY_STEP | |
| type | Yes | New script format | |
| steps | No | Complete final list of steps — required for STEP_BY_STEP, not allowed otherwise. Existing steps omitted here are deleted; keep their ids (from get_test_case) to update them in place. | |
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond destructiveHint annotation, description details what gets destroyed (omitted steps, format switch) and specific constraints (BDD rejects headers). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise paragraph with front-loaded purpose. Every sentence adds essential information. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: destructive warning, parameter conditions, return value ({ key, url }). No output schema needed. Complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds critical context: text not allowed for STEP_BY_STEP, steps not allowed otherwise, BDD restrictions, and verbatim storage. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it replaces the entire script or changes format, with specific HTTP method and endpoint. Distinguishes from siblings like add_test_steps and update_test_case by focusing on script replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns about destructive behavior, states when to use (replace/change format), and gives format-specific instructions. Implicitly suggests using add_test_steps for incremental changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the LAST (most recent) test result of a run item. Partial update: ONLY the fields you pass are changed, everything else is preserved — do not send fields you do not want to modify. Older executions cannot be targeted; to record a new execution use create_test_result. The test case must already be one of the run's items (the run's composition is fixed at creation). Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. Durations (executionTime) are in milliseconds; dates are ISO 8601. scriptResults record per-step outcomes as { index (0-based), status, comment? }. If the same test case is included in the run as several items, disambiguate with matchEnvironment / matchUserKey.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Execution status. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. | |
| comment | No | Comment (HTML allowed) | |
| version | No | ||
| iteration | No | ||
| assignedTo | No | Assignee. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| executedBy | No | Executor. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| testRunKey | Yes | Test run (cycle) key, e.g. PROJ-R123 | |
| environment | No | Environment name as configured in the project (case-sensitive), e.g. "Chrome" | |
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 — must already be one of the run's items | |
| customFields | No | Custom field values keyed by field name | |
| matchUserKey | No | Run-item selector, sent as the 'userKey' QUERY parameter (never in the body): when the same test case is included in the run as several items, targets the item by its executor's Jira user key (e.g. 'JIRAUSER10000'). | |
| actualEndDate | No | ISO 8601 | |
| executionTime | No | Execution duration in milliseconds | |
| scriptResults | No | Per-step results (STEP_BY_STEP scripts) | |
| actualStartDate | No | ISO 8601, e.g. 2026-07-20T14:00:00Z | |
| matchEnvironment | No | Run-item selector, sent as the 'environment' QUERY parameter (never in the body): when the same test case is included in the run as several items, targets the item with this environment (case-sensitive). Distinct from the 'environment' body field, which sets the environment recorded on the result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: partial update (only sent fields change), targeting only the latest result, requirement for run composition, and nuances like matchUserKey/matchEnvironment being query parameters. Annotations only provide idempotentHint, so the description carries the full behavioral burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and structured logically. It covers all necessary details without being overly verbose, though a slightly tighter structure could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (17 parameters, nested objects, query parameters), the description is largely complete. It covers update semantics, limitations, data types, and disambiguation. The lack of return value description is a minor gap, but the tool's context (update) makes the return somewhat predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (88%), but the description adds value by explaining partial update semantics, duration units, date format, scriptResults structure, and special parameter behavior (e.g., query parameters vs body). This goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'update the LAST (most recent) test result of a run item' with a clear verb and resource. It distinguishes from sibling 'create_test_result' by noting that older executions cannot be targeted. This provides precise purpose differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (update last result) and when not (use create_test_result for new execution). Also notes precondition that test case must already be a run item, and provides disambiguation hints for duplicate items. This is comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a Zephyr Scale test case (PUT /testcase/{testCaseKey}). PARTIAL update: only the fields you pass are changed; omitted fields keep their current values — never send empty placeholders. projectKey cannot be changed. STEP_BY_STEP step synchronization: when testScript.steps is passed, steps are matched by id — a step WITHOUT an id is CREATED, a step WITH an id is UPDATED, and any existing step MISSING from the list is DELETED. Therefore always pass the COMPLETE final list of steps, carrying over the ids of steps to keep (read them with get_test_case). To merely add steps, prefer add_test_steps, which performs that read-merge-write safely. Returns { key, url }.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Test case name | |
| owner | No | Owner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| folder | No | Full folder path from the root starting with "/", e.g. "/Regression/Payments". The folder MUST already exist (create it with create_folder). | |
| labels | No | Labels; the API replaces spaces with underscores | |
| status | No | Test case status. Defaults: 'Draft', 'Approved', 'Deprecated' — case-sensitive; instances may define custom ones. | |
| priority | No | Priority. Defaults: 'High', 'Normal', 'Low' — case-sensitive; instances may define custom ones. | |
| component | No | Name of a Jira component of the project | |
| objective | No | Objective (HTML allowed) | |
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| parameters | No | Test case parameters: { variables: [{name, type: FREE_TEXT | DATA_SET, dataSet?}], entries: [{<variable>: <value>}] } | |
| testScript | No | Test script. STEP_BY_STEP: {type, steps: [{description?, testData?, expectedResult?, testCaseKey?}]}; PLAIN_TEXT/BDD: {type, text}. | |
| testCaseKey | Yes | Test case key, e.g. PROJ-T123 | |
| customFields | No | Custom field values keyed by field name | |
| precondition | No | Precondition (HTML allowed) | |
| estimatedTime | No | Estimated duration in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial update (only passed fields changed), step sync with id-based matching, immutability of projectKey, and return format {key, url}. Despite idempotentHint annotation, the description adds critical behavioral context not available from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: partial update behavior, step sync logic, alternative tool recommendation, and return value. The most critical information (partial update, step behavior) is front-loaded, and the description is dense yet clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects for a complex 15-parameter tool: partial update semantics, step synchronization (with id-based rules), immutability constraints, and return value. No output schema exists, but the description provides the essential return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover 100% of parameters, but the description adds valuable usage tips like 'never send empty placeholders', 'projectKey cannot be changed', and the step synchronization rule. This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a Zephyr Scale test case via PUT /testcase/{testCaseKey}, and distinguishes it from siblings like add_test_steps and set_test_script. The verb 'Update' and resource 'test case' are specific, and the partial update detail differentiates it from full replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use add_test_steps instead for simple step additions, and explains the step synchronization behavior (create/update/delete based on id). Provides clear context for when this tool is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a Zephyr Scale test plan (PUT /testplan/{testPlanKey}). PARTIAL update: only the fields you pass are changed; omitted fields keep their current values — never send empty placeholders. projectKey cannot be changed. The same constraints as create_test_plan apply: the folder must be an existing TEST_PLAN folder, status is case-sensitive, owner is a Jira user key. Returns { key }.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Test plan name | |
| owner | No | Owner. Jira *user key* (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. | |
| folder | No | Full TEST_PLAN folder path from the root starting with "/", e.g. "/Releases/2026". The folder MUST already exist — create it first with create_folder using type TEST_PLAN. | |
| labels | No | Labels; the API replaces spaces with underscores | |
| status | No | Test plan status. Defaults: 'Draft', 'Approved', 'Deprecated' — case-sensitive; instances may define custom ones. | |
| objective | No | Objective (HTML allowed) | |
| issueLinks | No | Jira issue keys to link, e.g. ["PROJ-123"] | |
| testPlanKey | Yes | Test plan key, e.g. PROJ-P123 | |
| customFields | No | Custom field values keyed by field name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide idempotentHint; description adds that it's a partial update, projectKey is immutable, and constraints from create_test_plan apply (folder existence, status case-sensitivity). Returns { key } gives basic output. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Approximately 5 sentences, front-loaded with the partial update key point. Dense with useful info, no fluff, though could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavioral rules (partial update, immutable projectKey, constraints from create), and returns basic output shape. Good for a 9-parameter tool with nested objects, but no mention of versioning or conflict handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage; description adds value by noting partial update semantics, that owner must be a Jira user key resolved via find_jira_user, and that folder must already exist. Exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it updates a Zephyr Scale test plan via PUT, specifies it's a partial update (only passed fields change), and contrasts with create_test_plan by noting the endpoint and immutable projectKey.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the partial update behavior, warns against sending empty placeholders, mentions projectKey cannot be changed, and directs to resolve owner via find_jira_user, with references to create_test_plan constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file as an attachment to a Zephyr Scale test case, test run (cycle) or test result — optionally to a single step (POST multipart/form-data to /testcase/{key}[/step/{i}]/attachments, /testrun/{key}/attachments or /testresult/{id}[/step/{i}]/attachments). Addressing: target 'test_case' requires testCaseKey (stepIndex optional to address a specific step); target 'test_run' requires testRunKey (no step addressing — the API has no per-step endpoint for runs); target 'test_result' requires testResultId (stepIndex optional). Pass ONLY the identifier that matches the chosen target. filePath must be an absolute path of a file ON THE MACHINE RUNNING THIS MCP SERVER (the file is read from local disk). Returns the attachment metadata reported by the API, or { uploaded, fileName, size } when the API responds with an empty body.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Kind of entity the attachment belongs to: test_case, test_run or test_result | |
| fileName | No | File name to store in Zephyr Scale; defaults to the basename of filePath | |
| filePath | Yes | Absolute path of the file to upload on the machine running this MCP server | |
| stepIndex | No | 0-based step index to address a single step instead of the whole entity (targets 'test_case' and 'test_result' only) | |
| testRunKey | No | Test run (cycle) key, e.g. PROJ-R123 — required when target is 'test_run' | |
| testCaseKey | No | Test case key, e.g. PROJ-T123 — required when target is 'test_case' | |
| testResultId | No | Numeric test result id — required when target is 'test_result'. Result ids are returned by create_test_result / update_last_test_result / get_test_run_results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries the full burden. It discloses that filePath must be an absolute path on the MCP server, explains the response format including a fallback for empty API responses, and notes step assignment constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but not overly verbose. It front-loads the main purpose and then systematically details the addressing rules. Every sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains the return value. It covers all three target types, parameter constraints, file path requirements, and step addressing limitations, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by clarifying which identifier is required per target, the stepIndex applicability, and the default for fileName. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool uploads a file as an attachment to Zephyr Scale entities (test case, test run, test result) optionally to a step. Distinguishes from siblings like delete_attachment, download_attachment, list_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on target selection and required identifiers, including the limitation that test_run does not support step addressing. Though it doesn't state when not to use, the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2clone_test_casecreate_foldercreate_test_cases_bulkcreate_test_plancreate_test_resultcreate_test_results_bulkcreate_test_rundelete_attachmentdelete_test_rundownload_feature_filesget_issue_test_coverageget_latest_result_for_test_caseget_test_planget_test_run_resultsget_test_run_summarylink_issues_to_test_casesrecreate_test_run_with_itemsrename_foldersearch_test_casessearch_test_runsupdate_test_planupload_automation_resultsupload_cucumber_resultsclone_test_casecreate_environmentcreate_foldercreate_test_plancreate_test_results_bulkcreate_test_rundelete_test_casedownload_feature_filesfind_jira_userget_issue_test_coverageget_latest_result_for_test_caseget_test_cases_linked_to_issueget_test_planhealth_checklist_environmentsrecreate_test_run_with_itemsrename_folderupdate_test_planupload_automation_resultsupload_cucumber_resultsv0.1.1download_feature_filesrecreate_test_run_with_itemsupload_automation_resultsupload_cucumber_resultsclone_test_casecreate_test_case1 field changedInput schema / properties / testScript / properties / text / descriptionPrevious value: -"Script body for PLAIN_TEXT, or the full Gherkin document for BDD"New value: +"Script body for PLAIN_TEXT, or the Gherkin scenario body for BDD: ONLY Given/When/Then/And/But step lines — Server/DC rejects texts wrapped in \"Feature:\"/\"Scenario:\" headers with 400 \"Invalid BDD Script\" (a BDD test case IS a single scenario; the feature wrapper is generated on export)."create_test_cases_bulk1 field changedInput schema / properties / testCases / items / properties / testScript / properties / text / descriptionPrevious value: -"Script body for PLAIN_TEXT, or the full Gherkin document for BDD"New value: +"Script body for PLAIN_TEXT, or the Gherkin scenario body for BDD: ONLY Given/When/Then/And/But step lines — Server/DC rejects texts wrapped in \"Feature:\"/\"Scenario:\" headers with 400 \"Invalid BDD Script\" (a BDD test case IS a single scenario; the feature wrapper is generated on export)."create_test_plandelete_attachmentdelete_test_plandownload_attachmentdownload_feature_filesget_issue_test_coverageget_test_planget_test_run_summarylist_attachmentsrecreate_test_run_with_itemssearch_test_plansset_test_script1 field changedInput schema / properties / text / descriptionPrevious value: -"Script body — required for PLAIN_TEXT and BDD (full Gherkin document), not allowed for STEP_BY_STEP"New value: +"Script body — required for PLAIN_TEXT and BDD (Gherkin step lines only, no Feature:/Scenario: headers), not allowed for STEP_BY_STEP"update_test_case1 field changedInput schema / properties / testScript / properties / text / descriptionPrevious value: -"Script body for PLAIN_TEXT, or the full Gherkin document for BDD"New value: +"Script body for PLAIN_TEXT, or the Gherkin scenario body for BDD: ONLY Given/When/Then/And/But step lines — Server/DC rejects texts wrapped in \"Feature:\"/\"Scenario:\" headers with 400 \"Invalid BDD Script\" (a BDD test case IS a single scenario; the feature wrapper is generated on export)."update_test_planupload_attachmentupload_automation_resultsupload_cucumber_resultsv0.1.0add_test_stepscreate_environmentcreate_foldercreate_test_casecreate_test_cases_bulkcreate_test_resultcreate_test_results_bulkcreate_test_rundelete_test_casedelete_test_runfind_jira_userget_latest_result_for_test_caseget_test_caseget_test_cases_linked_to_issueget_test_runget_test_run_resultshealth_checklink_issues_to_test_caseslist_environmentsrename_foldersearch_test_casessearch_test_runsset_test_scriptupdate_last_test_resultupdate_test_caseScored across 22 tools
Each tool targets a distinct resource and action (e.g., add_test_steps vs set_test_script, clone_test_case vs create_test_case, etc.), with no overlapping purposes. Agents can clearly differentiate between tools.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_test_case, update_test_plan, download_attachment). No mixing of conventions or vague verbs.
22 tools is well-scoped for a test management server, covering core entities (test cases, plans, runs, folders, attachments) and common operations without bloat.
Missing several expected operations: delete_test_case, delete_test_run, delete_attachment, list_folders, search_test_cases, and get_test_run_results. These gaps will likely cause agent failures in standard workflows.
An MCP server that provides access to Testiny projects, test cases and test runs
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
MCP server for building and testing AI agents with multi-model experimentation and insights.
