Skip to main content
Glama
mungowang

jira-mcp

by mungowang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_test_runs

Read-only

Search Jira test runs or test cycles with TQL queries. Filter by projectKey and folder, including subfolders, to locate cycles before reading details.

Instructions

Search test runs / test cycles with TQL (GET /testrun/search). For runs TQL accepts ONLY the fields projectKey and folder — name, status or dates are NOT searchable, and there is no full-text search; read a candidate run with get_test_run instead. A folder clause matches that folder AND its subfolders: folder = "/A" also returns the runs in /A/B. 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; for test runs only projectKey and folder are searchable, e.g. projectKey = "PROJ"
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.8/5.0
Behavior5/5

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

With readOnlyHint=true already covering safety, the description adds substantial behavioral context: strict syntax rules, AND-only connector, mandatory spaces, the '=' vs IN quirk for choice fields, folder-root behavior, and the pagination/return contract including the isLast heuristic. This is far beyond what the annotation provides.

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?

Long but front-loaded: the critical scoping constraint and the get_test_run alternative come first, followed by a dense reference. A few lines (pagination default restated from the schema, overlapping field list plus examples) are mildly redundant, keeping it short of a 5.

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?

There is no output schema, and the description compensates by describing the response shape ({ startAt, maxResults, count, isLast, values }) plus how to paginate. For a syntax-heavy search tool, an agent has everything needed to construct and page a valid query.

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% and already documents query/fields/startAt/maxResults, so the baseline is 3. The description still adds real meaning: TQL operators, quoting, AND-only logic, folder path syntax, and the note that maxResults server-side default is 200, which helps an agent tune paging.

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?

Opens with a specific verb+resource ('Search test runs / test cycles with TQL') and even names the endpoint. It immediately distinguishes itself from siblings by stating that name/status/dates are NOT searchable here and pointing to get_test_run for retrieval.

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

Usage Guidelines5/5

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

Explicitly states the constraints of this tool (only projectKey and folder are searchable, no full-text search) and names the alternative (get_test_run) plus the condition that selects it (reading a candidate run). It also clarifies folder-clause semantics (matches subfolders), which prevents a common misuse.

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