Skip to main content
Glama

List Test Controls

list_test_controls
Read-only

Retrieves quarantined, critical, watched, or flaky-candidate tests from a project's Test Controls, filtered by state, search, or assignee, so you can review which tests need action.

Instructions

List the tests under Test Controls in a project, as the Test Controls page shows them. view "quarantined" (default) lists quarantines — filter by state (active, ending_soon, released), covers (any failure or one error) and, for released ones, reason; the response includes the quarantine budget. view "critical" lists tests marked critical, view "watched" lists the tests you watch, view "candidates" lists flaky tests that failed a build in the last 30 days (a test that always passed on retry is not listed, since quarantining it would change nothing). search matches the test title or file; assignee takes "me", a user id or an email. Quarantine settings (budget, default length, auto-release) are changed only in the app, not here.

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_test_controls"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
viewNoDefault "quarantined"
limitNoDefault 25 (50 for candidates, max 200 there)
stateNoquarantined view only. Default "active"
coversNoquarantined view only: "any" failure or one "error"
reasonNoRelease reason; only with state "released"
searchNoMatch the test title or file
assigneeNo"me", a user id or an email. Not for the candidates view
projectIdYesProject ID (e.g. project_<id>)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.2.3
    • addedInput schema / properties / assignee / maxLength
      Added value: +254
  2. Addedv2.2.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare this a read-only, non-destructive, closed-world operation, so the description only needs to add extras — and it does: the quarantined response includes the quarantine budget, the candidates view deliberately omits always-pass-on-retry tests, and quarantine settings (budget, default length, auto-release) cannot be changed here. Pagination/ordering behavior is not mentioned, which keeps it below 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 the core purpose, then the view semantics, then cross-cutting filters, then the scope limitation — a sensible ordering with no filler sentences. It is dense and semicolon-heavy, reading as one long run-on rather than clearly separated bullets, which costs a point.

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?

With 9 parameters, four enums and no output schema, an agent needs view semantics and filter applicability, both of which are covered, along with the explicit note that mutation of quarantine settings happens elsewhere. Missing items are secondary: no mention of ordering, pagination mechanics beyond limit, or what fields each view returns.

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 89%, so the schema already documents view, state, covers, reason, search, assignee and limit defaults. The description mostly restates those enums, with one genuine addition: clarifying that "covers" means any failure versus a single error type. That is useful but marginal over an already-rich schema, so the baseline of 3 fits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("List the tests under Test Controls in a project") and enumerates the four views, so an agent knows exactly what population is returned. It does not name a sibling (e.g. get_test_controls or list_automated_tests) to contrast against, so it stops short of full sibling differentiation.

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?

Each view is defined with the condition that selects it (quarantined = current quarantines, critical = marked critical, watched = you watch, candidates = flaky failures in last 30 days), which is effectively per-mode when-to-use guidance. It also states exclusions (tests that always passed on retry are not listed) and that assignee does not apply to the candidates view, but it never names an alternative tool for overlapping needs.

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