Skip to main content
Glama
mungowang

jira-mcp

by mungowang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_test_cases

Read-only

Search Zephyr Scale test cases with a TQL query; filter by project, status, folder, labels, or keys, choose fields, and paginate results.

Instructions

Search test cases with a TQL query (GET /testcase/search). A query longer than 1500 characters is sent as POST /testcase/search instead, which supports ONLY the fields projectKey, key and name and at most 2500 values per IN list. That POST endpoint is missing or broken on some Zephyr Scale Server builds, so prefer staying under 1500 characters (split a long IN list across calls); when a POST search fails the error says which transport was used and why.

Unknown VALUES are validated inconsistently: an unknown status, priority, component or projectKey is rejected with 400, while an unknown label in an IN list and an unknown key inside key IN (…) are silently skipped and just shrink the result set — a typo there is indistinguishable from no match. isLast is a heuristic, so an exactly full page always reports isLast false even when it is the last one: stop when values is empty.

TQL quick reference:

  • Test case fields: projectKey, key, name, status, priority, component, folder, estimatedTime, labels, owner, issueKeys + custom fields (field name in double quotes).

  • Test run (cycle) fields: ONLY projectKey and folder.

  • Operators: =, >, >=, <, <=, IN; the only logical connector is AND (no OR).

  • Syntax is strict: spaces around operators are mandatory, string values in double quotes. Folder paths start with "/" ("/" is the root). For single/multi-choice custom fields '=' does not work — use IN.

  • Examples: projectKey = "PROJ" AND status = "Draft" AND priority = "High" projectKey = "PROJ" AND folder = "/Regression/Payments" projectKey = "PROJ" AND labels IN ("smoke", "ui") projectKey = "PROJ" AND "My Field" IN ("Value") key IN ("PROJ-T50", "PROJ-T90") projectKey = "PROJ" AND issueKeys IN ("PROJ-5")

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesTQL query, e.g. projectKey = "PROJ" AND status = "Draft" (see the description for the syntax)
fieldsNoReturn only these fields, e.g. ["key","name","status"]; sent to the API as one comma-separated parameter
startAtNo0-based index of the first result to return (default 0)
maxResultsNoMaximum number of results to return (default 50; the API server-side default is 200)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.5

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, while the description adds substantial non-obvious behavior: the fallback POST endpoint may be missing or broken, unknown values are validated inconsistently with silent skips for some fields, isLast is a heuristic, and pagination should stop on empty values.

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

Conciseness4/5

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

The description is front-loaded with purpose and the GET/POST transport caveat, then organized into TQL reference and examples. It is lengthy for a tool description and repeats some details (isLast heuristic, pagination defaults) already in the schema, but the length is largely justified by TQL complexity.

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

Completeness5/5

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

With no output schema, the description still explains the return shape ({ startAt, maxResults, count, isLast, values }) and covers TQL syntax, validation quirks, transport limits, and pagination behavior. An agent has everything needed to call the tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description supplies an extensive TQL quick reference (fields, operators, strict syntax, examples) that is essential for constructing the query parameter and cannot be inferred from the schema alone. It adds less for fields, startAt, and maxResults beyond what the schema already says.

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

Purpose5/5

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

States a specific verb and resource ('Search test cases with a TQL query') and names the exact endpoint, so an agent can distinguish it from get_test_case, create_test_case, and other siblings without opening the schema.

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

Usage Guidelines4/5

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

Provides clear context for use (TQL search over test cases) and operational guidance such as preferring GET under 1500 characters, but it never names or contrasts alternatives like search_test_runs or get_test_case, so there are no explicit exclusions.

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

Deploy Server

Other Tools