Skip to main content
Glama
uarlouski

TestRail MCP Server

by uarlouski
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

get_cases

Read-onlyIdempotent

Retrieve all test cases for a TestRail project, filtering by section, priority, type, or custom fields. Returns case IDs, titles, and requested fields.

Instructions

Get all test cases for a project. Filter by section, API params (priority, type), or any field including custom fields via 'where'. Returns case IDs, titles, and any additional requested fields.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
whereNoOptional client-side filter for any field including custom fields (filters after fetching all cases). Supports exact value matching. Example: {"custom_automation_status": 1, "priority_id": 2}
fieldsNoAdditional fields to include in response beyond id, title, and suite_id (supports system fields such as updated_on, created_on, created_by, updated_by, as well as custom fields). Example: ["updated_on", "priority_id", "custom_automation_status"]
filterNoOptional API-side filters (more efficient for large datasets). Supported: priority_id, type_id, created_by, updated_by, milestone_id, refs, created_after, created_before, updated_after, updated_before. Use comma-separated values for IDs. Example: {"priority_id": "1,2", "type_id": "3"}
sectionNoSection filter configuration. Use query_section to find available sections
suite_idNoThe ID of the test suite (required for multi-suite projects, i.e. suite_mode=3). Use query_suite to find available suites
project_idYesThe ID of the project. Use query_project to find available projects
output_fileNoAbsolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.1.0
    • changedInput schema / properties / fields / description
      Previous value: -"Additional fields to include in response beyond id, title, and suite_id. Use get_case_fields to see available fields. Example: [\"priority_id\", \"type_id\", \"custom_automation_status\"]"New value: +"Additional fields to include in response beyond id, title, and suite_id (supports system fields such as updated_on, created_on, created_by, updated_by, as well as custom fields). Example: [\"updated_on\", \"priority_id\", \"custom_automation_status\"]"
  2. Changed3 schema fields changedv3.0.0
    • changedInput schema / properties / project_id / description
      Previous value: -"The ID of the project. Use get_projects to find available projects"New value: +"The ID of the project. Use query_project to find available projects"
    • changedInput schema / properties / section / description
      Previous value: -"Section filter configuration. Use get_sections to find available sections"New value: +"Section filter configuration. Use query_section to find available sections"
    • changedInput schema / properties / suite_id / description
      Previous value: -"The ID of the test suite (required for multi-suite projects, i.e. suite_mode=3). Use get_suites to find available suites"New value: +"The ID of the test suite (required for multi-suite projects, i.e. suite_mode=3). Use query_suite to find available suites"
  3. Addedv2.2.0
  4. Removedv2.1.0
  5. Addedv2.0.0
  6. Removedv1.9.2
  7. Changed1 schema field changed
    • addedInput schema / properties / output_file
      Added value: +{
+  "description": "Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits.",
+  "type": "string"
+}
  8. First observedv1.9.0

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the return shape (case IDs, titles, requested fields), which is mildly useful, but the significant behavioral caveat — that 'where' fetches all cases first and filters client-side — lives only in the schema, and no auth or rate-limit context is given.

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?

Three tight sentences, front-loaded with purpose followed by filtering and return shape. No filler, though the return-shape sentence is the only non-redundant addition.

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

Completeness4/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 correctly compensates by naming the guaranteed return fields (IDs, titles) plus requested extras. With 100% schema coverage on parameters and annotations covering safety, the definition is nearly self-sufficient; only the client-side filtering cost is left undocumented in the description.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description summarizes the same filters (section, priority, type, custom fields via 'where') without adding syntax, format, or constraint detail beyond the schema — the baseline 3.

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 ('Get all test cases for a project') with scope, then names the filter dimensions and the return contents. An agent can distinguish this from the singular sibling get_case and from get_tests/get_results 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 Guidelines3/5

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

The description enumerates the filtering mechanisms (section, API params, 'where') but never says when to prefer this tool over get_case or get_tests, nor when to use the API-side 'filter' versus the client-side 'where'. Usage is implied by the filter list rather than stated.

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