Skip to main content
Glama

List monitors and their runs

list_monitors
Read-onlyIdempotent

List the workspace's monitors -- searches and agent questions kept on a schedule -- each with its schedule, status, next run, this month's spend and what its last run found; or, with monitor_id, one monitor with its latest runs. Call it to find a monitor_id, to see whether a kept search or question found something new, or to check spend. A run's refId is the search or agent run it made: get_job(kind='search' or 'agent', id=refId) reads it in full. Inputs: kind keeps 'search' or 'agent' ones; monitor_id reads one, with up to runs of its runs (10 by default). Read-only and free: it reads stored data and never fetches.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_monitors"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoKeep only 'search' or 'agent' monitors; omit for both.
runsNoWith monitor_id: how many of its latest runs, 1 to 50; default 10.
monitor_idNoOne monitor's id, to read it with its latest runs.

Output Schema

NameRequiredDescriptionDefault
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
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.
monitorNoWith monitor_id only: the monitor in full -- its request, budget and records setting -- and under `runs` its latest runs, newest first, each {id, status, trigger, changed, summary, credits, refId, createdAt}.
monitorsNoEach {id, kind, name, schedule, status, nextRunAt, lastRunAt, spentThisMonth, budget, lastRun: {status, changed, summary}}, newest first. Absent with monitor_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds context the annotations cannot: 'Read-only and free: it reads stored data and never fetches', which tells the agent there is no cost and no external network call. It stops short of noting result caps or pagination for the collection mode, so it is strong but not exhaustive.

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 sentences, each carrying distinct information: object definition, call triggers, refId follow-up, and input summary. The first sentence is long and stacks parentheticals and a comma list, which slightly slows scanning, but nothing is redundant and the dual-mode distinction is front-loaded.

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 three-parameter, zero-required read tool with an output schema, the description covers everything needed: what a monitor is, the two modes, what each mode returns, when to call it, how to follow a run's refId, and the cost/network profile. No behavioral or routing question is left open.

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%, so the schema already documents kind, runs and monitor_id, including defaults and the 1–50 range. The description reinforces the key interaction ('monitor_id reads one, with up to runs of its runs, 10 by default') but adds little beyond the schema. It does explain what a run's refId refers to, though that is return-value semantics rather than parameter meaning.

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 the workspace's monitors') and immediately defines the domain object as 'searches and agent questions kept on a schedule'. It also distinguishes two operating modes — collection listing versus single-monitor-with-runs when monitor_id is supplied — so an agent knows exactly what shape of result each call produces.

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 call conditions ('to find a monitor_id, to see whether a kept search or question found something new, or to check spend') and routes the follow-up explicitly: a run's refId is read in full via get_job(kind='search' or 'agent', id=refId). That is a named alternative with the condition that selects it, which is the top of the scale.

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.