Skip to main content
Glama

List a project's runs

list_runs
Read-onlyIdempotent

List a project's runs, newest first, with each run's id, status, trigger, pages read and pages changed. Use it to find a run_id for list_pages or get_changes, to check whether a run is still going before start_run, or to find the run to stop with cancel_job. get_project shows only the last run. Inputs: project_id from list_projects. limit=5 finds the latest few; runs past the limit cannot be paged. Errors: an unknown project answers 404. Read-only and free: it reads stored data and never fetches.

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": {
      "project_id": "<project_id>"
    },
    "name": "list_runs"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many runs to return, 1 to 100 (default 25).
project_idYesThe project's 32-character hex id, from list_projects.

Output Schema

NameRequiredDescriptionDefault
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
runsNoEach {id, status, trigger, scope, pages, changed, errors, counts, coverage, stop, startedAt, elapsed, baseline, rebaselined}; baseline is a first run with nothing to compare, rebaselined one whose settings changed how pages read, so it was recorded rather than compared.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
statusNoOnly on a failure: the HTTP status code.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / runs / description
      Previous value: -"Each {id, status, trigger, scope, pagesN, changedN, counts, coverage, stop, startedAt, elapsed, baseline, rebaselined}; baseline is a first run with nothing to compare, rebaselined one whose settings changed how pages read, so it was recorded rather than compared."New value: +"Each {id, status, trigger, scope, pages, changed, errors, counts, coverage, stop, startedAt, elapsed, baseline, rebaselined}; baseline is a first run with nothing to compare, rebaselined one whose settings changed how pages read, so it was recorded rather than compared."
  2. Changed3 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"How many runs to return, newest first: 1 to 100 (default 25)."New value: +"How many runs to return, 1 to 100 (default 25)."
    • changedInput schema / properties / project_id / description
      Previous value: -"The project's id, as list_projects or create_project returns it."New value: +"The project's 32-character hex id, from list_projects."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A project's runs, newest first.",
      +  "properties": {
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "runs": {
      +      "description": "Each {id, status, trigger, scope, pagesN, changedN, counts, coverage, stop, startedAt, elapsed, baseline, rebaselined}; baseline is a first run with nothing to compare, rebaselined one whose settings changed how pages read, so it was recorded rather than compared.",
      +      "title": "Runs"
      +    },
      +    "status": {
      +      "description": "Only on a failure: the HTTP status code.",
      +      "title": "Status"
      +    }
      +  },
      +  "title": "RunsOut",
      +  "type": "object"
      +}
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description still adds non-obvious behavior: newest-first result ordering, the fact that results past the limit cannot be paged, a 404 on unknown project, and that the call is free because it reads stored data rather than fetching. These are the operational details an agent cannot get from the annotation flags.

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?

Four short, labelled lines (purpose, use cases, inputs, errors) with the core behavior front-loaded and no filler. The enumeration of returned fields is mildly redundant given an output schema exists, which keeps this from a perfect score.

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 two-parameter read tool this is fully specified: purpose, ordering, alternatives, input provenance, limit semantics, and the one error case. The output schema carries the return shape, so no further explanation of results is required.

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, but the description adds real meaning: 'limit=5 finds the latest few; runs past the limit cannot be paged' clarifies that limit is a hard cap rather than a page size, which the schema does not state. It also ties project_id to its source ('from list_projects'), though it does not restate the id format.

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 ('List a project's runs') plus ordering ('newest first') and the fields returned (id, status, trigger, pages read/changed). It also differentiates from the closest sibling by noting 'get_project shows only the last run', so an agent can pick correctly without opening either 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 three concrete when-to-use triggers: obtaining a run_id for list_pages or get_changes, checking whether a run is still going before start_run, and finding the run to stop with cancel_job. It also names the alternative (get_project) and its limitation, leaving nothing to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.