Skip to main content
Glama

List Test Runs

list_testruns
Read-only

Browse a project's test runs with filters for status, branch, author, commit, environment, and time to retrieve run metadata and testrun_id values for follow-up queries.

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>"
    },
    "name": "list_testruns"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo1-indexed page number (default: 1)
sortNoRun list sort order
limitNoItems per page: 10, 25, 50 or 100. Any other value is rounded to the nearest, and the answer's `warnings` says so.
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. Changed1 schema field changed
    • changedInput schema / properties / limit / description
      Previous value: -"Items per page. Data Handler accepts 10, 25, 50, or 100."New value: +"Items per page: 10, 25, 50 or 100. Any other value is rounded to the nearest, and the answer's `warnings` says so."
  2. 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"
  3. 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"
      +}
  4. 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)."
  5. First observed

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by steering toward filtered/paginated access and by naming the follow-up handle (testrun_id) the call yields. It stops short of discussing rate limits, auth requirements, or result-size behavior, so it is strong but not fully transparent.

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 negative routing rule, then filter syntax — a sensible order with no filler sentences. The closing time-value sentence partly restates the by_time_interval schema description, which is the only mildly redundant material.

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?

For a 13-parameter read-only list tool with no output schema, the description covers purpose, the kind of data returned, pagination guidance, and the sibling relationship — the things an agent needs to select and call it correctly. Parameter-level detail is fully delegated to a complete schema, so nothing material is missing.

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%, with every parameter, three enums and the limit rounding behavior already documented inline, so the baseline is 3. The description adds only marginal semantic value: it supplies a few extra time-filter examples ('1d', '3d') beyond the schema's list and frames the return fields, but it does not explain filters like by_test_controls or by_test_case_tags that carry the most interpretation burden.

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') plus scope ('optional filters'). It also distinguishes itself from the sibling list_testcase by saying when that tool should be used instead, so an agent can disambiguate without opening a schema.

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?

Gives an explicit when-to-use condition ('run-level metadata: pass/fail totals, duration, branch, commit, author, or testrun_id values for follow-up calls') and an explicit when-not-to-use ('You do NOT need to call this before list_testcase when you already have branch/time/author filters — list_testcase resolves runs internally'). It also advises narrowing with filters and pagination rather than fetching broad result sets.

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