Skip to main content
Glama
uarlouski

TestRail MCP Server

by uarlouski
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

get_cases

Read-onlyIdempotent

Retrieve test cases for a project, using filters for section, priority, type, or custom fields, and return IDs, titles, and selected 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. Use get_case_fields to see available fields. Example: ["priority_id", "type_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. 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"
  2. Addedv2.2.0
  3. Removedv2.1.0
  4. Addedv2.0.0
  5. Removedv1.9.2
  6. 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"
+}
  7. First observedv1.9.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the `where` filter is client-side ('filters after fetching all cases'), implying inefficiency for large datasets, and `output_file` is recommended to avoid context limits. This goes beyond the annotations and informs the agent of performance trade-offs.

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

Conciseness5/5

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

The description is concise and front-loaded with the primary purpose. It uses two clear sentences plus a return statement, avoiding redundancy with schema details. Every sentence adds actionable information (scope, filtering, output format) without filler.

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?

Given the tool's complexity (7 parameters, nested objects), the description covers essential aspects: what it returns, filtering options, and large-data handling. It does not explicitly mention suite_id requirements or response structure beyond IDs/titles, but these are documented in the schema. The lack of an output schema is mitigated by the clear return statement.

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. The description adds meaning by distinguishing `where` (client-side, after fetch) from `filter` (API-side, more efficient) and provides examples for both. It also clarifies the output_file use case, adding value beyond the schema's parameter descriptions.

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?

The description clearly states the tool retrieves all test cases for a project, with filtering options. It distinguishes itself from siblings like `get_case` (singular) and `get_tests` by emphasizing bulk retrieval and flexible filters. The verb 'get' and resource 'cases' are specific and unambiguous.

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?

The description implies usage for fetching cases with filtering and provides pointers to associated tools (query_section, query_suite, get_case_fields). It does not explicitly state when not to use this tool, but the examples and mentions of client-side vs API-side filters give practical guidance. It lacks explicit contrasts with alternatives, but the context is clear enough for typical scenarios.

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