Skip to main content
Glama

List Test Runs

list_testruns
Read-only

Browse a project's test runs with filters for branch, author, status, commit, environment, and time. Retrieve pass/fail totals, duration, and run IDs for follow-up calls.

Instructions

Browse test runs for a project with optional filters. Use this when you need run-level metadata: pass/fail totals, duration, branch, commit, author, or when you need testrun_id values for follow-up calls. Use specific filters and pagination instead of fetching broad result sets. You do NOT need to call this before list_testcase when you already have branch/time/author filters — list_testcase resolves runs internally. Common time values: "1d", "3d", "weekly", "monthly", or "YYYY-MM-DD,YYYY-MM-DD" for a custom range.

Input Schema

NameRequiredDescriptionDefault
pageNo1-indexed page number (default: 1)
sortNoRun list sort order
limitNoItems per page. Data Handler accepts 10, 25, 50, or 100.
searchNoSearch run commit message, or exact counter when numeric
by_authorNoFilter by commit author
by_branchNoFilter by git branch name
by_commitNoFilter by commit hash prefix
by_statusNoFilter by run status
projectIdYesProject ID (e.g. project_<id>)
by_environmentNoFilter by CI/deployment environment
by_test_controlsNoRuns Test Controls changed, as the runs list filter: "excluded" = had quarantined failures, "critical" = a critical test passed only on retry, "any" = changed by Test Controls. Each run carries `quarantine` ({state, excluded_count, critical_flaky}; null for reporters before 2.8.0).
by_time_intervalNoTime filter: "1h", "1d", "weekly", "monthly", "last 5 days", or "YYYY-MM-DD,YYYY-MM-DD"
by_test_case_tagsNoComma-separated test case tags contained in the run

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed20 schema fields changedv2.2.0
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / by_author / description
      Previous value: -"Filter by commit author name (exact match)."New value: +"Filter by commit author"
    • changedInput schema / properties / by_branch / description
      Previous value: -"Filter by git branch name (e.g., 'main', 'develop', 'feature/login')."New value: +"Filter by git branch name"
    • changedInput schema / properties / by_commit / description
      Previous value: -"Filter by git commit hash (full or partial)."New value: +"Filter by commit hash prefix"
    • changedInput schema / properties / by_environment / description
      Previous value: -"Filter by environment. Example: 'production', 'staging', 'development'."New value: +"Filter by CI/deployment environment"
    • changedInput schema / properties / by_status / description
      Previous value: -"Filter by run status: 'passed', 'failed', 'interrupted', 'incomplete', or 'running'."New value: +"Filter by run status"
    • changedInput schema / properties / by_test_case_tags / description
      Previous value: -"Comma-separated test case tags contained in the run (exact match, include the '@' prefix if the tag has one, e.g. '@critical')."New value: +"Comma-separated test case tags contained in the run"
    • addedInput schema / properties / by_test_controls
      Added value: +{
      +  "description": "Runs Test Controls changed, as the runs list filter: \"excluded\" = had quarantined failures, \"critical\" = a critical test passed only on retry, \"any\" = changed by Test Controls. Each run carries `quarantine` ({state, excluded_count, critical_flaky}; null for reporters before 2.8.0).",
      +  "enum": [
      +    "excluded",
      +    "critical",
      +    "any"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / by_time_interval / description
      Previous value: -"Filter by time interval. Supports: 'Latest' (most recent, no time filter), '1h' (last hour), '2h' (last 2 hours), '5h' (last 5 hours), '12h' (last 12 hours), '1d' (last day), '3d' (last 3 days), '5d' (last 5 days), 'weekly' (last 7 days), 'monthly' (last 30 days), 'last 1 hour', 'last day', 'last 5 days', or '2024-01-01,2024-01-31' (date range)."New value: +"Time filter: \"1h\", \"1d\", \"weekly\", \"monthly\", \"last 5 days\", or \"YYYY-MM-DD,YYYY-MM-DD\""
    • removedInput schema / properties / limit / default
      Removed value: -20
    • changedInput schema / properties / limit / description
      Previous value: -"Number of results per page (default: 20, max: 1000)."New value: +"Items per page. Data Handler accepts 10, 25, 50, or 100."
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • removedInput schema / properties / page / default
      Removed value: -1
    • changedInput schema / properties / page / description
      Previous value: -"Page number (default: 1)."New value: +"1-indexed page number (default: 1)"
    • addedInput schema / properties / page / exclusiveMinimum
      Added value: +0
    • changedInput schema / properties / page / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / projectId / description
      Previous value: -"Project ID (Required). The TestDino project identifier."New value: +"Project ID (e.g. project_<id>)"
    • changedInput schema / properties / search / description
      Previous value: -"Search run commit messages, or match an exact run counter when the value is numeric."New value: +"Search run commit message, or exact counter when numeric"
    • changedInput schema / properties / sort / description
      Previous value: -"Sort order for the run list: 'counter_desc' (newest first, default), 'counter_asc', 'duration_asc', or 'duration_desc'."New value: +"Run list sort order"
  2. Changed6 schema fields changedv2.0.2
    • changedInput schema / properties / by_author / description
      Previous value: -"Filter by commit author name (case-insensitive, partial match)."New value: +"Filter by commit author name (exact match)."
    • addedInput schema / properties / by_status
      Added value: +{
      +  "description": "Filter by run status: 'passed', 'failed', 'interrupted', 'incomplete', or 'running'.",
      +  "enum": [
      +    "passed",
      +    "failed",
      +    "interrupted",
      +    "incomplete",
      +    "running"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / by_test_case_tags
      Added value: +{
      +  "description": "Comma-separated test case tags contained in the run (exact match, include the '@' prefix if the tag has one, e.g. '@critical').",
      +  "type": "string"
      +}
    • removedInput schema / properties / get_all
      Removed value: -{
      -  "default": false,
      -  "description": "Get all results up to 1000 (default: false).",
      -  "type": "boolean"
      -}
    • addedInput schema / properties / search
      Added value: +{
      +  "description": "Search run commit messages, or match an exact run counter when the value is numeric.",
      +  "type": "string"
      +}
    • addedInput schema / properties / sort
      Added value: +{
      +  "description": "Sort order for the run list: 'counter_desc' (newest first, default), 'counter_asc', 'duration_asc', or 'duration_desc'.",
      +  "enum": [
      +    "counter_desc",
      +    "counter_asc",
      +    "duration_asc",
      +    "duration_desc"
      +  ],
      +  "type": "string"
      +}
  3. Changed1 schema field changedv1.0.10
    • changedInput schema / properties / by_time_interval / description
      Previous value: -"Filter by time: '1d' (last day), '3d' (last 3 days), 'weekly' (last 7 days), 'monthly' (last 30 days), or '2024-01-01,2024-01-31' (date range)."New value: +"Filter by time interval. Supports: 'Latest' (most recent, no time filter), '1h' (last hour), '2h' (last 2 hours), '5h' (last 5 hours), '12h' (last 12 hours), '1d' (last day), '3d' (last 3 days), '5d' (last 5 days), 'weekly' (last 7 days), 'monthly' (last 30 days), 'last 1 hour', 'last day', 'last 5 days', or '2024-01-01,2024-01-31' (date range)."
  4. First observed

TDQS

A4.4/5.0
Behavior4/5

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

readOnlyHint=true already covers the safety profile, and the description adds real context on top: which fields the runs carry, that testrun_id values feed follow-up calls, and a guidance to prefer filtered/paginated queries. It stops short of describing pagination limits or result volume behavior, so not a full 5.

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, then usage, then the sibling exclusion, then time formats — a sensible priority order with no filler. The closing time-value sentence partially duplicates the by_time_interval schema description, which keeps it from 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?

With no output schema, the description still tells the agent what comes back (run metadata fields and testrun_id) and how to keep result sets manageable. Combined with 100% schema coverage on 13 parameters, an agent has everything needed to call this correctly.

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 all 13 parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the time-interval vocabulary ("1d", "3d", "weekly", "monthly", custom range) and names the branch/time/author filter families, but adds no syntax or semantics the schema lacks.

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 ("Browse test runs for a project") and immediately narrows scope to run-level metadata. It distinguishes itself from the closest sibling by explaining that list_testcase resolves runs internally, so an agent can route without opening schemas.

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 when to use it (need run-level metadata such as pass/fail totals, duration, branch, commit, author, or testrun_id values) and when not to ("You do NOT need to call this before list_testcase when you already have branch/time/author filters"). It also advises specific filters plus pagination over broad result sets.

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