incident.io

Create an action on an incident.

Actions are remediation tasks captured during an incident to help resolve it now — restarting a service, rolling back a deploy, investigating a spike. Only capture work that is part of resolving the incident.

Actions are deliberately distinct from follow-ups. Work to be tracked for after the incident is resolved — fixing a runbook, adding monitoring, a postmortem task — is a follow-up, not an action: use follow_up_create for that. Someone saying the word "action" does not on its own make it one.

The action is created with status "outstanding". An action with the same description already open on the incident is rejected rather than duplicated.

Streams are a special case: a closed stream can still have its existing actions managed, but no new ones created, because a stream has no follow-up flow to move the work into.

Returns the created action.

Delete an incident action.

Use this when an action was captured by mistake, or is no longer wanted. Use action_update to mark work that was considered and rejected as "not_doing" instead — that keeps the decision visible on the incident, where deleting hides it.

Deleting is separate from updating because it is a different operation: it archives the action, so it stops appearing in action_list and can no longer be edited. It cannot be undone through these tools.

This does not convert the action into a follow-up. To carry work forward past the incident, create a follow-up with follow_up_create and then delete the action.

Returns the deleted action.

List incident actions with optional filters and pagination.

Actions are remediation tasks captured during an incident to help resolve it now — restarting a service, rolling back a deploy, investigating a spike. They are distinct from follow-ups, which track the work that happens after an incident is resolved: use follow_up_list for those.

Each result includes: description, status, assignee, creator, the parent incident, and timestamps.

Filters (all optional):

• incident_id: filter to a specific incident (accepts ID, external ID, or reference like INC-123)
• assignee_id: filter by assignee user ID (use your own ID from config://organisation to find "my actions")
• status: one or more of outstanding, completed, not_doing
• created_after / created_before: date range for when the action was created (yyyy-mm-dd or RFC 3339)

Deleted actions, and actions that have been converted into follow-ups, are never returned.

Pagination: results are ordered oldest first. Use page_size (default 10, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results. "total_count" is how many actions match the filters altogether, so use it for counts rather than counting one page.

Use action_create to capture new remediation work, and action_update to reassign one or mark it done.

Update an existing incident action. Only the fields you provide will be changed — omitted fields are left as-is.

Use action_list to find action IDs. Use action_create to capture new remediation work.

Updatable fields:

• description: reword the action
• assignee_id: assign to a user (empty string unassigns). The assignee must be a participant in the incident.
• status: change to outstanding, completed, or not_doing

Actions cannot be deleted through this tool: "deleted" is not an accepted status, because deleting archives the action and needs a different permission. Use action_delete for that. Prefer status "not_doing" when the work was considered and rejected, which keeps the decision visible where deleting hides it. An action cannot be converted into a follow-up here either — create the follow-up with follow_up_create instead.

An action that has already been deleted, or converted into a follow-up, can no longer be edited.

Returns the updated action.

Attach an existing alert to an incident, marking it as related.

Use this when alerts should be recorded against an incident that already exists — for example after finding firings with alert_list. The alert is not moved or deleted; it is linked to the incident as related.

Use alert_list or alert_show to find an alert's ID, then pass the alert_id and incident_id here. The incident_id accepts a ULID, numeric external ID, or reference like INC-123. If the alert is already related to the incident, this is a no-op and still returns success.

If someone previously marked this alert unrelated to this incident, the call is refused with an "explicitly_unrelated" error rather than quietly undoing their decision. Tell the user it was explicitly unrelated and ask whether to override; if they confirm, retry with re_relate set to true, which relates it again and returns status "re_related". Don't set re_relate on a first attempt.

To declare a new incident for alerts rather than attach to an existing one, use alert_create_incident.

Declare a new incident for one or more alerts, attaching them to it as related.

Use this when firing alerts warrant an incident and none exists yet. It creates the incident and relates every alert in one atomic step, so you never end up with an incident that is missing the alerts that justified it.

Prefer this over incident_create followed by alert_attach: this links the incident to its originating alert and rolls the whole thing back if attaching fails.

Before declaring, check for an existing open incident for the same problem (incident_list with status_category triage/active/paused). If one exists, use alert_attach instead of declaring a duplicate.

Required: alert_ids (at least one) and name.

Alerts that belong to an alert group are rejected, with an "alert_ids" validation error naming them and nothing created. Alert groups are attached as a unit, which this tool can't do — tell the user to attach the group from the dashboard, or to ungroup those alerts first, then retry with the rest.

Everything else behaves exactly as incident_create: the incident starts in triage unless you give both severity_id and an active incident_status_id, never invent a severity the user hasn't stated, and organisations that require custom fields at declare time return a "missing_required_fields" validation error naming what is missing. Read config://organisation for severity, status, type, custom field and role IDs.

Private alerts can only go on a private incident — pass visibility "private" for those, or the call is rejected.

A retry of the same request attaches the alerts to the incident it already created, with already_existed set — say it was already declared rather than claiming you declared it.

Returns the incident and the alerts attached to it. Use incident_show for full details.

Detach an alert from an incident, marking it as unrelated.

Use this when an alert was routed to the wrong incident and needs to be removed. The alert is not deleted — it is marked as unrelated to this incident.

Use alert_show to find an alert's ID and its linked incidents, then pass the alert_id and incident_id here. The incident_id accepts a ULID, numeric external ID, or reference like INC-123.

List alerts with optional filters and pagination. Use alert_show for full details on a specific alert.

Each result includes: title, status, alert source (with type), priority, deduplication key, and links.

Use 'include' to request additional fields on each result:

• tags: names of tags applied to the alert

Filters (all optional):

• query: search alert titles and descriptions
• status: one or more of firing, resolved
• alert_source: one or more alert source config IDs (use alert_source_list to discover these)
• priority: one or more priority IDs (see config://organisation resource for IDs)
• deduplication_key: exact match on a deduplication key
• attributes: filter by alert attribute values (object mapping attribute ID to array of values, see config://organisation for attribute IDs)
• tag: one or more alert tag names, matched case-insensitively (use alert_tag_list to discover them); returns alerts carrying any of them. Archived tags are ignored.
• created_after / created_before: dates to bound the time range (yyyy-mm-dd or RFC 3339)
• has_related_incident: true for alerts attached to an incident, false for unattached

By default, results are limited to alerts created in the last 30 days. Set created_after to look further back, but prefer a narrow time range alongside other filters — wide ranges on large orgs are slower and more likely to time out.

By default, alerts caught by maintenance windows are excluded from results.

Pagination: results are ordered newest first. Use page_size (default 15, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Tip: if you need counts, trends, or noise analysis, use alert_stats first — it's much more efficient than paginating through alert_list. Use alert_list when you need to browse specific alerts or inspect their details.

Understanding alert attributes: alerts carry structured attributes (e.g. team, service, environment, feature) that describe what they relate to. Read config://organisation to see what attributes are configured, then use the attributes filter to slice alerts by these dimensions. For example, filtering by service helps answer "which alerts fire for the payments service?" or by team for "what's the alert load for the platform team?"

List notes attached to an alert.

Notes capture context, decisions, and investigation findings against an alert without needing to declare an incident. Each result includes the markdown content, author, and timestamps. Notes the caller cannot see (e.g. due to private-alert access control) are not returned.

Content is returned as Markdown. Supported formatting includes headings, bold/italic/strikethrough, inline and fenced code, lists, blockquotes, links, GitHub-flavoured tables, and horizontal rules. Raw HTML, image syntax, task lists, and footnotes are not rendered.

Pagination: results are ordered oldest first. Use page_size (default 10, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Pass "id" to fetch a single note instead of the page.

Use alert_note_manage to write, edit or remove a note.

Write, edit or remove a note on an alert.

Notes capture context, decisions and investigation findings against an alert without declaring an incident.

Actions:

• create: add a note to an alert. Takes alert_id and content.
• update: replace a note's content. Takes id and content.
• delete: remove a note. Takes id.

Content is Markdown. Headings, bold/italic/strikethrough, inline and fenced code, lists, blockquotes, links, GitHub-flavoured tables and horizontal rules all render. Raw HTML, images, task lists and footnotes are stripped or rendered as plain text.

Only a note's author can edit or delete it. Read notes with alert_note_list.

Resolve one or more firing alerts, marking them resolved now and recording who did it.

Use this to close the loop after triage — for example once you've confirmed a firing alert is noise, or the underlying problem is fixed. Use alert_list or alert_show to find alert IDs first.

Pass several alert_ids in one call rather than calling once per alert: a batch takes one row lock pass and notifies responders once, where repeated single calls are slower and noisier. Up to 50 per call.

Resolving is idempotent — an alert that is already resolved comes back as already_resolved, not an error.

Not every alert can be resolved here. Some sources own resolution themselves. For a few (PagerDuty, Opsgenie, BigPanda, Jira, and Wiz when configured for write-back or local resolution) resolving here works as normal. For the rest (ServiceNow, Zendesk, GitHub issues, and Wiz when configured as the source of truth) the alert clears only when that system closes the underlying ticket: those come back as externally_resolved, naming the source. Tell the user to close it there rather than retrying.

The response reports every alert you asked about with its own outcome:

• resolved: was firing, now resolved
• already_resolved: was resolved before this call, nothing changed
• externally_resolved: the alert's source resolves its own alerts, so it is still firing
• no_permission: you lack the alerts.resolve permission for that alert's team
• not_found: no alert with that ID, or you cannot see it
• not_resolved: still firing for some other reason (the message says more)

Read "resolved" for how many actually changed, and report the exceptions rather than claiming everything was resolved.

To resolve the page an alert raised rather than the alert itself, use escalation_respond. Alerts and escalations are separate: resolving an alert does not acknowledge its page.

Look up an alert by ID and return its details.

Returns: title, description, status, deduplication key, alert source (with type), priority, tags, links (source, dashboard, silence), and any linked incidents.

Use 'include' to request additional sections:

• payload: the raw JSON payload from the alert source (only available for firing alerts)

The response includes linked incident IDs. Pass these to incident_show with include: ["investigation"] to see the full investigation for each linked incident.

List configured alert sources for this organisation.

Returns the ID, name, and source type (e.g. datadog, sentry, grafana, http) for each alert source. Use alert source IDs to filter alert_list results by source.

This is not paginated — alert source lists are typically small.

Count alerts grouped by one or more dimensions, returning aggregate statistics.

Use this tool instead of paginating through alert_list when you need counts, breakdowns, or trend data across many alerts — for example "how many alerts by source this week?" or "what proportion of alerts result in incidents?"

Dimensions (combine freely in the group_by array):

• status: group by status (firing, resolved)
• priority: group by alert priority (e.g. Critical, Urgent, In-hours)
• source: group by alert source name (e.g. Sentry, Grafana, Datadog)
• has_incident: group by whether the alert is attached to an incident (true/false)
• team: group by the org's configured team. Resolves the team alert attribute, so its counts agree with filtering alerts by team. Multi-value: alerts tagged with several teams are counted under each; untagged alerts show as "None".
• tag: group by alert tags. Multi-value: alerts carrying several tags are counted under each; untagged alerts show as "None". Archived tags are ignored, so an alert whose only tags are archived is counted under "None".

Scoping to a team: use the team filter for exact teams, or team_part_of to include a parent team and all its sub-teams in the hierarchy (e.g. a "Go To Market" parent covering Sales, Marketing, etc.). Combine team_part_of with group_by ["team"] to break a parent down into its sub-teams. Scoping to tags: use the tag filter with alert tag names to include alerts carrying any of those tags.

• attribute:<attribute_id>: group by any alert attribute's value (e.g. team, service, environment). Read config://organisation to find attribute IDs. Array attributes are flattened so each value is counted individually; catalog-typed attributes are resolved to names.
• week: group by ISO week (e.g. 2026-W03)
• month: group by calendar month (e.g. 2026-01)
• quarter: group by calendar quarter (e.g. 2026-Q1)

Each group includes a count, a workload breakdown (responder time from linked incidents, split by working hours, late evening, and overnight), and sample alert IDs that you can pass to alert_show for detail. This lets you answer "which alert sources generate the most on-call work?" directly.

Note on workload scope: workload is summed from all incidents linked to the alerts in each group, regardless of when those incidents were created. This means an alert created in December linked to an incident from November will include November's workload. This is intentional — it measures the total impact generated by the alert — but means alert workload totals may differ from incident_stats workload for the same date range.

By default, alerts caught by maintenance windows are excluded.

The tool processes at most 25,000 alerts. If more match, the response sets "truncated": true — narrow the date range for accurate results.

Conversion rate: to calculate what proportion of alerts become incidents, group by ["source", "has_incident"]. For each source, conversion rate = count(has_incident=true) / total count. Sources with low conversion rates are noise candidates.

Cross-reference: use incident_stats(group_by: ["alert_source"]) to see how alert sources map to incident volume and workload over time. This traces the full path from alert noise through to responder cost. Note that alert counts will be higher than incident counts for the same source, since multiple alerts can link to the same incident.

Deeper analysis: many organisations have a small number of alert sources (e.g. one Datadog integration) but rich alert attributes (team, service, environment, feature). Group by attribute:<attribute_id> to break volume, conversion and workload down by these — for example group_by ["attribute:<service_id>", "has_incident"] to find the noisiest services, or group_by ["team"] for per-team alert load. Read config://organisation to discover attribute IDs. Use alert_list when you need to browse the individual alerts behind a number.

Structured analysis: for a comprehensive report with playbooks, themes, and recommendations, call analysis_start first — it provides step-by-step methodology and a branded report template. Use this tool directly only for quick, focused queries.

Add, remove, or replace tags on up to 50 alerts.

Use alert_list or alert_show to find alert IDs. Tags must already exist; this tool never creates them.

Choose operation add to keep existing tags and add these, remove to keep all tags except these, or set to replace the complete tag set. An empty set clears every tag.

References are validated before any alert changes. If any alert or tag is unknown, the whole call fails with alerts_not_found or tags_not_found and nothing is changed. Otherwise each alert reports updated, too_many_tags, or no_permission.

List the organisation's active alert-tag vocabulary.

Alert tags are names responders apply to alerts after they arrive (for example "noisy" or "known issue"). This tool returns the live vocabulary — archived tags are excluded. Each result is an id and name only; it does not include how often a tag is used.

Use this to discover tag IDs and names. Pass a query to filter by name substring.

Pagination: results are ordered by name, case-insensitively. Use page_size (default 25, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Start an operational analysis session. Returns a download URL for a tar.gz archive containing everything needed to run analysis: playbooks with step-by-step methodology, your organisation's configuration (severity IDs, custom fields, roles), reference materials, and a branded HTML report template.

Download and extract the archive, then follow the playbook steps using the MCP data tools (incident_stats, alert_stats, escalation_stats, etc.).

Ask the incident.io AI agent a question about your organisation's incidents, on-call schedules, alert routes, and operational setup.

Use this tool for conversational questions that need reasoning, entity resolution, or multi-step investigation — for example "what happened on my last on-call shift?", "summarise recent incidents for the payments team", or "who is on call for the backend service?". The agent can query schedules (including past shifts and overrides), search incidents, look up catalog data, and manage schedule overrides.

Pass incident_id to focus the agent on that incident, with its full investigation data and management tools: it can update the incident, create follow-ups, escalate, and draft status updates — for example "what caused this incident?" or "draft a status update for stakeholders". It may act on the incident to satisfy the request, so for a purely-read question prefer incident_show with include: ["investigation", "postmortem"].

For structured data needs (counts, filtering, pagination), prefer the direct tools: incident_stats for analytics, incident_list for browsing, incident_show for details. The ask tool adds latency and cost from the inner LLM call, so only use it when you need the agent's reasoning.

Pass session_id from a previous response to continue a multi-turn conversation.

Ask the telemetry-focused AI agent a question, or run a native query verbatim. This agent queries logs, metrics, traces, and dashboards across your connected observability platforms (Datadog, Grafana, Splunk, Honeycomb, etc.). Read the telemetry://datasources resource to see which platforms are connected.

There are two modes:

1. Natural language (default): set "question" and let the agent plan and translate the query. Use this to correlate incident data with observability signals — for example "what do the error rates look like for the payments service?", "show me the logs around the time of INC-123", or "query the CPU dashboard for the last hour".

2. Passthrough (verbatim): set "passthrough" with a complete native expression, its query_type (log_query | metric_query | span_query | sql_query), and the datasource_id to run it against. The expression is the datasource's native query language for log/metric/span (LogQL, PromQL, TraceQL) or a SQL statement for sql_query, and runs exactly as written — the planner is bypassed, nothing reshapes it. Use this when you already hold the precise query (e.g. you authored it from the code, a runbook, or the user). "question" is optional in this mode; when supplied it becomes the recorded query's purpose and steers any follow-up analysis. If you're unsure whether the labels, fields or metric names a verbatim expression references exist on the datasource, call telemetry_inspect on the same datasource_id to confirm them first — a typo fails the whole query. You only need it when you lack prior proof the vocabulary is sound: earlier results this session that already surfaced those labels and metrics, or an expression the user handed you verbatim, are proof enough.

Pass session_id from a previous response to continue a multi-turn conversation.

List entries in a catalog type with optional search and pagination.

Catalog entries are instances of a type — for example, entries in a "Service" type might include "Payments API" or "User Auth". Each entry has attribute values defined by the type's schema, and may have aliases (alternative identifiers like EP011 for escalation paths or owner/repo for GitHub repos).

Required: catalog_type_id (the ID or type_name of the catalog type — use catalog_type_list to discover available types).

The response includes the type's attribute schema alongside entries. Attribute values use attribute names as keys. Reference attributes (those pointing to other catalog types) are formatted as "Name (ID)" so you can read the name directly and use the ID to look up the referenced entry via catalog_entry_show if needed.

Pagination: entries are ordered by name (or rank for ranked types). Use page_size (default 25, max 250) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Look up a catalog entry by ID and return its full details.

Returns the entry with all attribute values and aliases — unlike catalog_entry_list, array attributes are not truncated. The response includes the type's attribute schema for context. Aliases are alternative identifiers for the entry (e.g. EP011 for escalation paths, owner/repo for GitHub repos).

Use this when you need the complete set of values for a specific entry, e.g. all members of a team or all dependencies of a service.

List catalog types configured in this organisation.

The catalog is a connected map of your organisation's data — it contains types like Service, Team, Feature, Customer, and anything else relevant to your organisation. Each type has a schema of attributes that define what data its entries hold.

Use this tool to discover what types exist, then use catalog_entry_list to browse entries of a specific type.

Returns: name, type_name, description, and the attribute schema for each type (excluding derived attributes like backlinks and paths).

This is not paginated — organisations typically have a manageable number of catalog types.

List merged code changes (pull or merge requests) newest merge first, with filters on repository, merge time, deploy status, title and author.

Each row has the change's ID, permalink, title, author, merge time, tags, how many deploy events are linked to it, the environments they named and the latest deploy time. Pass an ID to code_change_show for the description, files, commits and the full deploy history.

Filters:

• repository_id or repo: scope to one repository. Every row carries repository.id for the former; the latter takes an owner/name slug
• merged_after / merged_before: the merge window. Only merged changes are listed. When merged_after is omitted the window is the 14 days before merged_before (or before now), and the response echoes the window it used, so widen merged_after if you need more
• deployed_to: only changes with a linked deploy to that environment, or 'any' for at least one
• query: substring match on the title, within the window
• author: exact provider username, within the window

A repo that matches no tracked repository still lists any rows carrying that slug, and the response note names the closest tracked repositories so a misspelling is a one-step retry. Open and unmerged changes are not listed here; look one up by permalink with code_change_show.

Pass next_cursor as 'after' to fetch the next page. There is no total count: while has_more is true the rows you have are a partial set, so narrow the window or the filters rather than paging through a long history.

Look up one code change (a pull or merge request we have ingested from the organisation's code host) and everything we know about when it was deployed.

Find it by its provider URL (permalink), by the ID a code_change_list row gave you, or by a merge commit SHA when you have a commit from a deploy or a log line and want the change behind it.

Returns: title, repository, author, state (open, merged or closed), opened/merged times, the merge commit SHA, the change's description and AI summary, tags, the files touched and the commits, then 'deploys': one entry per deploy event linked to this change, with the environment, component, deploy type (full, partial, rollback) and how the link was made. 'deploy_tracking' says how to read that list: whether this repository has deploy tracking at all, which environments it deploys to, and the typical merge-to-deploy time. Read its note before concluding a change has or has not shipped: deploys are linked from deploy events, so an empty list is strong evidence only when the repository is tracked, and never proof.

Use 'include' for more:

• diff: the code diff (capped; the permalink has the full change)
• comments: review comments and their replies

To browse what merged into a repository, or to find a change by title, use code_change_list.

Create a cover request asking for volunteers to cover a shift.

By default the system identifies candidates from the schedule's rotation members and notifies them directly; pass candidate_user_ids to ask specific people instead — e.g. just the one person the requester named. The requester receives a summary tracking candidate responses.

The request is created on behalf of the authenticated user, who must be on call during the requested window — you can only ask for cover of your own shift. Requires user authentication (e.g. OAuth) rather than an API key.

Times must be UTC RFC 3339 ending in Z; never convert a wall-clock time by writing an offset yourself. Prefer this over schedule_override_create when someone asks for cover rather than instructs a change: a cover request asks first, an override changes who gets paged immediately.

List cover requests: asks for someone else to take a stretch of an on-call shift.

Use this to find the cover request ID that cover_request_respond and cover_request_manage need — e.g. "remind people about my cover request" or "accept Milly's request" starts here.

Only current and future requests are returned (a request whose window has fully passed is no longer actionable). By default only pending ("created") requests show; pass state to see accepted, declined, or cancelled ones. Pass user (a user ID, or "me" for the caller) to narrow to requests that user raised or is a candidate for, and schedule_id to narrow to one schedule.

Each result carries the request's window, state, message, candidates with their response state, and — for partially covered requests — which ranges are covered and which still need someone.

Manage a cover request as its requester or creator.

Actions:

• cancel: cancel the request. Only works while it is still pending (nobody has accepted yet).
• accept_offer: accept a candidate's partial coverage offer, creating an override for the offered ranges. Requires candidate_user_id.
• send_reminder: nudge candidates who haven't responded yet.

Only the requester or creator can manage a request, so this requires user authentication (e.g. OAuth) rather than an API key.

Respond to a cover request you are a candidate on.

• accept: accept the full request. An override is created automatically so you are placed on call for the requested window.
• decline: decline the request; you are removed from consideration.
• offer: offer partial coverage for specific time ranges. The requester then accepts or declines your offer.

The response is attributed to the authenticated user, who must be a candidate on the request. Requires user authentication (e.g. OAuth) rather than an API key. Offer time ranges must be UTC RFC 3339 ending in Z.

Create a native Insights dashboard from a set of organised charts and tiles.

Call insights_chart_options first. Use preset_key whenever a preset fits the request: it carries valid organisation-specific defaults. Use chart only for a combination that is not already a preset, starting from a preset's chart in insights_chart_options. Add a trend or KPI tile by its key from the tiles list.

Each chart and trend tile becomes a full-width row, and KPI tiles next to each other share a row, grouped under the supplied section heading. The result is a normal native dashboard that the user can open and refine with the visual editor.

When the request names a team, custom field value, or anything else to filter by, find it in insights_chart_options. If nothing matches, tell the user what you looked for and the closest options that exist, and ask before you create the dashboard. Never drop a filter the user asked for without telling them.

This creates the dashboard immediately. Call it only after the user has asked for a dashboard and the requested contents are clear; ask a focused question first when an important grouping, time range, or metric is ambiguous. Returns a direct link to the created dashboard.

Look up which values a custom field accepts, so you can set it to a real one.

Call this before setting a custom field on incident_create or incident_update. Pass custom_field_id — either the field's ID or its exact name — and optionally a search term to narrow a long list. You do not need to know the field's type first: this handles every type.

There is no cursor here. When pagination.has_more is true, pass a search term to narrow the list rather than asking for the next page.

Each value comes back with an id and a human-readable value. The id is what you set: the response's set_using tells you which key of a custom_field_entries value to put it in (value_option_id for option fields, value_catalog_entry_id for catalog-backed ones).

Read the field's own flags before writing to it:

• can_be_set is false when an expression fully derives the field. Setting it will fail, so don't try.
• allows_new_values is true when the field is tag-like, so people can add values to it. You can still only set a value that appears in this list.
• accepts_multiple tells you whether you may set several values at once.

Text, link and numeric fields configure no values at all. They return an empty list with a note, which is not the same as an option field that has no options configured.

This is the best way to find the values a custom field accepts.

Search the organisation's synced knowledge base documents — runbooks, guides, post-mortems, architecture notes and similar — indexed from sources like GitHub, Notion, and Confluence.

Two matching modes are supported, and you can pass both for higher recall:

• queries: natural-language questions or phrasings, matched semantically against document content
• keywords: specific names, terms, or identifiers, matched against document summaries

Returns compact summaries (id, title, generated summary and tags, source system and URL), not full content. Matches are sorted alphabetically by URL — judge relevance from the summaries and tags, not the order. Each match may list refers_to: other indexed documents it links to, worth considering as follow-up reads. Pass a result's id to document_show to read its full content.

Use this to find operational knowledge, e.g. the runbook for a failing system or what a past incident concluded. This covers the organisation's own documents only, and not incident.io's own product documentation — it will not tell you how an incident.io feature behaves or how to configure one. For a synthesised answer to a broad question, prefer the ask tool.

Read a document from the organisation's synced knowledge base, returning the full text content (typically markdown) alongside its title, generated summary and tags, source system, and URL.

Name the document by its ID from document_search, or by its file path when it is a file in a synced plugin: either under the plugin's mount (/plugins/<plugin>/runbooks/lock-wait.md) or relative to the plugin root (runbooks/lock-wait.md). Source URLs are not accepted. Very large documents are cut at a size cap, signalled by content_truncated; the source URL links to the complete document.

Use this once search has surfaced a promising document and you need its actual content, e.g. to follow runbook steps or quote a post-mortem.

Use 'include' to request additional sections:

• notes: problems recorded against the document by incidents and by assessed skill loads, newest first. Each note says what the document gets wrong, quotes the passage it is about, proposes an edit, and carries a status: open, or likely_resolved when the quoted passage is no longer in the text. Use them to decide what to fix in a runbook. A note's skill_usage_ids are the loads that produced it; pass the document to extension_skill_usage_list to see every load that worked from it.

Aggregate incident duration metrics (e.g. time to acknowledge, time to resolve) grouped by one or more dimensions, returning per-group statistics.

Use this for MTTX-style questions — "what's our median time to resolve for P1s this quarter?", "how has time to acknowledge trended by month?", "which team resolves incidents fastest?". Each group reports count, mean, p25, p50 (median), p75, p90, min, and max, all as durations in hours.

Dimensions (combine up to 2, at most one time bucket):

• metric: which duration metric the numbers belong to (e.g. Time to resolve vs Time to acknowledge). Group by this whenever more than one metric is in play, otherwise different metrics are pooled into one meaningless number.
• severity: group by severity level (e.g. Critical, Major, Minor)
• week / month / quarter: group by time bucket (bucketed by incident report time)
• custom_field:<field_id>: group by a custom field's values (read config://organisation to find field IDs)

By default all configured duration metrics are included — pass duration_metric_ids to restrict to specific ones. Zero-length durations are excluded, and each metric honours its own paused-time configuration, matching the MTTX dashboard.

Date range: durations are measured over incidents reported within the window. Supply created_after / created_before derived from the question; if omitted the window defaults to the last 90 days. A very wide window over a large organisation can time out — narrow the range if that happens.

By default test and tutorial incidents are excluded and declined/canceled/merged incidents are excluded. Provide explicit status_category or mode filters to override these defaults.

Cross-reference: use incident_stats for counts and workload (this tool is about how long incidents take, not how many there are), and incident_list with include: ["durations"] to see per-incident durations behind a group.

Raise an escalation to page a specific user or an escalation path. The words "escalate" and "page" are synonymous.

Escalations wake people up and cannot be undone. Paging the wrong person, or paging when nobody asked you to, is the worst mistake this tool can make, so it drafts by default.

Choosing an action

• action=suggest (the default) — draft an escalation for a person to accept, edit or decline. Use it whenever the request was implicit, the target is uncertain, or the target is an escalation path.
• action=execute — page immediately. Only when the user explicitly asked for someone to be paged AND you have exactly one unambiguous user ID. To page a draft a human has already reviewed, pass action=execute with only suggestion_id — it is applied verbatim. Anything ambiguous — an escalation path, several users, or paging whoever asked — is drafted for confirmation instead of paged.
• action=edit_suggestion — revise a draft. Pass suggestion_id plus only the fields you want changed; anything omitted keeps the draft's value. A user and an escalation path are alternative targets, so setting either one clears the other.

When not to use it

• Information requests: "who's on call for payments?", "which teams can I page?". Answer those with escalation_path_list, schedule_show or catalog_entry_list. Naming who you could page is fine; paging them is not.
• Changing who is on call. This tool cannot edit a schedule or an escalation path.
• Something you can't do but a human could. The answer is never to page someone; say what you can't do.

Parameters

• Give exactly one of user_ids or escalation_path_id. Never both, never neither. Prefer a user ID when you have a specific person in mind.
• incident_id is optional — an escalation can stand alone. With an incident, title defaults to the incident's name; without one, title is REQUIRED, because the person paged needs to know what for.
• description is required, and should say what expertise or action is needed. Keep names, incident numbers and priorities out of it. Good: "Database performance issue requires your PostgreSQL optimisation expertise".
• Pass real ULIDs only. If you cannot find the ID you need, ask rather than guessing, and never fall back to a fuzzy match.

What a draft does

From a chat thread the draft is posted as a card in the conversation. From any other caller it is created without a card, so show it to the user yourself and find it again with suggestion_list; a person can accept it from the dashboard. card_posted on the result tells you which happened. A draft whose card lives in a conversation must be edited there (e.g. via ask with incident_id).

List escalations (also known as "pages") with optional filters, newest first.

Use this for anything about pages that have already happened: "why was I paged?", "how many times was I paged last night?", "has that page been acked?", "find the page a teammate sent me". Pass user: ["me"] when someone asks about their own pages.

Each result includes the escalation's ID, title, status, priority, escalation path, who raised it, who was paged, when it was acked and the acker's user ID, and the linked alert and incident. Use escalation_show for full details on a specific escalation.

Filters (all optional):

• query: search escalation titles
• status: one or more of pending, triggered, acked, resolved, expired, cancelled, snoozed, pending_repeat. What each means:
• pending: created but nobody has been paged yet
• triggered: someone is currently being paged and hasn't responded
• acked: someone acknowledged the page and is handling it (stops it climbing the path)
• resolved: the page is done (acked and closed out, or the linked incident/alert resolved)
• expired: nobody acknowledged before the escalation path ran out of levels to try
• cancelled: called off before it completed
• snoozed: temporarily silenced, to re-trigger later
• pending_repeat: acknowledged but set to page again after a delay (a repeating reminder)
• escalation_path: one or more escalation path IDs
• priority: one or more priority IDs (see config://organisation for IDs)
• user: one or more user IDs, or "me" for the caller
• incident: one or more incident IDs
• alert: one or more alert IDs
• created_after / created_before: bound the time range

Use page_size to set the page length (default 15, max 50). Pass "next_cursor" back as "after" to fetch the next page.

List escalation paths configured in this organisation.

Escalation paths define who gets paged and in what order when an alert fires or someone manually escalates. Each path has levels — level 1 is paged first, then level 2 if nobody acknowledges, and so on. Each path has a short_id (e.g. EP011) that serves as a human-readable alias.

Use escalation_path_show to see the full ladder with who is currently on call at each level. You can search by name or short_id.

Pagination: results are ordered by name. Use page_size (default 15, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Look up an escalation path and show who would be paged at each level.

Shows the full escalation ladder, resolving schedules to their current on-call users. Each level also names the schedules it pages (and the rotation, when it pages just one), which answers "which paths use this schedule". When the path has conditional branches (e.g. different paths for different priorities or working hours), all branches are shown with the currently active branch marked.

Level 1 is paged first — if nobody acknowledges within the time-to-ack window, level 2 is paged, and so on.

Use this to answer questions like "who would get paged if this alert fires?", "what does the backend escalation look like?", or "who's first-line on-call for this path?"

Use schedule_show to see the full rotation details for any schedule referenced in the path. Use escalation_stats(group_by: ["path"]) to see paging volume and ack rates for this path over time.

Respond to an active escalation (page) on behalf of the authenticated user.

Use escalation_list to find active escalations, then respond with:

• ack: acknowledge the page — stops it from climbing the escalation path. Use when you or an agent are handling the issue.
• nack: decline the page — the escalation continues to the next level. Use when you cannot handle it.

Returns the updated escalation with its new status.

Requires user authentication (e.g. OAuth) rather than an API key, because the response is attributed to a specific user.

Look up an escalation (page) by ID and return its details.

An escalation is what happens when someone gets paged — it tracks who is being notified, whether they've acknowledged, and the full history of the page.

Returns: title, description, status, priority, escalation path, creator, linked incident and alert IDs, who is being paged (targets with urgency), and the full state transition history — including who acknowledged it, by name, and when.

Count escalations (pages) grouped by one or more dimensions, returning aggregate statistics with workload from linked incidents.

Use this tool instead of paginating through escalation_list when you need counts or trend data — for example "how many pages per escalation path this week?" or "what's our ack rate?"

Dimensions (combine freely in the group_by array):

• status: group by outcome (pending, triggered, acked, resolved, expired, cancelled, snoozed). "Cancelled" means the page was automatically cancelled because the underlying alert resolved or was attached to an incident — it is system-initiated, not user-initiated. Exclude cancelled from ack rate calculations.
• priority: group by priority (e.g. Critical, Urgent, In-hours)
• path: group by escalation path name (e.g. "Engineering", "SRE On-call")
• team: group by the team that owns the escalation path. Resolves through escalation path ownership, so its counts agree with filtering escalations by team. A path owned by several teams is counted under each; escalations on a path with no team owner show as "None".
• user: group by the user(s) who were paged. Shows user names. An escalation can target multiple users across different levels, so the same escalation may appear under multiple users. Useful for assessing individual on-call burden.
• time_of_day: group by when the escalation was created in UTC — working_hours (09:00-18:00 Mon-Fri), late_evening (18:00-23:00 any day + weekend daytime 09:00-18:00), or overnight (23:00-09:00)
• week: group by ISO week (e.g. 2026-W03)
• month: group by calendar month (e.g. 2026-01)
• quarter: group by calendar quarter (e.g. 2026-Q1)

Scoping to a team: use the team filter for exact teams, or team_part_of to include a parent team and all its sub-teams in the hierarchy. Both resolve through escalation path ownership. Combine team_part_of with group_by ["team"] to break a parent down into its sub-teams.

Key metrics to derive from the results:

• Ack rate: to calculate, group by ["path", "status"] then compute resolved / (resolved + expired) per path. Low rates indicate paging fatigue or coverage gaps.
• Out-of-hours load: group by time_of_day to see working_hours vs late_evening vs overnight split. Overnight pages with low ack rates are the highest priority to fix.
• Path comparison: group by path to see which teams are paged most
• Workload per group: each group includes responder-hours from linked incidents, split by working hours, late evening, and overnight

Each group includes a count, workload breakdown, and sample escalation IDs that you can pass to escalation_show for detail.

The tool processes at most 25,000 escalations. If more match, the response sets "truncated": true — narrow the date range for accurate results.

Cross-reference: use alert_stats(group_by: ["source"]) to see which alert sources drive the most pages, and incident_stats(group_by: ["severity", "month"]) to see how paging load correlates with incident volume. Together the three stats tools give a full picture: alerts → pages → incidents → workload.

Structured analysis: for a comprehensive report with playbooks, themes, and recommendations, call analysis_start first — it provides step-by-step methodology and a branded report template. Use this tool directly only for quick, focused queries.

List the organisation's extension connectors — the MCP servers and HTTP APIs connected through Extensions — with their capabilities and connection health.

Each entry says what the connector can be asked for (its capabilities, after runtime restrictions) and whether the connection currently works: connection_status is the latest diagnostic verdict, and reconnection_reason is set when it needs re-authentication. The tools field names the operations enabled in the connector's access policy.

Use this when reviewing an organisation's Extensions estate: what's connected, what's broken, and what a new integration would add.

Load a plugin from a source-control repository as an extension, and start its first sync.

A plugin is a skill tree — a directory holding skills/<name>/SKILL.md files, optionally with a README and reference files — that incident.io's AI agents mount and draw on during investigations and chat. Point this tool at the repository (and subpath, when the plugin isn't the repository root) and the plugin is registered with every skill enabled, then synced.

The repository must be reachable through the organisation's connected GitHub or GitLab integration; that isn't checked here. The first sync runs asynchronously and verifies it within moments — check the plugin's sync_status via extension_plugin_list, where an inaccessible repository or malformed plugin shows up as a sync_error. Renaming, disabling, skill selection, and removal are managed from the dashboard's Extensions page.

List the organisation's extension plugins with their skills and sync state.

Extension plugins are skill trees (SKILL.md files) synced from the organisation's own source-control repositories and mounted into incident.io's AI agents, so the agents follow the organisation's runbooks and conventions during investigations and chat.

Use this tool to see which plugins are installed and which skills each provides. To see how a plugin's skills are performing — and what our assessments say their authors should fix — pass a plugin's ID or name to extension_skill_feedback_list.

Request a re-sync of an extension plugin from its source repository.

Plugins otherwise sync on an hourly schedule, so use this after pushing changes to the plugin's repository to have agents pick them up now. The sync runs asynchronously: the response shows the plugin back in a pending state, and extension_plugin_list shows the outcome — last_synced_at moves on success, sync_error carries the reason on failure.

This completes the skill-improvement loop: read extension_skill_feedback_list, fix the skills in the repository, sync here, then re-read the feedback — issues whose quoted content you changed will read likely_resolved against the new version.

Update an extension plugin: enable or disable it, rename its mount, or change which of its skills agents may load.

Absent fields are left unchanged. Skill selection is set whole-state: pass skill_selection_mode "selected" together with the complete enabled_skill_dirs list (any dir not listed is disabled), or "automatic" with no dirs to let agents load every skill in the current version. Use the dir_name values from extension_plugin_list, and read extension_skill_feedback_list first when deciding — the funnel and issues say which skills earn their place.

Relocating a plugin to a different repository, and removing it, are managed from the dashboard's Extensions page.

Get the current feedback on an extension plugin's skills, so their author can improve them.

After an agent loads a plugin skill during an investigation or chat, a retrospective assessment judges how the load went once the run is scored: whether the skill was followed (the funnel), whether following it helped (the contribution), and what specifically held it back. Those observations are deduplicated into distinct issues, each anchored to the file and verbatim quote it's about, with a suggestion for the fix.

Use this when improving a plugin's skills. Work the issues most-actionable-first (they're ordered that way): an issue's target_file and target_quote locate the content to edit in the plugin's source repository, and its theme names where the fix lands — description_mismatch in the frontmatter description, instruction_gap in the skill body, broken_reference in a link, capability_gap needs conditional guidance, output_format in format sections, behaviour/scope in structure. Keep what the strengths describe. An issue whose status is likely_resolved has probably been fixed already: its quoted content is gone from the current version.

Only skills that agents have actually loaded appear, and coverage grows over time: assessment runs after a run is scored, so assessed_count lags usage_count. Feedback survives renames and removals: an entry with in_current_version false is a skill that no longer exists under that directory, kept for its history rather than for editing.

Issues the organisation has dismissed as accepted tradeoffs (via extension_skill_feedback_update) are excluded by default; set include_dismissed to see them alongside, marked dismissed with the recorded reason.

Use 'include' to request additional sections:

• examples: the most recent assessed loads per skill, each with the assessor's headline and rationale and a link to the run. Useful when a verdict needs evidence behind it; omitted by default because it's the bulk of the response. They are capped per skill and per surface, so a busy skill's examples may only span its last few hours — narrow them with example_usage and example_contribution to reach a particular verdict's loads, and use extension_skill_usage_list when you want every load over a period rather than a sample.

Dismiss a skill feedback issue the organisation won't fix, or reopen one dismissed earlier.

Use dismiss when an issue reflects an accepted tradeoff — the skill is deliberately written that way, the cost of fixing outweighs the friction, or the feedback misjudges intent — and continuing to report it would only be noise ("won't fix, stop reporting"). A dismissal is durable: later assessments observing the same issue do not revive it, so only dismiss issues that are genuinely settled rather than merely unfixed. Reopen undoes a dismissal, putting the issue back in the default feedback view.

Address the issue with the dir_name and issue_key from extension_skill_feedback_list (set include_dismissed there to find dismissed issues to reopen). Strengths cannot be dismissed — they're kept so authors don't undo what works.

List individual assessed skill loads — one row per time an agent loaded a skill and the retrospective assessment judged how it went.

Each row carries the assessor's headline and one-sentence rationale, both verdicts (whether the agent followed the skill, and whether following it helped), the incident it ran against, a link to the run, and the documents the run worked from while the skill was loaded, such as the runbook it followed. That makes this the tool for evidence about particular loads: a digest of how skills did over a period, the runs behind a verdict, the worked examples to show someone, or every time a runbook was followed.

For a skill's overall track record — its rates, its open issues, and what to fix — use extension_skill_feedback_list instead. This tool never aggregates: it lists loads, newest first.

Filters (all optional):

• plugin / skill: narrow to one plugin (ID or mount name) or one skill (dir_name)
• surface: investigation or chat
• usage: not_used, not_applicable, partial, followed
• contribution: helped, neutral, hurt, unclear
• document: only loads that worked from one document, by ID or plugin file path. Pair it with document_show and include: ["notes"] to see what those loads recorded against the document
• since / until: bound the window (yyyy-mm-dd or RFC 3339). A bare date as "until" covers the whole of that day; a timestamp is the exact instant it names
• window: which timestamp since and until bound

Only assessed loads appear. Assessment runs after a run is scored, so it lags the load — which is why window defaults to "assessed": a recurring digest that windows on when loads were assessed picks up every load exactly once, where windowing on "activated" permanently misses whatever was assessed after the last digest read it.

Pagination: use page_size (default 10, max 50) and pass "next_cursor" as "after" for the next page. Stopping before "has_more" is false means you have incomplete results.

Get a URL to upload extension content you want to check, when it isn't in a repository we can read.

Use this when there is nothing connected yet: no plugin registered and no repository we hold access to. If your content is on a branch, skip this and give extension_verify the repository and branch instead — we read that ourselves, and you upload nothing.

Two steps, because the archive never passes through this API: call this for a URL, PUT your gzipped tar to it, then call extension_verify with the same mount_name. Uploading a name again replaces what was there, so iterating costs nothing but the upload.

Tar from inside the plugin root, so members start at skills/ rather than at the directory holding it: cd <plugin-root> && tar czf tree.tar.gz $(ls -A). Tarring the parent instead prefixes every path, and the run fails saying the tree carries no skills. Build the archive before you call this: the URL is signed for ten minutes.

Nothing is registered by this. The tree is read for the run and discarded, so it never enters the catalog and no real investigation can load it.

Test proposed extension content before landing it.

Three ways to say where the tree comes from. Name a plugin to check a change against its current synced version — what is live today. Name a repository, branch and mount name to check the tree on that branch, which is how you try work you have pushed but not merged; that does not need a plugin to exist, but it is just as useful when one does, because a protected main blocks merging rather than pushing. Or, when there is nothing connected at all, upload the tree with extension_upload_url and give the mount_name you uploaded to.

Either way the change is proposed, not committed: the files you pass are overlaid for the run only, and nothing is written back to the plugin or the repository.

The changed files are overlaid on the base tree — the plugin's current synced version, or the repository at the branch you name — and a verification agent tests the result: it writes concrete expectations for what should happen, hands realistic scenarios to a fresh agent that has the patched content and no knowledge of the change, and grades the expectations against what that agent actually did. Neither the plugin nor the repository is modified.

Only a plugin needs changes, because it is the version already live and the change is what makes the run a proposal. A branch and an uploaded tree are each the subject already, so pass either on its own and the run tells you whether that content works — which is what you want after pushing a branch, with no need to upload a tree we can already read.

External calls are simulated by default, and the report lists every simulated call as a place the run is weaker than production. Set live_connectors or live_telemetry to make reads real instead — graded against what those systems actually answer, and listed separately in real_calls. Writes are never made, whatever you set: the content under test has not shipped, so a scenario that would change a connected system is refused and the agent is told to assume it succeeded.

Anchor the run one of two ways: a reference to a recorded situation (a chatbot thread or investigation where things went wrong, or a skill feedback issue from extension_skill_feedback_list — the change is verified against the recorded problem), or a prose description of what to test (a new skill, a hypothetical you're protecting against). The run takes a few minutes; the response carries the verification ID to poll with extension_verify_show.

Show a plugin verification's status and result.

Poll this after extension_verify: a run typically takes a few minutes, and while it runs the response reports how long it has been going and how far it has got. Once status is complete, the result carries the overall verdict, each tested expectation with its evidence, the external calls the run simulated rather than made (each a place the verification is weaker than a real run), and suggested edits for anything that failed — apply those locally and verify again.

List the third-party services whose status pages we monitor.

Use it to turn a vendor into a name external_service_status accepts, and to tell "we don't monitor that vendor" apart from "that vendor is fine".

Every organisation sees the same services: we monitor them centrally, and an organisation cannot add to the set or remove from it. Names are the vendor's own ("Amazon Web Services", "Google Cloud Platform"): neither "AWS" nor "Bedrock" appears in one. A query matching nothing is refused with the closest names rather than an empty list.

Returns at most 25 services, sorted by name, with the number that matched. There is no pagination: a query narrows the list instead.

Read the state of third-party services we monitor, and the state changes inside a window.

A state here is a claim, and the result says whose. state_confirmed_by carries the source of the current state, reported_by the source of each change:

• "vendor" — the vendor published this on their status page. It is their announcement, in their words.
• "our_monitoring" — we inferred this ourselves and the vendor has published nothing. It is our suspicion, unconfirmed by them, and their status page does not show it. The service is not "in" this state as far as anyone outside us is concerned.

Use it whenever a vendor comes up in an incident: an upstream outage is the cheapest explanation to rule in or out, and the state changes tell you whether the timing lines up with your incident.

Takes ids or exact names from external_service_list, so resolve the vendor before calling: a product name belongs to its vendor ("Bedrock" and "S3" are both "Amazon Web Services"), and an abbreviation is not the name we hold ("GCP" is "Google Cloud Platform"). A name we do not monitor comes back under unknown.

This reads other companies' status pages, which we monitor centrally. It is not status_page_update, which publishes to the organisation's own status page.

Submit feedback about the incident.io MCP tools to help us improve them.

After completing a task using the MCP tools, reflect on whether the experience could have been better. Consider:

• Was there data you needed but couldn't get, or had to piece together from multiple calls?
• Did a tool return too much or too little information for your use case?
• Was there a question you couldn't answer without paginating through many results?
• Did you have to work around a limitation (e.g. manually counting, converting units, cross-referencing IDs)?
• Would a different grouping dimension, filter, or sort option have saved significant effort?

Examples of valuable feedback:

• "I wanted to find the top 5 noisiest alert sources but had to call alert_stats then manually rank by workload — a built-in ranking would help"
• "incident_show doesn't include the Slack channel name, only the URL — I needed the name to cross-reference with another system"
• "I couldn't filter escalation_stats by the user who was paged — I wanted to show a specific person's paging load"
• "The workload data was in minutes but I always convert to hours — returning both would save a step"

IMPORTANT: Always ask the user for permission before submitting feedback. Draft your feedback, present it to the user, and only call this tool after they approve. The user may want to refine, add context, or decline to send.

The feedback goes directly to the team building these tools and is stored for analysis. Even small friction points are valuable.

Create a follow-up on an incident, either from scratch or by importing an existing external ticket.

Follow-ups are post-incident tasks — work that needs to happen after an incident is resolved, like "add monitoring for X", "update runbook", or "fix the root cause". They are distinct from in-flight actions which are checklist items used during active response. Follow-ups persist, can be assigned, prioritised, labelled, and exported to external issue trackers.

There are two modes:

1. Create from scratch: provide incident_id and title (required), plus optional description, assignee_id, assignee_team, priority_id, labels. The follow-up is created with status "outstanding".

2. Import from external ticket: provide incident_id and url (a link to an existing Linear, Jira, GitHub, GitLab, Asana, ClickUp, or Shortcut issue). The title, description, status, and assignee are imported from the ticket automatically. The follow-up is linked to the external issue for ongoing sync.

Instead of creating directly, action "suggest" posts a draft for a human to accept, edit, or decline, and action "edit_suggestion" (with suggestion_id) revises a draft. To apply a draft that was already reviewed, use action "execute" with only suggestion_id — it is applied verbatim. Prefer "suggest" when the user asked for a draft or you are unsure. In a chat conversation the draft appears as a card; elsewhere it has no card — show it to the user, and find it later with suggestion_list. A url import cannot be drafted.

If the org requires a priority or assignee, those fields become required and the tool will return a validation error if they're missing. A draft is looser: a missing required assignee is filled for you (the incident lead, else the caller), and a required priority is enforced when a person accepts.

A user and a team can own a follow-up at the same time. Omit assignee_team and the incident's own team is used where the organisation requires one; pass an empty string for no team. Where the organisation demands a team and none can be inferred, the call is refused rather than creating one it considers invalid.

assignee_id, assignee_team and priority_id each take an ID or a name. A name matching more than one user, team or priority is rejected rather than guessed.

List follow-ups with optional filters and pagination.

Follow-ups are post-incident tasks that track work needed after an incident is resolved — things like "add monitoring for X", "update runbook", or "fix the root cause". They are distinct from in-flight actions (checklist items used during active response). Follow-ups can have priorities, assignees, labels, and can be exported to external issue trackers like Jira or Linear.

Each result includes: title, status, priority, assignee (user), assignee team, creator, labels, linked external issue, and timestamps.

Filters (all optional):

• incident_id: filter to a specific incident (accepts ID, external ID, or reference like INC-123)
• assignee_id: filter by assignee user ID (use your own ID from config://organisation to find "my follow-ups")
• assignee_team_id: filter to a team (a catalog entry ID from team_list). Matches follow-ups assigned to the team, plus follow-ups assigned to a direct member of that team when no team is set — mirroring what the team page shows. An explicit team assignment always wins.
• status: one or more of outstanding, completed, not_doing
• created_after / created_before: date range for when the follow-up was created (yyyy-mm-dd or RFC 3339). Useful for scoping to recent follow-ups rather than returning historical items.

Pagination: results are ordered oldest first. Use page_size (default 10, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

For aggregate counts and breakdowns (e.g. "how many outstanding follow-ups by priority?"), use follow_up_stats instead of paginating through this list.

For post-incident review workflows, combine with incident_show to understand the incident context behind each follow-up. Use follow_up_create to add new follow-ups discovered during analysis.

Count follow-ups grouped by one or more dimensions, returning aggregate statistics.

Use this tool when you need counts or breakdowns across many follow-ups — for example "how many outstanding follow-ups by priority?" or "follow-up completion rate by incident severity". Use follow_up_list to browse individual follow-ups.

Dimensions (combine freely in the group_by array):

• status: group by follow-up status (outstanding, completed, not_doing)
• priority: group by follow-up priority (e.g. P0, P1, P2). Shows "No priority" for unset.
• assignee: group by assigned user. Shows "Unassigned" for follow-ups without an assignee.
• has_external_issue: group by whether the follow-up has been exported to an external tracker like Jira or Linear (true/false)
• incident_severity: group by the severity of the parent incident (e.g. Critical, Major, Minor). Useful for answering "are we completing follow-ups from our most critical incidents?"
• week: group by ISO week (e.g. 2026-W03)
• month: group by calendar month (e.g. 2026-01)
• quarter: group by calendar quarter (e.g. 2026-Q1)

Each group includes a count, sample incident references (e.g. INC-123) for drill-down, an age summary for outstanding items showing how long they've been open, and a completion-time summary (mean and max days from creation to completion) covering the group's completed follow-ups. Completion time is measured for follow-ups created within the queried window; narrowing by created_after/created_before therefore answers "how long did the follow-ups created in this period take to close".

By default, deleted and archived follow-ups are excluded.

The tool processes at most 25,000 follow-ups. If more match, the response sets "truncated": true — narrow the date range for accurate results.

Drill-down: each group includes incident references. Pass these to follow_up_list(incident_id: "INC-123") to see the individual follow-ups, or to incident_show for incident context.

Cross-reference: use incident_stats to understand the incidents that generated these follow-ups, and follow_up_list to browse and update individual items.

Structured analysis: for a comprehensive report with playbooks and recommendations, call analysis_start first.

Update an existing follow-up. Only the fields you provide will be changed — omitted fields are left as-is.

Use follow_up_list to find follow-up IDs. Use follow_up_create to add new follow-ups.

Updatable fields:

• title: rename the follow-up
• description: set or clear the description (empty string clears)
• assignee_id: assign to a user by ID or name (empty string unassigns the user)
• assignee_team: set the owning team by catalog entry ID or name (empty string unassigns the team)
• priority_id: set priority by ID or name (empty string clears, see config://organisation for IDs)
• status: change to outstanding, completed, or not_doing
• labels: replace all labels (omit to leave unchanged)

A user and a team can own a follow-up at the same time: assignee_id and assignee_team are independent, and setting one never clears the other. A name matching more than one user, team or priority is rejected rather than guessed.

Deleting a follow-up is not possible here, so "deleted" is not an accepted status. Follow-ups can currently only be deleted on other surfaces like Slack and the dashboard.

If the follow-up has been exported to an external issue tracker (Jira, Linear, etc.), the fields that sync from the external system cannot be changed here and the tool says which they are. The owning team can always be changed; the priority can too, unless the organisation syncs priorities from the tracker.

Returns the updated follow-up.

Create a glossary entry: a coined term (acronym, service name, or internal jargon) and what it means.

Use this when the organisation uses a term that is not already in the glossary and someone with organisation settings permission wants it defined so Scribe and other AI features transcribe and summarise it correctly. Look the term up with glossary_list first — a live entry with the same item (case-insensitive) is rejected.

Pass after with an entry ID from glossary_list to insert the new entry immediately after it. Omit after to append the new entry to the end. Anyone can read it with glossary_list; creating it requires organisation_settings.update.

Returns the created entry.

Delete a glossary entry so it no longer appears in glossary_list.

Use this when a coined term is wrong or no longer used. Deleting frees the item: the same term can be added again later with glossary_create. It cannot be undone through these tools. Find the ID with glossary_list.

Requires organisation_settings.update.

Returns the deleted entry.

List and search this organisation's glossary: coined terms (acronyms, service names, internal jargon) and what they mean.

Consult the glossary before treating an unfamiliar acronym, service name, or piece of jargon as unknown, and before inventing an expansion. Scribe and other AI features use these definitions so they transcribe and summarise the organisation's language correctly. If the user mentions a term that might be internal, look it up here first.

Anyone in the organisation can read the glossary. To add or change terms, use glossary_create, glossary_update, or glossary_delete (those need organisation settings permission).

Filters (all optional):

• item: exact match on the coined term (case-insensitive). Prefer this when you already have the item.
• query: relevance-ranked search over item and description, matching whole words and partial terms. Prefer this when searching for a meaning or a partial name.

Pagination: entries are ordered by rank, or by relevance when query is set. Use page_size (default 25, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. A query or item that matches nothing is refused with the closest coined items rather than an empty list.

Update a live glossary entry's item and description.

Use this to correct a definition or rename a coined term. Both item and description are required — pass the current item unchanged if you are only editing the description. Find the ID with glossary_list. An archived entry cannot be updated: create a new one with glossary_create instead.

Requires organisation_settings.update. A live entry that already holds the same item (case-insensitive) is rejected.

Returns the updated entry.

Ask how incident.io works and get an answer written from incident.io's own product documentation.

Use it for questions about the product itself: "how do escalation paths work?", "what does incident.io integrate with for follow-ups?", "how do I set up an alert route?", "what's the difference between streams and incidents?". Reach for it before guessing at product behaviour, and before telling a user something isn't possible.

This is not document_search. document_search searches the organisation's own synced documents — their runbooks, guides and post-mortems from GitHub, Notion or Confluence. This tool searches incident.io's documentation of the product, which every organisation shares and none can add to. A question about how a feature behaves belongs here; a question about how this organisation responds to an outage belongs in document_search.

It answers from documentation only and can see nothing about the organisation — no incidents, schedules or configuration. For "who is on call right now?" or "which alert routes do we have?", use the tools that read live data.

Returns a written answer, not a list of matching documents: there are no per-document ids to read further, so ask a fuller question than you would give a search box. A model writes the answer, so a call takes a few seconds.

Pass session_id from a previous response to ask a follow-up with the earlier turns in context.

Create a new incident.

Use this tool when you know what incident to create (e.g. from an alert, a customer report, or a detected issue).

Before creating from an alert or a report, check for an existing open (triage, active or paused) incident for the same problem so you attach to it or merge rather than declaring a duplicate.

Required: name (a short, descriptive title).

A retry of the same request returns the incident it already created, with already_existed set — say it was already declared rather than claiming you declared it.

Rate limited: an organisation can only create a limited number of incidents per hour. A call over the limit is rejected — don't retry in a loop.

The incident is created in triage by default — this means no severity is required and the team can assess before accepting. To create an already-accepted incident, provide both severity_id and an active incident_status_id.

Never invent a severity. Only pass severity_id if the user has explicitly stated one (e.g. "create a sev2", "this is critical"). If they haven't, leave severity_id empty so the incident starts in triage and a responder can set it later.

Some organisations have disabled manual triage incidents — those require severity_id at creation time. The organisation's declare form may also require custom fields on every incident, including triage.

A call missing any required field creates nothing.

If the tool can deliver the form to the person itself, the call succeeds and says what was missing — tell them the form is waiting for them and stop; don't repeat the field list or claim you declared anything.

Otherwise it returns a "missing_required_fields" validation error. Its first entry summarises what is missing. After it comes one "missing_required_field" entry per field, each pointing at the field it means: severity_id for severity, custom_field_entries/<custom_field_id> for a custom field. Read those pointers to tell the fields apart.

You may be given a URL to a form that the user can fill in the missing fields which you should share with them to complete if you cannot gather the fields yourself. If they tell you what all of the missing fields should be you can retry calling the tool with those new fields.

Defaults applied when fields are omitted:

• visibility: public
• incident_type_id: the organisation's default incident type
• incident_status_id: triage (only if the organisation allows manual triage incidents)
• severity_id: none (allowed in triage; required if status is active or if the org has disabled manual triage)
• slack_team_id: only meaningful on Slack Enterprise Grid with multiple workspaces — defaults to the workspace the authenticated user is a member of (when unambiguous), otherwise the organisation's primary workspace

Read the config://organisation resource to discover severity IDs, status IDs, incident type IDs, custom field IDs, and role IDs.

Returns the created incident summary.

Search and list incidents, returning a summary per result. Use incident_show to get full details for a specific incident.

Each result includes: reference (e.g. INC-123), name, status (with category), severity, mode, reported_at, updated_at, and a permalink. A merged incident (status category "merged") also includes "merged_into", identifying the incident it was merged into.

Use the include parameter to enrich results with additional fields, avoiding the need to call incident_show for each incident:

• summary: short incident summary (~200 chars, AI-generated or human-written) — useful for understanding what each incident was about without fetching full details
• roles: include role assignments (e.g. incident lead) with user names and IDs
• custom_fields: include custom field values
• timestamps: named timestamps (e.g. reported at, resolved at) — useful for timeline and trend analysis
• durations: duration metrics (e.g. time to resolve, in seconds) — useful for comparing incident response times
• escalation_urgency: include AI assessment of whether each incident needed immediate response (urgency level and tags). Only available for orgs with AI investigations enabled. Use incident_show for the full reasoning text.

This is especially useful for analytical queries like "who has been incident lead the most?" — include roles and paginate through the results rather than calling incident_show for each one. For trend analysis, include summary, timestamps, and durations to get context without extra API calls.

By default only standard and retrospective incidents are returned, and declined/canceled/merged incidents are excluded, except when searching by query, which returns every status category. Provide explicit filters to override these defaults.

Filters (all optional):

• query: free-text search across incident names
• status_category: one or more of triage, active, post-incident, closed, paused, declined, merged, canceled
• severity: one or more severity IDs
• incident_type: one or more incident type IDs (e.g. filter to "Default" only, or exclude "Internal" and "Maintenance")
• mode: one or more of standard, retrospective, test, tutorial. standard is a real, live incident; retrospective records something that already happened for the postmortem/timeline without a live response; test and tutorial are practice incidents (a test run, or the onboarding walkthrough) and are excluded by default
• team: one or more team IDs (exact match — incidents tagged with any of these teams)
• team_part_of: one or more team IDs including all sub-teams in the hierarchy (e.g. "Platform" returns incidents for Platform and all its child teams). Mutually exclusive with team.
• custom_fields: filter by custom field values (object mapping field ID to array of value IDs)
• created_after / created_before: dates to bound the time range (yyyy-mm-dd or RFC 3339)
• assigned_to: one or more user IDs (or the literal "me" for the calling user). Returns incidents where any listed user is a participant (responder/collaborator/observer) or has any incident role assignment (e.g. lead). Use this to triage your own workload without wading through everyone else's, e.g. {"assigned_to": ["me"], "status_category": ["triage", "active"]}. "me" only works for OAuth tokens, not API keys.

To discover severity IDs, incident type IDs, custom field IDs, and custom field value IDs, read the config://organisation resource first.

Sorting: results are ordered newest first by default. Set sort_by to "workload" to order by total responder-minutes (highest first), which is useful for finding the most costly incidents. Workload data is synced hourly from our insights pipeline.

Pagination: use page_size to control the page (default 10, max 50). When the response has "has_more": true, pass the "next_cursor" value as "after" to fetch the next page. Stopping before "has_more" is false means you have incomplete results.

Tip: if you need counts or trend data, use incident_stats first — it's much more efficient than paginating through incident_list and counting manually. Use incident_list when you need to browse individual records or need the detail that includes provide.

Merge incidents that turn out to be the same problem into one.

The incidents in incident_ids are the sources: each moves to the merged status and stops being responded to separately. merged_into_incident_id is the target, which survives and carries the response on. Merging several sources into one target is a single call — don't loop.

A source may be in any lifecycle status except merged or canceled. The target may also have any status except merged or canceled. If it has been merged into something else, merge into the incident at the end of that chain instead. Streams cannot be merged, on either side.

Sources that cannot be merged are skipped and the rest still apply. The outcome names the sources that merged and the ones that did not. A refusal of the target, or a call where nothing could be merged, is an error. Each merge is its own transaction, so a later failure does not undo the sources that already merged. Call again with the same list to see where it got to: an incident that already merged is skipped by name.

Merging is visible to responders: each source's channel is archived after a delay, its alerts and attachments move onto the target, and its subscribers are notified.

Read the result with incident_show. To reverse a merge, use incident_unmerge on the source that was merged away.

Share a finding, insight, or piece of analysis into an incident's chat channel, so the responders can see it.

Posts a quoted message attributed to you, with an optional threaded reply for longer detail. Use it to forward something you have worked out — "post that to the channel", "let the responders know".

This is not the tool for updating the incident. Three nearby things go elsewhere:

• Communicating a change to status, severity, summary or custom fields, or a progress note on the incident timeline, is incident_update (its message field).
• Correcting an in-progress investigation's hypothesis is investigation_steer.
• Answering the user in this conversation needs no tool at all.

Distil the key finding into a concise message rather than dumping the whole conversation. The main message is quoted in the channel, so keep it to the takeaway and put supporting detail in thread_message.

The attribution line names you from your credentials — it cannot be set by the caller. An incident with no chat channel has nowhere to post, and is refused.

Look up an incident by ID or reference (e.g. INC-123, 123, or a full ID) and return its details.

Returns: name, status, severity, roles, participants, custom fields, timestamps, durations, workload (responder time split by working/late/overnight hours), summaries, channel URLs, and the 5 most recent status updates. For a merged incident, "merged_into" identifies the incident it was merged into.

Use 'include' to request additional sections:

• investigation: AI investigation findings and extended summary. Always request this when investigating root causes or triaging — it contains the analysis our AI has already performed.
• postmortem: the post-mortem document content. Request this when reviewing what happened or preparing reports — it contains the team's written analysis.
• updates: all status updates (default returns most recent 5 only). Request this when you need the full timeline of how the incident progressed.
• escalation_urgency: AI assessment of whether the incident truly needed immediate response (immediate, deferrable, or unsure) with classification tags and reasoning. Useful for on-call burden analysis and alert noise reviews. Only available for orgs with AI investigations enabled.
• call_notes: AI-generated notes from calls, returned as two separate lists. "call_notes" covers calls held during the incident — what responders said while working it. "meeting_notes" covers follow-up meetings held afterwards, such as debriefs and post-mortem reviews. Request this when you want what people actually discussed rather than what was written down. Notes are only returned for the 5 most recent calls; raw transcripts are not available through this API.

For investigation or root cause analysis, request include: ["investigation", "postmortem"] — the default response without these only gives you the basic metadata, not the deeper analysis.

For the full investigation content (all findings, checks, conversation history, and incident context as a file tree), use the investigation_sync tool instead — it returns a downloadable tar.gz archive of the complete investigation filesystem.

Count incidents grouped by one or more dimensions, returning aggregate statistics.

Use this tool when you need counts, breakdowns, or trend data across many incidents — for example "how many P1s this quarter?" or "incident volume by team by month". Use incident_list when you need to browse or search individual incidents, and incident_show to get full details for a specific incident.

Dimensions (combine freely in the group_by array):

• severity: group by severity level (e.g. Critical, Major, Minor)
• status: group by status category (e.g. triage, active, closed)
• type: group by incident type
• mode: group by mode. standard is a live incident, retrospective records a past one for its postmortem/timeline, and test/tutorial are practice incidents (excluded by default)
• alert_source: group by the alert source that triggered the incident (e.g. Datadog, Sentry). Shows "No alert" for manually created incidents. Multi-value: incidents with alerts from multiple sources are counted under each source individually.
• escalation_urgency: group by AI-assessed urgency (immediate, deferrable, unsure, or "Not assessed" for incidents without analysis). Useful for quantifying alert noise and on-call burden — combine with month for trend analysis.
• team: group by the org's configured team (e.g. Engineering, Platform). Prefer this over grouping by a team-shaped custom field (custom_field:<id>) — "team" resolves the org's configured team field, so its counts agree with filtering by team. Multi-value: incidents tagged with several teams are counted under each; incidents with no team show as "None". Combine with month/severity for per-team trends and workload.
• custom_field:<field_id>: group by a custom field's values (read config://organisation to find field IDs). Multi-value: multi-select fields are flattened so each value is counted individually.
• role:<role_id>: group by who is assigned a specific role (e.g. Incident Lead). Shows user names, or "Unassigned" for incidents without that role.
• week: group by ISO week (e.g. 2026-W03)
• month: group by calendar month (e.g. 2026-01)
• quarter: group by calendar quarter (e.g. 2026-Q1)

Each group includes a count, a workload breakdown (total responder-minutes split by working hours, late evening, and overnight), and the most recent incident references (e.g. INC-123) which you can pass directly to incident_show to drill into. Workload data is synced hourly from our insights pipeline and may be absent for very recent incidents.

By default, test and tutorial incidents are excluded and declined/canceled/merged incidents are excluded. Provide explicit status_category or mode filters to override these defaults.

The tool processes at most 25,000 incidents. If more match, the response sets "truncated": true — narrow the date range for accurate results.

Drill-down: each group includes incident references (e.g. INC-123). Pass these to incident_show with include: ["investigation", "postmortem"] to understand root causes behind the numbers.

Cross-reference: compare with alert_stats(group_by: ["source"]) to see how alert volume and noise translate to the incident workload shown here.

Structured analysis: for a comprehensive report with playbooks, themes, and recommendations, call analysis_start first — it provides step-by-step methodology and a branded report template. Use this tool directly only for quick, focused queries.

Reverse a merge, restoring an incident as a standalone incident.

It operates on the incident that was merged away — the source. You don't say what it was merged into: that is derived from the incident's own history. The incident is restored to the status it held before the merge, falling back to triage if it was merged straight out of triage.

Only an incident currently in a merged status can be unmerged. Anything else — active, closed, declined, never merged at all — is refused rather than changed.

Unmerging is visible to responders: the incident's channel is un-archived if the merge was recent enough, the attachments copied onto the merge target are detached again, and subscribers are notified of the status change.

Read the incident with incident_show afterwards to see which status it was restored to. To merge incidents in the first place, use incident_merge.

Update an incident: post a status update message, rename it, change its summary, severity or status (including pausing it), set custom fields, assign roles, or set incident timestamps. Only the fields you provide change — omitted fields are left as-is.

Set everything the user asked for in a SINGLE call: accepting an incident, setting its summary, posting a message and pausing it all go in one call.

Choose an action:

• action "execute" (the default) applies the change directly. Use it when the user asks you to make a change or post an update, or gives the exact content. To apply a draft that was already reviewed, pass only suggestion_id — execute it verbatim, without adding fields the user didn't approve.
• action "suggest" drafts the change for a human to accept, edit or decline. Use it when the user wants an update written or drafted rather than posted, wants your opinion on a name, or is vague ("update pls") — don't ask for clarification, just draft sensible fields. In a chat conversation the draft appears as a card; elsewhere it has no card, so show it to the user yourself and find it later with suggestion_list.
• action "edit_suggestion" revises a draft. Pass suggestion_id and the fields to change.

An "execute" that can't be applied yet changes nothing, and comes back one of two ways. Usually a draft is made for you — accepting a triage incident with no severity or incident type, or resolving and closing, which send the user through the required-fields form — and "suggestion" carries it: relay it, don't retry. Otherwise the result names required fields that are unset and asks you to draft it, and there is no "suggestion": call again once with action "suggest", filling those fields from context rather than asking the user for them.

This tool posts a real, user-visible update and is NOT idempotent, so read "incident" on the result to tell what happened. Once it is set the change is applied: never call the tool again for that request — if part of the change didn't land, tell the user. A result without it applied nothing and doesn't count against that, whether it was rejected, drafted, or asked you to draft: act on what it says and call again at most once.

Status transitions follow the incident lifecycle:

• From triage you can accept (move to an active status), pause, decline, resolve or close (the last two decline it). Declining is only possible from triage.
• From active you can pause, resolve, close, cancel, or move to another active status. You can't move an active incident back to triage.
• Pausing a triage incident works in one call — it's accepted first automatically. Don't split it into two steps.
• A closed incident can be reopened by moving it to an active status. You can't reopen a merged or cancelled incident. A declined incident must be reopened (moved back to triage or to an active status) before any other change.

Accepting an incident requires an incident type. Incidents declared from alerts often have none, so pass incident_type_id alongside incident_status in the same call — it can only be set while still in triage.

Resolving may require custom fields: some organisations require certain fields before an incident can be resolved. Set them with custom_fields in the same call — otherwise nothing is applied and the result names the fields for you to draft with.

This tool cannot merge incidents (use incident_merge), update a status page (use status_page_update), or update an action or follow-up. To have the change decided for you rather than specified, use ask with incident_id.

Roles, severities, statuses and timestamps accept their names; read config://organisation only for the IDs you cannot see (incident types, custom fields).

List status updates for an incident, most recent first.

Each update shows the message, any status or severity change, and when it was posted. The update that merged the incident also includes "merged_into", the incident it was merged into. The incident_show tool returns the 5 most recent updates by default — use this tool when you need the full history.

Pagination: use page_size (default 10, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Link to a chart of the organisation's incident.io data in Insights explore. Use this when the user asks for a chart, graph or visual of incidents, alerts, pages, follow-ups, post-incident work or on-call readiness over a period. It returns a URL, not an image or values: the chart draws when the user opens it.

Call insights_chart_options first. Use preset_key whenever a preset fits the request, and chart only for a combination that is not already a preset.

A period counted back from today, e.g. the last 12 weeks, stays relative, so the chart moves on when the user opens it later. Set start_date and end_date for fixed dates.

Link the result's url in your reply, and say what the chart shows from its summary. Don't quote numbers: this tool reads none.

List the charts this organisation can draw, for a dashboard or a single chart: ready-made presets, the measures a custom chart can plot, the filters each measure takes, and the ids of the organisation's duration metrics, custom fields, teams, alert attributes and post-incident flows.

Call it before you build a chart or a dashboard, and prefer a preset when one matches the request. When a preset is close, pass its chart, filters included, with the changes the user asked for, e.g. a different series or presentation. A preset listed without a chart has filters the agent can't set, so draw it only by its key. Tiles are for custom_dashboard_create only.

Add a chart or a trend or KPI tile to one of the organisation's Insights dashboards. Only call this when the user explicitly asks to add or save a chart to a dashboard: drawing a chart doesn't need it.

Find the dashboard with insights_dashboard_list. When it isn't clear which dashboard the user means, ask them rather than pick one.

Without a placement the chart goes in a full-width row at the bottom of the dashboard. When the user says where it goes, read the layout with insights_dashboard_show and set placement from its numbers. Match a section by its title or its number, and a row by its number or by a panel it holds. "Next to" or "in the same row as" a panel is in_row on that panel's row, which fills the row's empty space if it has some, and otherwise splits the row evenly unless the user gave a size. "Under" or "above" a section is a new section next to it, and "under" or "above" a chart is a new row next to that chart's row. When it isn't clear where the user means, ask them.

When the chart's own filters clash with those of the section or dashboard it joins, nothing is added and the result lists filter_conflicts. Explain each one to the user in plain words, offer to keep the chart's filters, use the inherited ones, or put the chart somewhere else, and wait for their answer. Never choose for them: only set on_filter_conflict to what they chose.

Call insights_chart_options first. Use preset_key whenever a preset or tile fits the request, and chart only for a combination that is not already a preset. There are no period fields: the chart covers the dashboard's own date range, so say so in your reply.

List the organisation's custom Insights dashboards that insights_dashboard_add_chart can add a chart to, by name. Call it to find the dashboard the user means before adding a chart to it.

Remove one panel (a chart, trend or KPI tile, text or divider) from one of the organisation's custom Insights dashboards, as "Delete panel" does in the editor. Its space is left empty, a row left with nothing else goes, and so does a section left with nothing else and no title, description or filters.

Only call this when the user explicitly asks to remove or delete a panel. Find the dashboard with insights_dashboard_list and the panel with insights_dashboard_show. Match the panel the user names by its title or position, and ask them when it isn't clear which one they mean.

Never remove a panel to make space or to replace a chart: to change a chart, use insights_dashboard_update_chart.

When the result says a row or section went with the panel, tell the user. Link the result's url in your reply.

Show a custom Insights dashboard's layout: its numbered sections with their titles and filters, each section's numbered rows, and each row's columns with their widths and panels. Call it before insights_dashboard_add_chart whenever the user says where the chart goes, e.g. "in section 2", "under the Response section", "next to the MTTR chart" or "in row 3", and use its numbers for the placement.

Change a chart, trend tile, KPI tile or text panel already on one of the organisation's custom Insights dashboards. The panel keeps its place and size.

• A chart: its title, description, colours, background, or chart settings such as what it measures, how it's drawn (e.g. line or stacked bar), how it's grouped and split, its statistics and its filters.
• A trend tile: the field, metric, team grouping or flow its theme breaks down by, its filters and its background. Its theme can't change: for other trends, add a new tile.
• A KPI tile: its metric and its background.
• A text panel: its text, in Markdown, and its background.

Find the dashboard with insights_dashboard_list, then the panel with insights_dashboard_show, which gives each panel's id and current settings. Match the panel the user names by its title, its text or its position, and ask them when it isn't clear which one they mean. To change a chart's or a trend tile's settings, send chart or trend as insights_dashboard_show gives it with only what the user asked for changed, and check insights_chart_options for the values they accept. Leave out the settings the user didn't ask to change.

When the new filters clash with those of the panel's section or dashboard, nothing is changed and the result lists filter_conflicts. Explain each one to the user, offer to keep the panel's filters or use the inherited ones, and wait for their answer. Never choose for them: only set on_filter_conflict to what they chose.

Link the result's url in your reply.

Set the title or description of a section on one of the organisation's custom Insights dashboards. Its charts, rows and filters stay as they are.

Find the dashboard with insights_dashboard_list and the section's number with insights_dashboard_show. Match the section the user names by its title or number, and ask them when it isn't clear which one they mean. Only set the fields the user asked to change.

Record a user's overall feedback on an AI investigation — whether it was helpful in responding to the incident. Feedback can only be submitted once the incident reaches a terminal state (resolved, declined, or merged).

Provide either incident_id (ID, external ID, or reference like INC-123) or investigation_id. When using incident_id, the most recent completed investigation for that incident is selected.

Set sentiment to "helpful", "not_helpful", or "not_seen" (the user didn't use the investigation). Optionally include reasons matching the sentiment, plus a freeform comment (a comment can accompany any sentiment). Valid reasons per sentiment:

• helpful: root_cause_correct, pointed_right_direction, gathered_context, caught_something_missed, confirmed_thinking, helped_prepare_fix
• not_helpful: not_accurate, too_late, too_frequent, missing_information, didnt_do_what_asked, already_knew
• not_seen: already_knew, too_late, too_frequent, work_elsewhere

IMPORTANT: This submits feedback on the user's behalf. Always confirm the sentiment (and any reasons/comment) with the user before calling this tool — don't infer their verdict and submit it unprompted.

Start an AI SRE investigation for an incident.

An investigation runs automated checks in the background to gather context about the incident — telemetry, recent code changes, similar past incidents — and builds a hypothesis from what it finds. Use this when you want investigation artifacts or telemetry for an incident and nothing is investigating it yet.

Pass incident_id as an ID, external ID, or reference like INC-123, exactly as investigation_steer accepts it.

Starting an investigation is visible to responders, and neither effect comes back in this result: a summary message is posted and pinned into the incident's chat channel, and the user whose credentials made the call is invited into that channel. Credentials with no user attached — an API key — start an investigation attributed to nobody, and invite nobody.

If an investigation is already running for the incident this returns started: false with that investigation's ID rather than starting a second one. Use investigation_steer to redirect its focus, or investigation_sync to download its findings.

Investigations are asynchronous: this call returns as soon as the investigation is queued, and findings appear over the following minutes.

Feed information into an in-progress investigation so it re-assesses its hypothesis.

Use this when you know something the investigation doesn't — for example, the responder has identified the real cause, telemetry shows a different explanation, or the investigation is going down the wrong path.

Provide either incident_id (ID, external ID, or reference like INC-123) or investigation_id. When using incident_id, the latest investigation is selected.

The directive should explain what the investigation should focus on and why its current hypothesis may be wrong. Good directives reference the current hypothesis and explain the correction:

• "The investigation is focused on Postgres connection pooling, but Redis connections are exhausted (100% since 14:32) — focus on Redis instead"
• "The error started immediately after the 14:30 deploy of payment-service v2.3.1 — the investigation should look at that deploy"
• "Ignore the Sentry errors — they're a known false positive from last week, not related to this incident"

Include evidence (telemetry results, log excerpts, etc.) and telemetry_query_ids when available — the investigation unpacks query IDs into rich artifacts with query expressions, datasource details, and explore URLs.

After steering, the investigation re-assesses its hypothesis within a few minutes (checks are debounced to coalesce rapid updates).

Download an investigation as a tar.gz archive containing the full investigation filesystem.

Provide either incident_id (ID, external ID, or reference like INC-123) or investigation_id. When using incident_id, the latest investigation is selected.

The archive contains markdown files describing the investigation: findings, checks, incident context, conversation history, and more.

Optionally pass since (a timestamp) to include a preamble showing what changed since that time — useful for polling an in-progress investigation.

Returns a signed URL valid for 15 minutes.

Count the alerts a maintenance window held.

Returns how many alerts the window held, how many of those are still firing versus resolved, and when it last held one. Use it to measure what a window suppressed.

stats is omitted when the window has held nothing yet. Take the window ID from maintenance_window_list.

Schedule a maintenance window: a period where matching alerts are held back instead of paging anyone.

This stops real pages for real people. Say what will be held and for how long, and get agreement, before calling it.

Which alerts: alert_source_ids says which sources the window holds. Resolve names to IDs with alert_source_list first. At least one is required — a window cannot hold every alert in the organisation, so a request to mute everything needs the sources naming.

Times must be UTC RFC 3339 ending in Z. Never convert a wall-clock time to UTC by writing an offset yourself: daylight saving shifts offsets and the window lands on the wrong hours.

Filters beyond alert source, escalation overrides, notification channels and start or end reminders are dashboard-only. Say so rather than approximating them.

Returns the created window, whose ID maintenance_window_update and maintenance_window_delete take.

Cancel a maintenance window that has not started.

Only an upcoming window can be cancelled. To stop a window that is already running, use maintenance_window_update with end_now.

Take the window ID from maintenance_window_list.

List maintenance windows by status.

A maintenance window holds alerts matching a filter for a fixed period, instead of routing them to whoever is on call.

Returns each window's ID, name, status, lead, time range, linked incident and how many alert filter condition groups it carries. The ID is what maintenance_window_update, maintenance_window_delete and maintenance_window_alerts take.

status defaults to active. Pass "upcoming" for windows that start later, "past" for ended ones. Ordered by start time, most recent first, and capped at 10: has_more reports windows beyond the cap.

Change a maintenance window's name, lead or times, or end an active one now.

Pass only the fields to change; the rest keep their values. Take the window ID from maintenance_window_list.

Set end_now to stop an active window immediately, which is how you unmute alerts early. To cancel a window that has not started, use maintenance_window_delete.

Refusals: a window that has ended cannot be changed; an active window's start time cannot move; no time can move into the past; the end cannot precede the start; end_now works only on an active window.

Show the health of the AI data sources the organisation has connected — the same view the dashboard's health page computes.

Each data source (telemetry, code, documents, catalog, past incidents, messages) gets a setup status (healthy, setting_up, or not_connected) and usage counts: how many distinct chats and investigations drew on it over the reported window. The telemetry and code sources break down further into per-datasource children — telemetry children carry query outcome stats (total, with data, failed, empty, cited) and attention_reasons naming what needs a human (needs_reconnection, low_success_rate, always_empty, no_active_memories, stale_guidance).

Use this when assessing whether the organisation's AI setup is working: which sources are connected but unused, which telemetry datasources are failing or never return data, and where usage concentrates. For the telemetry datasource inventory (capabilities and connection status, including disabled sources), read telemetry://datasources; for MCP and HTTP connectors, use extension_connector_list.

Health is only computed for organisations that can use investigations; otherwise data_sources is empty and message says why.

Pause someone's on-call notifications for a window: while the pause is active, escalations skip them instead of paging them.

This stops real pages reaching a real person. Say whose notifications will be paused, from when until when, and get agreement before calling it. Never invent an end time the user didn't give you: ask.

A pause doesn't take anyone off a rotation. Their shifts still show as theirs; we just skip them when we would otherwise page them. If they want someone to take their shift, that's cover_request_create (asks for volunteers) or schedule_override_create (changes who is on call). Say so rather than approximating it with a pause.

user_id defaults to the caller. Pausing anyone else needs the notification_pauses.manage_all permission. Requires user authentication (e.g. OAuth) rather than an API key.

Times must be UTC RFC 3339 ending in Z. Never convert a wall-clock time to UTC by writing an offset yourself: daylight saving shifts offsets and the pause lands on the wrong hours. A pause can last at most 6 months, and cannot end in the past.

A person's pauses can't overlap. If one already covers part of the window, extend or move it with notification_pause_update instead. Back-to-back pauses are fine.

Returns the created pause, whose ID notification_pause_update, notification_pause_resume and notification_pause_delete take.

Cancel an upcoming notification pause, so it never takes effect. Say whose pause you are cancelling and get agreement before calling it.

This refuses a pause that is active now: end that with notification_pause_resume, which keeps a record of the pause. To end a pause at a later time, move its ends_at with notification_pause_update instead.

You can cancel your own pauses. Cancelling anyone else's needs the notification_pauses.manage_all permission. Requires user authentication (e.g. OAuth) rather than an API key.

Take the pause ID from notification_pause_list.

List notification pauses: windows in which someone's on-call notifications are paused, so escalations skip them instead of paging them.

Use this for "am I paused?", "is anyone on the platform rota paused this week?", and to find the pause ID that notification_pause_update, notification_pause_resume and notification_pause_delete take.

Only current and upcoming pauses are returned unless you pass from. Pass user (a user ID, or "me" for the caller) for one person's pauses, and schedule_id for everyone on a schedule over the window. Each pause carries a status: active means we would skip that person if they were paged right now.

A pause doesn't change the rota: someone who is paused still shows as on call in schedule_show.

End an active notification pause now, so that person can be paged again. The pause is kept, ending at the time it was resumed, so schedules still show when they were paused.

Resuming means that person may start getting paged again straight away. That's fine during their working hours and a nasty surprise at 3am. Say whose pause you are resuming and get agreement before calling it.

Only for a pause that is active now. To drop an upcoming pause, use notification_pause_delete. To end a pause at a later time, move its ends_at with notification_pause_update.

You can resume your own pauses. Resuming anyone else's needs the notification_pauses.manage_all permission. Requires user authentication (e.g. OAuth) rather than an API key.

Take the pause ID from notification_pause_list. Returns the resumed pause.

Change a notification pause's window or reason, such as extending a holiday or coming back a day early.

Pass only what changes: omitted fields keep their current value. The pause stays with the same person.

Moving ends_at earlier resumes pages sooner, and moving starts_at later lets pages through until then. Say the new window and get agreement before calling it. To end an active pause right now, use notification_pause_resume instead: ends_at cannot be in the past.

Times must be UTC RFC 3339 ending in Z. Never convert a wall-clock time to UTC by writing an offset yourself. A pause can last at most 6 months, and can't overlap another of the same person's pauses.

You can change your own pauses. Changing anyone else's needs the notification_pauses.manage_all permission. Requires user authentication (e.g. OAuth) rather than an API key.

Returns the updated pause.

List all available resources. Resources provide context that helps you use the other tools effectively — organisation config, analysis playbooks, telemetry datasources, and more. Use resource_show to read a specific resource by name.

Read a resource by name. Resources provide context that helps you use the other tools effectively. This tool returns the same content as the MCP resources, for clients that don't support the resources protocol.

Use resource_list to see all available resources, or pass one of these names:

• alert_noise_playbook: Playbook for deep alert noise analysis. Identifies noisy sources, quantifies noise cost in responder time, and produces specific tuning recommendations.
• analysis_playbook: Index of all analysis playbooks. Describes which playbook to use for different questions (operational review, alert noise, on-call burden, team health, response effectiveness). Read this first to pick the right playbook.
• metrics_glossary: Glossary of derived metrics used across playbooks: workload ratios, alert quality scores, escalation rates, and lifecycle timings. Includes formulas, interpretation guidance, and source tools.
• on_call_burden_playbook: Playbook for assessing on-call sustainability. Analyses paging volume, ack rates, overnight burden, and workload distribution across people and teams.
• onboarding_context: datasource summaries and recent successful telemetry queries
• operational_review_playbook: Playbook for periodic operational reviews (weekly/monthly/quarterly). Covers incident volume, alert noise, paging load, responder burden, and follow-up health in one comprehensive analysis.
• organisation: incident statuses, severities, roles, types, custom fields, alert priorities — discover IDs for filtering
• presenting_results_guide: Guide for structuring and formatting analysis findings. Covers output structure, formatting conventions, and the branded HTML report template.
• response_effectiveness_playbook: Playbook for measuring response effectiveness: detection speed, resolution time, escalation response, and post-incident learning outcomes.
• scope_playbook: How to establish analysis scope with the user before running a playbook. Covers goal, time window, team/org scope, comparison periods, audience, and output format. Run this first.
• team_health_playbook: Playbook for per-team or cross-team operational health assessment. Combines incident, alert, and escalation data scoped to a team.
• telemetry_datasources: connected observability platforms and their capabilities

List on-call schedules with optional search, user filter, and pagination.

Schedules define who is on call and when. Each result shows who is currently on call and how many rotations the schedule has.

Pass user (a user ID, an email address, or "me" for the caller) to answer "am I on call?" and "when am I next on call?" in one call: results narrow to schedules that user is on, and each carries the user's in-progress shift (when they are on call right now) and their next shift, looking ahead 3 months.

Use schedule_show for full details: rotation configuration, shifts over a chosen time window (past included), and when the next handover happens. List results carry no handover time.

Only native incident.io schedules are returned. When the organisation manages on-call in an external provider (e.g. PagerDuty, Opsgenie), an empty result carries a note saying so — that means we cannot see who is on call, not that nobody is.

Pagination: results are ordered by name. Use page_size (default 15, max 50) and pass "next_cursor" as "after" to fetch subsequent pages. Stopping before "has_more" is false means you have incomplete results.

Create a schedule override, placing a user on call (or clearing the schedule) for a time period.

An override changes who gets paged, immediately and for real — state what will change and get agreement before calling this. Use user_id "NOBODY" to clear the schedule for the window, and "me" for the caller.

rotation_id and layer_id are optional for simple schedules where only one rotation and layer have shifts in the window. If the schedule has multiple rotations or layers, the call is rejected until you pass both — read them from schedule_show's rotation configuration.

Times must be UTC RFC 3339 ending in Z. Never convert a wall-clock time to UTC by writing an offset yourself — daylight saving silently shifts offsets and the override lands on the wrong instant.

Returns the created override, whose ID is what schedule_override_delete takes to undo it.

Delete a schedule override, restoring the underlying rotation for its window.

Use this to undo an override created by mistake or no longer needed. Deleting an override changes who gets paged for its window, so confirm before calling. Override IDs come from schedule_override_create's result, or from the override_id field on shifts in schedule_show.

Look up an on-call schedule by ID and return its full details and shifts.

Returns: name, timezone, rotation configuration, and shifts for the requested window (default: now to 7 days ahead). Pass "from"/"until" to move the window — including into the past, for questions like "who was on call last Tuesday night?". Each rotation includes its users, handover frequency, working hours, current shift end, and next shift start.

When the window includes the current time, each rotation reports "current_shift_ends_at" and "next_shift_starts_at". Equal values mean someone takes over at that instant. Different values show a coverage gap. A missing current end means the rotation is not covered now; a missing next start means nothing is scheduled within the window.

Shifts created by an override carry an "override_id" — that ID is how an override is targeted later — and "original_user_id"/"original_user_name", naming who the override took the shift from, so you can answer "who is Ana covering for?" without reading the rotation yourself. "shifts_truncated": true means the window held more shifts than one response carries; narrow the window for the rest.

Pass include: ["holidays"] to get the time off booked by anyone this schedule can put on call, over the same window. That answers "is anyone on call while they are away?" in one call, since the shifts are in the same response.

Use this to answer questions like "who's on call for the backend schedule?", "what does the rotation look like?", "when does the next handover happen?", "who is on-call next week?", or "who was on call during the incident?"

To see who would actually get paged when an alert fires, use escalation_path_show — it resolves schedules to current on-call users at each escalation level.

Only native incident.io schedules are accessible. A schedule imported from an external provider (e.g. PagerDuty, Opsgenie) returns not-found — that means we cannot read it, not that it doesn't exist.

Draft an update to a public status page for an incident: the next update when it is already published, or the first update, which publishes it to one of your existing status pages.

This tool only drafts. The draft is posted as a card into the conversation this call arrived from, and only a human can publish it — publishing emails or texts everyone subscribed to the page. Never tell the user an update has gone out. A caller who cannot show a publishable card is refused and told where to go instead, because a draft nobody can publish could never go live.

Action "suggest" (the default) drafts the update; "edit_suggestion" (with suggestion_id) revises an existing draft, and any field you omit keeps the draft's value. "execute" (publishing directly) is not supported yet and is refused.

For a first publish (the incident isn't on a status page yet): name is required, components must come from the page's own list, and if the organisation has more than one page the error lists them — ask the user, then pass status_page_id. When the incident is already on more than one page, pass status_page_incident_id the same way.

Write the message for customers reading the status page: lead with what they are experiencing, then what is being done about it, in plain prose that follows on from the previous updates — no internal jargon, no responder names, no incident IDs, no severity names, no internal links. Never speculate on cause, and never promise a fix time you can't evidence.

to_status moves the status page incident: investigating (something is wrong, cause unknown), identified (cause known, fix in progress), monitoring (fix applied, watching it hold), or resolved (impact over, and you're confident it is over). Keep the current status unless the evidence supports moving; moving backwards is fine when a fix didn't hold — say so in the message. For an update, only components already affected by this incident may move; resolving forces every affected component to operational.

List AI suggestions — drafts awaiting human action — with optional filters and pagination.

A suggestion is a draft the AI produced that a human accepts, edits, or declines: an incident update, summary, follow-up, escalation, or status page update. Each result carries the full drafted content (the same shape ask returns when called with incident_id), so no separate show call is needed.

Statuses:

• pending: awaiting action — these are the live drafts
• accepted / accepted_with_edits / declined: a human actioned it
• overridden: superseded by a newer suggestion or a manual update
• auto_applied: applied automatically on the org's behalf

Filters (all optional):

• incident_id: filter to a specific incident (accepts ID, external ID, or reference like INC-123). Suggestions without an incident are org-scoped and only appear when this filter is unset.
• suggestion_type: one or more of update, summary, follow_up, escalation, status_page
• status: one or more of the statuses above. Use status: ["pending"] to find live drafts — e.g. to check for an existing draft before creating another, or to find a draft's ID to edit.
• source: one or more of copilot (chatbot-drafted), copilot_edit, incident_activity, incident_update, generate_button_slack, generate_button_dashboard, request_update, orchestrator

Pagination: results are ordered newest first. Use page_size (default 10, max 50) and pass "next_cursor" as "after" to fetch subsequent pages.

To apply a pending draft, pass its id as suggestion_id with action "execute" to the tool that drafted it. Applying is real — an accepted escalation pages someone — so show the draft to a human first. Status page drafts cannot be applied this way: a human publishes them from the dashboard or Slack.

List teams with optional name search.

Teams are catalog entries of the organisation's configured team type. Each team owns resources like escalation paths, alert sources, and schedules — use team_show to see a specific team's owned resources.

Use this tool to discover teams when scoping analysis (e.g. "which teams exist?") or to find a team by name. Pass a query to filter by name substring.

Look up a team by ID and return its details with all owned resources.

Returns the team name and its owned escalation paths, alert sources, schedules, and alert routes. Use these resource IDs as filters when scoping analysis to a specific team:

• Escalation path IDs → escalation_stats(escalation_path: [...])
• Alert source IDs → alert_stats(alert_source: [...])

Use team_list to find team IDs, or check config://organisation for your own team.

Inspect one telemetry datasource to see the real labels, label values and metric names that exist on it, so a query you author references things that actually exist.

Run it before executing a verbatim expression via ask_telemetry's passthrough input. This goes a level deeper than the telemetry://datasources resource: that resource lists which sources exist and their capabilities; this tool looks inside a single source you already have an ID for.

Pass a datasource_id from telemetry://datasources, then pick a kind based on that source's capabilities:

• capability "logs" → kind="log_labels", target=<stream selector> — list the label names on matching streams (set label=<name> to list that label's values). The result's syntax_hint gives the selector syntax and how to list everything when you don't know a label yet.
• capability "metrics" → kind="metric_labels", target=<metric name> — list the labels on a metric (set label=<name> to list its values).
• capability "metrics" → kind="metric_search", target=<keyword> — find metric names containing that keyword, e.g. http. The result's syntax_hint says whether finer regex matching is supported.

If a source's capabilities (in telemetry://datasources) don't include the one a kind needs, that kind isn't supported for it.

Break down the time responders spent working on incidents, grouped by who spent it, by time bucket, or by a custom field.

Use this to answer workload-by-person questions — "responder hours by person last quarter", "who carried the most overnight load?". Each group returns the total responder-hours spent working on incidents, split by the time of day the work happened in the responder's local time — working hours, late evening, and overnight — so you can see out-of-hours burden. It also returns the number of distinct responders in the group.

Group by (combine at most two):

• user: the responder who did the work
• week / month / quarter: time bucket
• custom_field:<field_id>: a custom field's values (read config://organisation to find field IDs)

This tool sources the per-responder hourly workload table, so it can attribute time to individual people — which incident_stats cannot. It counts time spent within the active_after/active_before window (when the work happened, not the incident's creation date), matching the time-spent Insights dashboard. To break this time down by severity, team, type or other incident attributes, use incident_stats instead — it sums whole-incident workload from the per-incident rollup.

Workload is synced hourly and may be absent for very recent activity.

List users in the organisation. Use this to find user IDs for filtering (e.g. incident_list assigned_to), assigning follow-ups, or looking someone up by name or email.

Filters (all optional):

• query: name or email substring (case-insensitive). Matched against email if the value contains "@", otherwise against display name and real name. e.g. "hannah", "hannah@incident.io".
• email: exact email match. Use when you have the full address.
• seat_type: on_call, responder, on_call_responder, viewer.
• include_inactive: include deactivated or not-yet-active users (default false). Useful when looking up someone mentioned in an older incident who has since left.

To resolve "me" to your own user ID, read config://organisation — the "You" section contains your ID. user_list is for discovering other users.