Skip to main content
Glama

Get Run Error Clusters

get_run_error_clusters
Read-only

Group a test run's failed and flaky tests by shared error signature to identify distinct failures, pinpoint the error affecting the most tests, and review category rollups.

Instructions

Group ONE run's failing tests by shared error signature (normalized error fingerprint), computed for that run only. Returns error clusters (each = one signature + its affected tests + an error category), an unclustered bucket for blank/unfingerprintable errors, a per-category rollup, and run totals. Failed/timed-out tests cluster on their final-attempt error; flaky tests cluster on the error they recovered from (pre-recovery). Categories: assertion, timeout, element_not_found, network, filesystem, setup (an e2e run that could not get started: credentials, environment, seed data, test setup, no model), other. Use this to answer "what are the distinct failures in this run?" or "which error affected the most tests?" — it is far cheaper than paging every failed case. Optionally narrow with status="failed" or status="flaky" (default "all"). Workflow: list_testruns() → pick a testrun_id → get_run_error_clusters().

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>",
      "testrun_id": "<testrun_id>"
    },
    "name": "get_run_error_clusters"
  }
}

Input Schema

NameRequiredDescriptionDefault
statusNoWhich contributing tests populate the clusters (default "all")
projectIdYesProject ID (e.g. project_<id>)
testrun_idYesThe test run ID to cluster errors for (single run)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 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 / projectId / description
      Previous value: -"Project ID (Required). The TestDino project identifier."New value: +"Project ID (e.g. project_<id>)"
    • changedInput schema / properties / status / description
      Previous value: -"Filter by test status. 'failed' shows definitively failed tests, 'flaky' shows flaky tests, 'all' (default) includes both."New value: +"Which contributing tests populate the clusters (default \"all\")"
    • changedInput schema / properties / testrun_id / description
      Previous value: -"Test run ID (Required). The run to cluster errors for."New value: +"The test run ID to cluster errors for (single run)"
    • addedInput schema / properties / testrun_id / minLength
      Added value: +1
  2. Addedv2.0.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare a safe read, so the description's extra burden is low — and it still delivers substantial context: what each cluster contains, the existence of an unclustered bucket for blank errors, a per-category rollup and run totals, which attempt supplies the error (final attempt for failed/timed-out, pre-recovery error for flaky), and the full category taxonomy including the setup caveat.

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 the core definition, then returns shape, then categories, then use cases and the workflow — a sensible order. It is dense and the parenthetical category dictionary plus em-dash asides make it longer than ideal, but nearly every clause carries decision-relevant information.

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?

There is no output schema, and the description compensates fully by enumerating every component of the response (clusters, unclustered bucket, category rollup, totals) and the meaning of each category. Nothing needed to call or interpret the result is missing.

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 description coverage is 100%, so the baseline is 3; the description earns above that by explaining that status determines which contributing tests populate the clusters (not which tests are returned) and by tying status=flaky to the pre-recovery error semantics. projectId and testrun_id gain only their already-documented scope.

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 with explicit scope: failing tests of ONE run grouped by normalized error fingerprint, computed for that run only. It also distinguishes itself from the alternative approach of paging every failed case, so an agent can pick it without inspecting the 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 the exact questions the tool answers ("what are the distinct failures in this run?", "which error affected the most tests?"), states when it is cheaper than alternatives, and supplies a concrete workflow (list_testruns → pick testrun_id → get_run_error_clusters). The optional status narrowing with its default is called out explicitly.

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