Skip to main content
Glama
mungowang

jira-mcp

by mungowang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_test_plans

Read-only

Search Zephyr Scale test plans using TQL to filter by project, folder, status, owner, key, or labels. Use exact folder paths and paginate results when needed.

Instructions

Search test plans with a TQL query (GET /testplan/search). For test plans the searchable fields include projectKey, folder, name, status, key, owner and labels (verified live) — the exact set varies by Zephyr Scale version, and an unsupported field fails with 400 "Unrecognized field: ".

folder matches EXACTLY: plans in a subfolder of the given path are NOT returned. A folder path that does not exist is not an error here — it comes back as an empty page (count 0), unlike search_test_cases and search_test_runs, which answer 400 for the same path.

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 folder = "/Releases"
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, but the description adds substantial behavior: the 400 'Unrecognized field' failure mode for unsupported fields, that a nonexistent folder returns an empty page rather than an error (contrasted with siblings), the exact return envelope, and that isLast is a heuristic (count < maxResults). This is well beyond what the annotation conveys.

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?

Front-loaded with purpose and endpoint, then field list, then edge cases, then TQL reference — a sensible ordering for a complex tool. It is verbose, and the TQL cheat sheet lists test case and test run fields that this tool cannot search, which is mild scope bloat rather than pure signal.

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?

No output schema exists, so the description carries that burden and does so fully by naming the response fields (startAt, maxResults, count, isLast, values) and pagination contract. Query syntax, error semantics, and edge cases are all covered for a fairly complex search tool.

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 the baseline is 3, but the description adds value the schema cannot: TQL grammar for the query parameter (mandatory spaces, quoted strings, '/' root, IN required for choice fields, AND-only) and the meaningful gap between the tool's maxResults default of 50 and the API's server-side default of 200. Pagination interplay with isLast is also explained.

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 plans with a TQL query') plus the underlying endpoint (GET /testplan/search). It explicitly distinguishes itself from siblings search_test_cases and search_test_runs by contrasting their folder-path error behavior, so an agent can route without opening any 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?

Gives concrete usage context: searchable fields for test plans, operators, syntax rules, and five worked examples. It also distinguishes this tool's semantics from search_test_cases/search_test_runs for the folder case. It stops short of an explicit 'use this when X, use sibling when Y' routing statement, so it is strong but not complete.

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