fettle-mcp

Overview Schema Source Related Servers Discussions Admin

List incidents

list_incidents

Read-onlyIdempotent

List an organization's monitor and heartbeat incidents, newest first, to see what is or was down and which alerts were sent.

Instructions

List the organization's monitor and heartbeat incidents, newest first, to see what is or was down and which alerts went out. Each item has id, monitor_id or heartbeat_id (exactly one is set), started_at, resolved_at (null while open), cause, cause_detail (the raw check error), acknowledged_at and notification_logs: the alerts sent, oldest first, each with id, channel_type (EMAIL, TELEGRAM, WEBHOOK, SLACK or DISCORD), destination (may be masked), event (TRIGGERED for the first alert and every reminder, RESOLVED for the recovery), sent_at, status (PENDING while a webhook, Slack or Discord delivery is still being tried, then SENT or FAILED) and error (the last delivery error). For one incident's full record use get_incident; for the checks behind it use list_check_results; incidents posted on a status page are list_status_page_incidents. An incident resolves by itself when its monitor or heartbeat recovers. Returns a page: items plus total, page, size and pages. An invalid value is a 422 naming the argument. Example: {"status": "open", "size": 50}

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number, 1 or more; default 1.
`size`	No	Rows per page, 1 to 100; default 25. Keep paging until you have seen total rows.
`cause`	No	Keep one failure cause, such as TIMEOUT, HTTP_5XX or HEARTBEAT_MISSED.
`status`	No	open or resolved (lowercase); omit it for both.
`monitor_id`	No	Keep one monitor's incidents: its uuid from list_monitors.
`period_days`	No	Keep incidents active within the last N days, 1 to 365. An open incident always qualifies, so with status open it changes nothing: use status resolved, or omit status, to see the window take effect.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`page`	Yes
`size`	Yes
`items`	Yes
`pages`	Yes
`total`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.6.1Oct 20, 2026

changedInput schema / properties / cause / description

Previous value: -"Filter by structured failure cause."New value: +"Keep one failure cause, such as TIMEOUT, HTTP_5XX or HEARTBEAT_MISSED."

addedInput schema / properties / monitor_id / description

Added value: +"Keep one monitor's incidents: its uuid from list_monitors."

addedInput schema / properties / page / description

Added value: +"Page number, 1 or more; default 1."

changedInput schema / properties / period_days / description

Previous value: -"Only incidents that were active within the last N days. An incident still open is always included, whenever it started. Combined with status=open this makes period_days a no-op, since every open incident already satisfies that arm — use status=resolved or omit status to see the window take effect."New value: +"Keep incidents active within the last N days, 1 to 365. An open incident always qualifies, so with status open it changes nothing: use status resolved, or omit status, to see the window take effect."

addedInput schema / properties / size / description

Added value: +"Rows per page, 1 to 100; default 25. Keep paging until you have seen total rows."

changedInput schema / properties / status / description

Previous value: -"Filter by open or resolved; omit for both."New value: +"open or resolved (lowercase); omit it for both."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "items": {
+      "items": {
+        "properties": {
+          "acknowledged_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "acknowledged_by": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "cause": {
+            "description": "Known values: TIMEOUT, DNS_FAILURE, CONNECTION_REFUSED, TLS_INVALID, HTTP_4XX, HTTP_5XX, HTTP_UNEXPECTED_STATUS, KEYWORD_MISSING, TOO_MANY_REDIRECTS, TARGET_BLOCKED, PORT_STATE_MISMATCH, INVALID_TARGET, HEARTBEAT_MISSED, HEARTBEAT_FAILED, UNKNOWN.",
+            "type": "string"
+          },
+          "cause_detail": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "heartbeat_id": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "id": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "last_notified_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "monitor_id": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "notification_logs": {
+            "items": {
+              "properties": {
+                "channel_type": {
+                  "description": "Known values: EMAIL, TELEGRAM, WEBHOOK, SLACK, DISCORD.",
+                  "type": "string"
+                },
+                "destination": {
+                  "type": "string"
+                },
+                "error": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "event": {
+                  "description": "Known values: TRIGGERED, RESOLVED, SSL_EXPIRY.",
+                  "type": "string"
+                },
+                "id": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "sent_at": {
+                  "type": "string"
+                },
+                "status": {
+                  "description": "Known values: PENDING, SENT, FAILED.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "channel_type",
+                "destination",
+                "event",
+                "sent_at",
+                "status",
+                "error"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "renotify_count": {
+            "type": "integer"
+          },
+          "resolved_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "updated_at": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "started_at",
+          "resolved_at",
+          "cause",
+          "cause_detail",
+          "last_notified_at",
+          "acknowledged_at",
+          "acknowledged_by",
+          "renotify_count",
+          "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"
+}

First observedv0.5.4Oct 20, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive, closed-world), yet the description adds substantial context: newest-first ordering, the self-resolving lifecycle, the 422 error shape on invalid values, and the notification delivery state machine (PENDING while a webhook/Slack/Discord delivery is retried, then SENT or FAILED with the last error). This goes well beyond the structured fields.

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

Conciseness3/5

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

Purpose and alternatives are front-loaded, but the body is one dense run-on paragraph enumerating return fields (id, started_at, resolved_at, cause, notification_logs, channel_type, destination, event, sent_at, status, error) that an output schema already carries. Much of that inventory does not earn its place against a structured output contract.

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 read-only filtered list with 6 optional parameters, the description covers scope, ordering, alternatives, resolution semantics, pagination and error behavior. An agent has everything needed to call it correctly and interpret the result.

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 description coverage is 100%, so the baseline is 3, but the description adds a worked example ({'status': 'open', 'size': 50}) showing a valid filter combination and reinforces pagination intent. It does not add per-parameter syntax beyond the schema, so it does not reach 5.

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 organization's monitor and heartbeat incidents, newest first') and immediately bounds the scope to what is or was down. It explicitly distinguishes itself from get_incident, list_check_results and list_status_page_incidents, so an agent can route without opening another 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?

Names the three alternative tools and the condition selecting each ('For one incident's full record use get_incident; for the checks behind it use list_check_results; incidents posted on a status page are list_status_page_incidents'). It also explains the resolution lifecycle, telling the agent an incident clears itself on monitor/heartbeat recovery.

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

Deploy Server