conventions

---
name: conventions
description: Conventions and gotchas for every UptimeRobot MCP tool call — monitor types, URL formats, HEARTBEAT URL handling, discovery-before-writes, pagination, time ranges, error codes, and output style. Use whenever you call any uptimerobot:* tool.
---

# UptimeRobot conventions

Apply these rules whenever you use any tool from the `uptimerobot` MCP server (`https://mcp.uptimerobot.com/mcp`).

## Monitor types

- Always pass `type` as a string enum — one of `HTTP`, `KEYWORD`, `PING`, `PORT`, `HEARTBEAT`, `DNS`, `API`, `UDP`. Do not pass numeric type codes; the MCP layer rejects them.
- `HEARTBEAT` monitors must **not** include a `url` on creation. The server generates `https://heartbeat.uptimerobot.com/m<id>-<hash>` and returns it. Show that URL to the user after creation so they can wire up the heartbeat sender.
- `PING`, `PORT`, `UDP`, `DNS`: `url` is a hostname or IP, never a full URL with scheme.
- `HTTP`, `KEYWORD`, `API`: `url` must be a full URL with scheme (`https://...`).

## Discovery before writes

- Before calling `update-monitor`, `update-monitor-status`, or referencing a monitor by ID, call `list-monitors` (optionally with `search`) to confirm the ID and current state.
- Before referencing an alert contact in `assignedAlertContacts`, call `list-integrations` and use an `id` from the response.

## Verification after writes

- After `create-monitor` or `update-monitor`, call `get-monitor-details` to confirm the stored state before telling the user the change is live. Read-after-write replication can lag a few seconds.

## Intervals and plan limits

- Interval is in seconds. Minimum is 30s and depends on the plan. If the server returns `-28002 subscription_limit_exceeded`, do not retry — the plan cannot support that interval or monitor type. Tell the user.
- Do not retry `-28001 monitor_limit_exceeded`. Recommend deleting unused monitors or upgrading the plan.
- Plans are Free, Solo, Team, Enterprise. Never reference a "Pro" or "Business" plan — neither exists.

## Time ranges

- `timeRange` accepts `"24h"`, `"7d"`, `"30d"` (range 1h–90d), or an ISO 8601 interval `"<start>/<end>"` (start before end, 1h–90d). Default is `"7d"`.
- For anything older than 90 days, inform the user that UptimeRobot's MCP endpoints cap at 90 days of history.

## Pagination

- Paginated tools (`list-monitors`, `list-incidents`, `list-integrations`) return an `instructions` field with the exact next-call JSON. Follow it verbatim; cursor shape is opaque.

## Errors

- `-28001` monitor limit, `-28002` subscription limit, `-29001` invalid params (incl. blacklisted URLs), `-30001` / `-30003` not found, `-31002` access denied (authorized account lacks write permission).
- `-31001 user_not_found` means the OAuth grant is missing/expired/revoked — do not surface it raw; invoke the `uptimerobot:setup` skill to re-authenticate.
- HTTP 429 is the only code worth retrying (exponential backoff + jitter). Everything else is a client error — surface it to the user.

## Output style

- Do not echo API keys, incident log contents, or traceroute hops unless the user explicitly asks.
- When summarising many monitors, group by state (`DOWN` first, then `PAUSED`, then `UP`) and show counts before detail.
- When quoting uptime percentages, always cite the time range.