Skip to main content
Glama
fettlesh

fettle-mcp

by fettlesh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

List heartbeat monitors

list_heartbeats
Read-onlyIdempotent

Find cron heartbeat monitors to get a monitor's id or ping_url, or spot late jobs by sorting DOWN first. Filter by name, tags, or status.

Instructions

Find heartbeat (cron / dead-man's-switch) monitors. Each has id, name, state (PENDING until a success ping makes it UP or a /fail ping makes it DOWN; later UP, DOWN or PAUSED), period_seconds, grace_seconds, ping_url, last_ping_at, last_success_at, overdue_at, tags and channel_ids. Use it to get a heartbeat's id or ping_url, or to see which jobs are late (sort status puts DOWN first). Probed URLs and hosts are monitors: use list_monitors for those. For one heartbeat's full record, with its last run's duration, use get_heartbeat. Returns a page: items plus total, page, size and pages.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoCase-insensitive substring of the name, up to 255 characters.
tagNoKeep items carrying these tags: a JSON array of up to 10 tags, each up to 50 characters, lowercased before matching. tag_match decides whether all or any of them must match.
pageNoPage number, 1 or more; default 1.
sizeNoRows per page, 1 to 100; default 25. Keep paging until you have seen total rows.
sortNostatus (the default: DOWN, PENDING, UP, PAUSED, newest first within each), name, or created_at (newest first).
tag_matchNoall (the default): an item must carry every tag in tag. any: at least one of them.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageYes
sizeYes
itemsYes
pagesYes
totalYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.6.1
    • addedInput schema / properties / page / description
      Added value: +"Page number, 1 or more; default 1."
    • addedInput schema / properties / q / description
      Added value: +"Case-insensitive substring of the name, up to 255 characters."
    • addedInput schema / properties / size / description
      Added value: +"Rows per page, 1 to 100; default 25. Keep paging until you have seen total rows."
    • addedInput schema / properties / sort / description
      Added value: +"status (the default: DOWN, PENDING, UP, PAUSED, newest first within each), name, or created_at (newest first)."
    • addedInput schema / properties / tag / description
      Added value: +"Keep items carrying these tags: a JSON array of up to 10 tags, each up to 50 characters, lowercased before matching. tag_match decides whether all or any of them must match."
    • addedInput schema / properties / tag_match / description
      Added value: +"all (the default): an item must carry every tag in tag. any: at least one of them."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "items": {
+      "items": {
+        "properties": {
+          "channel_ids": {
+            "items": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "grace_seconds": {
+            "type": "integer"
+          },
+          "id": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "last_duration_ms": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_ping_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_start_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_success_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "name": {
+            "type": "string"
+          },
+          "notification_cooldown_seconds": {
+            "type": "integer"
+          },
+          "overdue_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "period_seconds": {
+            "type": "integer"
+          },
+          "ping_url": {
+            "type": "string"
+          },
+          "state": {
+            "description": "Known values: PENDING, UP, DOWN, PAUSED.",
+            "type": "string"
+          },
+          "tags": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "updated_at": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "state",
+          "period_seconds",
+          "grace_seconds",
+          "ping_url",
+          "last_ping_at",
+          "last_success_at",
+          "last_start_at",
+          "last_duration_ms",
+          "overdue_at",
+          "notification_cooldown_seconds",
+          "is_active",
+          "created_at",
+          "updated_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "page": {
+      "type": "integer"
+    },
+    "pages": {
+      "type": "integer"
+    },
+    "size": {
+      "type": "integer"
+    },
+    "total": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "items",
+    "total",
+    "page",
+    "size",
+    "pages"
+  ],
+  "type": "object"
+}
  2. First observedv0.5.4

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the read-only/idempotent/non-destructive profile, but the description adds real substance beyond them: the PENDING→UP/DOWN/PAUSED state machine, the meaning of last_ping_at/overdue_at, and the paginated return shape ('items plus total, page, size and pages'). It does not discuss rate limits or auth, but for a read-only list tool this is a rich disclosure.

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 purpose and usage before field details, and each sentence carries routing or state information. The long field enumeration is mildly redundant given an output schema exists, but it is compact and not padded.

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?

Covers filters, sort behavior, sibling disambiguation, and result paging, which is everything an agent needs to call it correctly. Return-value detail slightly overlaps the output schema but does not leave any gap.

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 every parameter (q, tag, page, size, sort, tag_match) is already fully documented in the schema, including defaults and enum meanings. The description only echoes the sort ordering already in the schema ('sort status puts DOWN first'), adding no new syntax or semantics.

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?

Opens with a specific verb+resource ('Find heartbeat (cron / dead-man's-switch) monitors') and immediately enumerates the returned fields, so the agent knows exactly what this list yields. It also draws explicit boundaries against the two nearest siblings, list_monitors and get_heartbeat, making selection unambiguous.

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 concrete when-to-use cases ('get a heartbeat's id or ping_url', 'see which jobs are late'), an explicit when-not ('Probed URLs and hosts are monitors: use list_monitors for those'), and names get_heartbeat for the single-record case. All three routing decisions are stated rather than inferred.

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

Deploy Server

Other Tools