squally-mcp

Official

by squallydev-admin

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Find runs

squally-find-run

Read-onlyIdempotent

Find CI runs for a project by branch, commit SHA, or status. Get summary counters with sharded runs collapsed into one entry per logical run.

Instructions

Finds CI runs of a project - the latest, or filtered by branch, commit SHA or status. One row per logical run: a sharded run is collapsed into a single entry. Returns summary counters only; use squally-get-run for the per-test rows.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sha`	No	A commit SHA or a prefix of one (4-40 hex characters). Matches the run's commit or its tested revision (a pull request's head behind a merge commit).
`days`	No	The period, in days, ending now. Must not exceed the plan's retention (Standard 60, Pro 90 days); a longer period is refused with 400 invalid_period rather than answered with less data.
`branch`	No	Exact branch name.
`cursor`	No	Opaque. Pass nextCursor for older runs, or prevCursor together with direction=prev for newer runs.
`status`	No	Only runs with this outcome.
`perPage`	No	Rows per page.
`direction`	No	Which way the cursor pages.	next
`projectId`	Yes	A project id from GET /projects.

Output Schema

TableJSON Schema

Name	Required	Description
`runs`	Yes
`total`	Yes
`window`	Yes
`project`	Yes
`nextCursor`	Yes	Pass as ?cursor= for the next page of older runs; null on the last page.
`prevCursor`	Yes	Pass as ?cursor= with direction=prev for newer runs; null on the first page.
`stableBranch`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 24, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: sharded runs are collapsed into one row and only summary counters are returned, which is important for interpreting results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the core purpose, the logical-run behavior, and the tool-selection pointer. It is front-loaded and has no filler.

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 annotations covering safety and an output schema explaining return shape, the description covers the remaining non-obvious context: run collapsing, summary-only results, and when to escalate to squally-get-run. Nothing needed for correct invocation 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 coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by defining the default query as 'the latest' when no filters are supplied, and by naming the three filter dimensions (branch, SHA, status) that map to schema parameters.

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 action ('Finds CI runs of a project') and immediately clarifies scope: latest, or filtered by branch, SHA, or status. It also distinguishes itself from squally-get-run by noting it returns summary counters only, so an agent can tell which tool fits.

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?

Explicitly tells the agent to use squally-get-run when per-test rows are needed, and clarifies that this tool returns only summary counters. It does not enumerate exclusions for every sibling, but the one meaningful routing decision is covered.

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

Deploy Server