# MCP tool reference

> Understand Anectico's MCP tool families and discover the tools available to your key.

Canonical page: https://anectico.com/docs/reference/mcp-tools/


The remote MCP server exposes only the tools allowed by the connected key. Let the MCP client
discover the current tool definitions instead of copying a fixed catalog into prompts.

## Start with `search` and `fetch`

Two tools are the way in, and everything else is where you go next.

- **`search`** takes one query and looks for it across people, issues, log lines, business accounts
  and Anectico's own documentation in a single call. It returns a compact list of hits — each a
  `ref`, a canonical `anectico://…` reference — plus a per-source report saying which sources were
  searched and which were skipped and why.
- **`fetch`** takes one of those references and returns the object it names.

Neither adds any search power of its own. `search` runs each source through that source's own tool
and says which one produced every hit; `fetch` returns exactly what the object's own read tool
returns. So the answer always tells you the specialised tool to use when you need its filters —
service, severity, window, cursor — and your key needs the same scopes it would have needed to call
that tool directly. A source your key cannot read is reported as such and is never queried.

A `ref` is also what every tool's `evidence` array carries — but **a citation is not automatically
fetchable**, and the two are worth keeping apart. `fetch` resolves exactly seven kinds: `person`,
`error_group` (an issue), `trace`, `incident`, `agent_run`, `account` and `doc` (a documentation
page). Every search hit carries `fetchable`, so check the flag rather than the presence of a `ref`.
Note the singular: the search report calls the source `docs` and the reference kind is `doc`.

Three cited kinds are deliberately not fetchable, and each refusal names the way through:

| Cited kind | Why not | What to do instead |
| --- | --- | --- |
| `log` | A log line has no single-object read | Find it with `search_logs`, or fetch the trace its citation carries |
| `session` | A recording is reached by its own panel | `get_session_signals` with the session id |
| `query` | It is a re-runnable query, not an object | Re-run the tool the citation names |

**Traces are deliberately not a `search` source.** Traces are found by filter rather than by text
(`search_traces` takes service, operation, person, minimum duration and errors-only), and by pivot: a
log hit carries its trace reference, which `fetch` resolves.

The reference is `fetch`'s only argument. It already carries the project when the object needs one,
so there is nothing else to pass — and holding a reference grants nothing on its own: every fetch is
authorized against your key exactly as the original read was.

## Focus the tool list with a profile

Add `?profile=<name>` to the MCP endpoint URL to narrow what your client is offered:

```
https://app.anectico.com/mcp?profile=incident
```

| Profile | What it leaves visible |
| --- | --- |
| `investigate` | The read-only debugging surface: people, issues, logs, traces, metrics, service health, timelines, cohorts, product events, feature-flag decisions, agent runs, and this documentation. No mutations at all. |
| `incident` | Everything in `investigate`, plus the incident and alert lifecycle: who is paged, what fired, what was delivered, what was filed, and the writes that respond to it. |
| `agent-observability` | AI-agent operations: agent runs, their transcripts, what they cost, and the evaluation loop. |
| `admin` | Organization administration: keys, members, projects, connections, plan usage — and this documentation, since configuring a scope or an alert is where looking one up matters most. |

Three things are worth being exact about:

- **A profile can only ever subtract, never reveal.** What it subtracts, it subtracts for the whole
  connection: a tool a profile excludes is not listed **and** cannot be called, even by a key that
  holds its scope. Your key's scopes are unchanged, and reconnecting without the parameter gives you
  the full surface again — which is why this is a focus control rather than a permission. If you
  want a genuinely narrower credential, mint one: `anectico apikey create --scope-profile
  investigate` materializes the same bundle into actual scopes.
- **Omitting the parameter changes nothing.** Without `?profile=`, you get everything your key is
  scoped for, exactly as before.
- **An unrecognized profile is refused** with `400` and the list of valid names, rather than being
  ignored. A typo that silently served the whole surface would look like the filter working.

Because a profile only ever subtracts, `search` and `fetch` disappear under a profile that admits none of
the tools they route to, and they disappear independently. Today `search` is absent under
`agent-observability`, which names none of its sources; `fetch` survives there and resolves
`agent_run` references alone, refusing the other kinds by naming the tool that would answer for them.
Under `admin` both are served but route to the documentation only. Connect without the parameter, or
use a profile whose sources you need.

Which client can use the endpoint at all, and how large a tool list each key produces, is in
[MCP client compatibility](/docs/reference/mcp-compatibility).

## How the surface is organized

MCP hosts have a practical limit on how many tools they handle well, and none of them publishes it:
the overflow simply stops being offered to the model inside your client, with nothing reported.
Anectico therefore budgets against two deliberately pessimistic design targets — **40**, past which we
assume a host may silently drop tools, and **50**, past which we assume selection accuracy degrades —
keeps the tool list small on purpose, and reaches the rest through gateways:

- **First-class tools** are the investigation core, the reads you use constantly while debugging:
  Issues and affected customers, logs, traces, metrics, service health, customer and account
  timelines, incidents, alerts, anomalies, session replay, cohorts, product events and feature-flag
  decisions, and agent runs.
- **`list_read_actions` / `execute_read_action`** reach the administrative reads: on-call schedules
  and rotation resolution, notification delivery receipts, external ticket links, saved searches,
  B2B account lookup, product and export definitions, plan/quota usage, and LLM cost.
- **`list_write_actions`** discovers the less common mutations, alongside a few daily write actions
  promoted to first-class tools. Running one uses **`execute_internal_action`** or
  **`execute_external_action`** — see below.

Nothing is unavailable behind a gateway, and an action your key is not scoped for is neither listed
nor runnable. Scopes are per action, not per gateway.

## Two doors for writes, and the three properties every mutation declares

There are two tools that run a discovered mutation, not one, and which of them accepts an action is
decided by how far that action's effect reaches:

- **`execute_internal_action`** runs an action whose effect stops inside your organization — creating,
  updating or deleting Anectico's own records. An internal action may still contact an outside
  provider while it runs, such as to validate a connection credential; the distinction is that it
  leaves no lasting effect there.
- **`execute_external_action`** runs an action that also causes something Anectico cannot retract:
  a message delivered, an email sent, an issue filed or closed in your own tracker. Deleting the
  Anectico-side record afterwards does not unsend it.

Every action belongs to exactly one of the two. Calling the other door is refused with the same
answer an unknown action id gets, so the pair cannot be used to probe what your key can reach.

**Your arguments are checked against the action's published schema before anything runs.** Send a
field the action does not declare, or the wrong type for one it does, and the call is refused and
names the field. A mistyped argument is never quietly ignored or read as an empty value, so a typo
cannot turn into a write against a blank id or an empty filter. Two keys are accepted on every
action whether or not its schema lists them, because they belong to the call rather than to the
action: `idempotency_key`, and `confirm_token` on an approval-gated action.

`list_write_actions` reports three **independent** properties for every action, and none of them
implies another:

| Property | Question it answers | Values |
| --- | --- | --- |
| `effect_scope` | How far can this reach? | `internal`, `external` |
| `destructive` | Does it remove state a key holding only this action's scope cannot put back? | `true`, `false` |
| `approval` | Does it require preview-and-confirm before it applies? | `confirm`, `none` |

**`approval` is about the protocol, not about a person.** `confirm` means the action will not apply
on the first call: it previews, hands back a `confirm_token`, and applies only on an identical second
call carrying that token — **once**. That token is spent when it applies; a third call repeating it is
refused, and "identical" includes any `idempotency_key` you sent with the preview. A confirmation that
cannot be claimed refuses the write and changes nothing. It does **not** mean a human saw the preview — nothing in the server can
tell someone pressing approve from an agent immediately calling again with the token. Whether a human
is in the loop is a property of your MCP host's approval settings, and yours to verify.

An action can be external and non-destructive (filing a ticket creates something rather than
removing it), internal and destructive (deleting a dashboard), or any other combination. Each entry
also carries `execute_with`, naming the door that will accept it.

Because the three are independent, `destructive` is not a door — it spans both. Pass it as a filter
to get the complete set: `list_write_actions` accepts `effect_scope`, `destructive` and `approval`
alongside `domain` and `query`, and an unfiltered call is never truncated.

**Every successful write call returns structured content**, beside the sentence you read — there is
no action that answers with prose alone. A receipt names what the write was about, what the change
committed to, when the owning transaction says it happened, and whether anything actually moved;
where the platform cannot tell, the field is `null` rather than a plausible guess. Every action
publishes the schema in its `list_write_actions` drill-in, so you can code against the shape before
you call it, and the server checks each result against that schema before serving it.

Read the `outcome` field to tell the three successful stages apart:

- `applied` — **the state you asked for now holds, because of this call.** That includes the
  idempotent case: a delete addressed at something already gone asked for "this is not here", and
  that is now true. It is deliberately not a claim that a row was written, because a receipt that
  distinguished "removed something" from "there was nothing to remove" would answer the existence
  question the next paragraph explains is not on offer.
- `preview` — **nothing happened.** This is the first call of an action whose approval is `confirm`.
  The summary carries the `confirm_token` and the instructions for applying, so you can drive the
  whole confirm flow from the structured half without parsing prose.
- `replayed` — **an earlier identical call did this; you are seeing its result again.** You get this
  when you retry with the same `idempotency_key` and arguments inside the retry window. The receipt
  is the one that call produced, so it is safe to treat as the answer to your retry.

If an identical call carrying the same `idempotency_key` is still running, you get an error telling
you to retry shortly — not a receipt. Nothing has been lost: the first call is still going, and its
result becomes replayable once it finishes.

**A delete succeeds when there was nothing to delete.** Deleting an id that does not exist returns
an ordinary receipt rather than an error, and that receipt is identical to the one you get for an id
that was really removed — it names the id you addressed and says in its warnings that it makes no
claim about whether that object existed beforehand. This is deliberate, and it has two consequences
worth coding against. A delete is safe to retry: an error means the call did not land and you should
try again, a receipt means you can stop, and the two never blur. And a receipt is **not** confirmation
that the object was there — if you need to know that, read it back before you delete, or check the
error the read gives you. The reason for the rule is that a delete is not a way to ask what exists: a
key holding only a delete scope would otherwise learn which ids were real by watching which calls
failed, without being scoped to list them.

The exception is a delete that takes an `expected_version`. Those refuse an unknown id and refuse a
stale version as two different errors, because they cannot report a verified version for a row they
did not compare against, and because a version conflict is a signal you need — it means somebody
else changed the object and you should look again before deleting it.

Telling those two errors apart does reveal whether the object exists, so **every one of them requires
the matching read scope as well as its delete scope** — `delete_dashboard` and `delete_widget` need
`dashboard:read`, `delete_saved_search` needs `saved_search:read`. That is the price of keeping the
version conflict visible, and the tables below list it. An earlier version of this page argued the
requirement was unnecessary because "you already need a current version to call them, so you have
already read the object". That was wrong: nothing checks where your version came from, so a
deliberately wrong number returns the same two errors and answers the same question without deleting
anything.

`delete_cohort` requires `analytics:read` for the same reason, arrived at from the other direction:
removing a cohort does extra work that only happens when the cohort is really there, so while that
work is failing the two cases stop looking alike. Requiring the scope that can list cohorts means the
difference tells you nothing you could not simply have asked for.

A committed write's receipt carries `effect_scope` and `destructive` too, so a record of what you
did says how far it went without re-reading the catalog. Product definitions and exports are separate
actions with their natural scopes: `list_projects` requires `projects:read`, `list_flags` requires
`flags:read`, the dashboard actions require `dashboard:read`, export job list/detail requires
`export:read`, and `get_export_download` requires `export:download` plus continued access to the
exported source data. Neither tool listings nor action listings report scopes; the tables below are
where you look up what each action requires.

<!-- BEGIN GENERATED CAPABILITY REFERENCE. Generated from the Anectico capability catalog. Do not edit by hand. -->

## Every tool and action

The endpoint serves 217 capabilities: 37 first-class read tools, 82 read actions behind the read gateway, 6 write tools promoted out of the write gateway, and 92 write actions behind it. The five gateway tools themselves — `list_read_actions`, `execute_read_action`, `list_write_actions`, `execute_internal_action` and `execute_external_action` — are the doors onto those actions rather than capabilities of their own.

### Scopes

Every capability is gated twice, and both gates must pass:

1. the umbrella scope for that side of the endpoint — `mcp:read` for every read, `mcp:write` for every write;
2. the domain scope in the capability's own row below.

A key minted with `mcp:read` and nothing else is served an empty tool list. Mint the key with the domain scopes the agent's job needs, and expect a tool to disappear when one of them is missing.

The `search` and `fetch` entry points are the only rows whose scope cell reads differently, and they are still not an exception to that: each routes your call to one of the tools named in its cell, checks that tool's own scope before it runs, and is not offered at all to a key that holds none of them.

Both halves of the gate are real: a capability your key is not scoped for is never listed, and calling it by name is refused with the same answer an unknown name gets — so the surface cannot be used to enumerate what your key is missing.

**The scopes in a row are the minimum, and five capabilities need more.** A capability whose work reaches another area is checked again where that work happens:

- `create_export_job` and `export_logs` also require the exported signal's own read scope — `logs:read` for a logs export, `traces:read` for traces, and so on. Without it the export is refused, so `export:write` alone cannot commission an export of data the key may not read.
- `retry_export_job` re-checks the same requirement against the job it is re-running, so a key that has since lost the signal's read scope cannot regenerate the file.
- `get_export_download` also requires the read scopes the job's rows came from, re-checked against the caller's CURRENT scopes at the moment of the request, and it is limited to whoever created the job or to an owner or admin.
- `set_issue_status` additionally requires `members:read` only when assigning to a non-empty member. Resolve, ignore, unresolve, unassign, and its other actions need only the scopes shown in the row.

Everything else is gated exactly as its row says.

The **Area** column groups related capabilities. For a read action it is exactly the `domain` filter: pass it to `list_read_actions` to drill into that area and get its actions' argument schemas. The write gateway browses under display names — `dashboards`, `cohorts`, `saved_searches` and a few others differ from the Area shown here — but its `domain` filter accepts either form, so the Area value below always drills in.

### First-class read tools

Registered as their own MCP tools, so an agent can select one directly without a discovery hop.

| Tool | Area | Required scopes | What it answers |
| --- | --- | --- | --- |
| `get_account_timeline` | `accounts` | `mcp:read` + `groups:read` | Get one business account's merged newest-first timeline across every person in it, optionally restricted to one signal or window. |
| `list_agent_fleet` | `agent_fleet` | `mcp:read` + `agents:read` | List the project's agent fleet with 24-hour run and failure counts, open review signals, containment metadata when authorized, and explicit unattributed activity. |
| `get_agent_run` | `agent_runs` | `mcp:read` + `agents:content:read` | Get one AI agent run: its status, steps, tokens and cost, plus its conversation transcript truncated to the opening and closing messages. |
| `list_agent_runs` | `agent_runs` | `mcp:read` + `agents:read` | List AI agent runs newest-first with their outcome, step and tool counts, model providers and cost, optionally filtered by agent, person, status or window. |
| `get_active_alerts` | `alerts` | `mcp:read` + `alerts:read` | List the currently-firing alerts with severity, state, start time and the identifiers the acknowledge and resolve actions consume. |
| `list_alert_rules` | `alerts` | `mcp:read` + `alerts:read` | List the configured alert rules with their severity and active state, plus the silences currently in effect and their windows. |
| `list_event_names` | `analytics` | `mcp:read` + `analytics:read` | List one project's captured product-event names with their counts, optionally narrowed by name prefix or an exact event property. |
| `list_event_triggerers` | `analytics` | `mcp:read` + `analytics:read` | Page the people who triggered one product event in one project over an exact window, optionally narrowed by an exact event property. |
| `list_anomaly_findings` | `anomalies` | `mcp:read` + `anomalies:read` | List detected statistical anomalies with their signal, metric, severity, score, detection time and a plain-English explanation, optionally filtered by status. `sort` chooses the order: newest first by default, or `actionability` to put the findings a ranking model judged most likely to be real faults first and unranked ones last. A ranked finding carries `actionability_score` (0-3) and `likely_real`; both orders return the same findings, and an unmarked finding is one the ranking did not promote, never one it called noise. |
| `get_cohort_members` | `cohorts` | `mcp:read` + `analytics:read` | Page every person in one cohort, optionally as of one retained historical generation rather than the current one. Requires the generation's source scopes: persons:profile:read and/or agents:content:read when applicable. |
| `list_cohort_generations` | `cohorts` | `mcp:read` + `analytics:read` | List one cohort's materialization history newest-first: member counts and deltas, why each was built, whether its members are retained, and its mirror status. Counts require the selected and preceding generations' source scopes (persons:profile:read and/or agents:content:read); membership_withheld identifies unavailable counts, whose zero is not a measured empty cohort. Original content-erasure evidence must remain valid. |
| `list_cohorts` | `cohorts` | `mcp:read` + `analytics:read` | List one project's cohorts with their kind, member count and current generation, or get one cohort's full definition, version and mirror state. Counts require the sources' scopes (persons:profile:read and/or agents:content:read); membership_withheld identifies unavailable counts, whose zero is not a measured empty cohort. Original content-erasure evidence must remain valid. |
| `preview_cohort` | `cohorts` | `mcp:read` + `analytics:read` | Evaluate a candidate cohort definition and return its exact size plus a deterministic sample, without saving it or changing any existing membership. Profile predicates require persons:profile:read; declared or nested content event filters require agents:content:read and allowing current policy. Preview refuses expired history, changed policy/declarations, missing source evidence or exceeded source limits; no partial audience is returned. |
| `get_affected_users` | `errors` | `mcp:read` + `errors:read` | Get an error issue's blast radius: the people it hit with their first and last occurrence, the accounts they belong to, and the totals behind both. |
| `get_issue` | `errors` | `mcp:read` + `errors:read` | Get one error issue's root-cause payload: status and counts, the latest occurrence with its stack trace and breadcrumbs, suspect commits and recent occurrences. |
| `list_issues` | `errors` | `mcp:read` + `errors:read` | List error issues most-relevant-first with their event and affected-people counts, optionally filtered by status, service, release and look-back window. |
| `search_issues` | `errors` | `mcp:read` + `errors:read` | Find error issues whose message or type matches a search term, optionally narrowed by service, severity and look-back window. |
| `decide_feature_flags` | `flags` | `mcp:read` + `flags:read` | Evaluate one project's feature flags for one person, returning each flag's decision and payload given the supplied person properties and account memberships. |
| `get_local_evaluation_snapshot` | `flags` | `mcp:read` + `flags:read` | Get one project's complete feature-flag snapshot for local evaluation, with its schema version, snapshot version, freshness budget and entity tag. |
| `get_incident` | `incidents` | `mcp:read` + `incidents:read` | Get one incident's case file: version, ordered timeline, evidence, linked signals and delivery receipts. |
| `list_incidents` | `incidents` | `mcp:read` + `incidents:read` | List one project's incidents, optionally filtered by lifecycle status, with the current version each lifecycle write has to quote. |
| `get_investigation` | `investigations` | `mcp:read` + `investigations:run` | Read one investigation: its subject, status, and every question-and-answer turn with the grounded conclusion, its citations, the exact blast radius and what the model call cost. Poll it after investigate to collect the answer. A turn whose answer was produced with access to recorded customer content the caller's role does not include is listed with its answer withheld rather than hidden. |
| `investigate` | `investigations` | `mcp:read` + `investigations:run` | Start a grounded AI investigation of one subject — an issue, a person, an account, an agent run, an incident, an exact saved audience, LLM spend, or an open question about a project — and get back its id, the exact blast radius, and whether an identical investigation was already answered. The answer itself is produced in the background: read it with get_investigation. An incident or project subject needs a project. An audience requires cohort_id, decimal-string audience_generation, explicit since/until and a matching project, plus analytics:read, persons:read and current source permissions; its bounded inspected sample never replaces the full saved count. An issue, person, account or agent run narrows to one when given it; an LLM-spend investigation is organization-wide and a project-scoped credential cannot run it. The evidence gathered is limited to what your key could read directly, so a key without errors:read gets an investigation with no error evidence in it — and cannot investigate an issue at all; the answer names what it did not examine. |
| `get_log_patterns` | `logs` | `mcp:read` + `logs:read` | Cluster a window's logs into recurring templates with counts — each carrying a suggested category and an attention flag once it has been labeled, and neither until then — or, with a group-by field, return that window's log counts grouped by it. |
| `search_logs` | `logs` | `mcp:read` + `logs:read` | Search log lines by text with optional service, severity, trace, person and look-back filters, returning each line with its trace correlation. |
| `query_metrics` | `metrics` | `mcp:read` + `metrics:read` | Query one metric as a bucketed time series over a window, or — with no metric name — list the metric names available to query. |
| `get_person_profile` | `persons` | `mcp:read` + `persons:profile:read` | Get one person's identity card: canonical id, identified flag, top profile properties, first and last seen, and per-signal activity counts. |
| `get_person_timeline` | `persons` | `mcp:read` + `persons:read` | Get one person's merged newest-first timeline across product events, errors, traces, logs, agent runs and sessions, optionally restricted to one signal or window. |
| `resolve_person` | `persons` | `mcp:read` + `persons:read` | Collapse any identity key — a person id or a raw distinct id — to the one canonical person and its distinct-id aliases. |
| `search_persons` | `persons` | `mcp:read` + `persons:read` | Find people by distinct id or profile property and return each one's canonical person id, identified flag and distinct-id aliases. |
| `get_session_signals` | `replay` | `mcp:read` + `replay:content:read` | Get the cross-signal panel for one session recording: the errors and product events captured during it, and the person it belongs to. Requires a current active project; project verification outages fail the read. |
| `list_recordings` | `replay` | `mcp:read` + `replay:read` | List a person's session recordings newest-first with each session's start, end and duration, and a link to play it back. Only current active projects are included; project verification outages fail the read. |
| `fetch` | `search` | `mcp:read` + the scope of the tool it routes to (`get_account_timeline`, `get_agent_run`, `get_doc`, `get_incident`, `get_issue`, `get_trace`, `resolve_person`) | Resolve one citation reference — the anectico:// value a search hit or an evidence citation carries — to the object it names, returning exactly what that object's own read returns. |
| `search` | `search` | `mcp:read` + the scope of the tool it routes to (`search_accounts`, `search_docs`, `search_issues`, `search_logs`, `search_persons`) | Find people, issues, log lines, business accounts and documentation pages matching one query, returning a reference for each hit that fetch resolves; org-wide unless a project is supplied or the credential is project-scoped. |
| `get_service_health` | `services` | `mcp:read` + `services:read` | Get per-service health, activity rate, error rate and latency over a window, a single service's bucketed series, or a bounded long poll that returns on a health change. |
| `get_trace` | `traces` | `mcp:read` + `traces:read` | Get one distributed trace by id: its service, duration and error summary plus its spans, reduced to the failing and slowest spans when the trace is large. |
| `search_traces` | `traces` | `mcp:read` + `traces:read` | Find distributed traces by service, operation, person, minimum duration or error presence over a window, returning each trace's root operation and id. |

### Read actions

Reached with `execute_read_action` after finding them through `list_read_actions`. Each enforces exactly the scope its own tool would; the discovery hop is what buys back the tool slots the host limit is measured in.

| Action | Area | Required scopes | What it answers |
| --- | --- | --- | --- |
| `search_accounts` | `accounts` | `mcp:read` + `groups:read` | Find business accounts by key or name, returning the account type and key the account-anchored reads need; with no arguments it lists the account types in use. |
| `get_agent_run_graph` | `agent_runs` | `mcp:read` + `agents:read` | Get one agent run's execution structure — every step, its parent, category, duration, and the outcome it declared with the error type when it failed, plus the count of non-span evidence attached to it and the action receipts it produced (approver, delegation chain, policy, lifecycle state, whether the effect was verified, and whether it was later compensated or rolled back). |
| `list_context_events` | `agent_runs` | `mcp:read` + `agents:read` | List one agent run's accepted context assembly, compaction, and cache events, optionally narrowed to events whose assembly names one context source id. |
| `list_agent_sessions` | `agent_sessions` | `mcp:read` + `agents:read` | List AI agent conversations newest-activity-first with their turn and run counts, participating agents, tokens and cost, optionally filtered by person, agent or time window. |
| `list_agent_turns` | `agent_sessions` | `mcp:read` + `agents:read` | List the exchanges within one agent conversation newest-first: each turn's position, the agent that answered, its timing, the run ids it produced, tokens and cost. |
| `get_telemetry_completeness` | `agent_telemetry` | `mcp:read` + `agents:read` | Report exact agent-telemetry row counts per normalizer version and source schema, newest normalizer first, so partially-stale data is visible instead of averaged away. Each bucket carries a resolution naming which of its fields no longer mean what the current normalizer means and which were never read for those rows, so older rows are flagged rather than silently reinterpreted. |
| `get_slo_burn` | `alerts` | `mcp:read` + `alerts:read` | Get an SLO rule's error-budget burn rate: the budget in failing-run events, how much remains, and the burn rate per window, with a window holding no evaluations reported as not measured rather than as a burn of zero. |
| `compare_analytics_results` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Read original and later exact results under current source permissions, preserving separate windows, identity, coverage and populations. Requires the prepared question and exact audience generation; no causal or completeness claims. |
| `get_analytics_audience` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Read one exact retained derived audience generation under current source authority. Metadata, count and lifetime only; no private receipts or members. Expired/pruned generations remain unavailable. |
| `get_analytics_contribution` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Read one exact funnel participant event chain and first-entry reference under current source and identity authority; frozen attribution and maturity facts, no live event search. Occurrences with a session id carry a typed replay reference — available, none_recorded or withheld — and available ones a session-replay link. |
| `get_analytics_remeasurement_source` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Prepare an explicit absolute-window remeasurement template from an original result and optional exact saved audience generation. No query execution or saved-insight edit; expired original metrics remain unavailable. |
| `get_analytics_result` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Read an immutable product result under current source authority; preserves definition, charts, value states and coverage without rerunning it. A pending or running execution reports status and result id with no payload; wait_millis (default 0, max 25000) polls this endpoint locally for a terminal status before returning. |
| `get_capture_quality` | `analytics` | `mcp:read` + `analytics:read` | Inspect retained capture-attempt counts for an exact project/window, separating pending, queued, uncertain, not attempted and refused positions. Source completeness remains unknown; queued is not consumed and zero does not prove absence of loss. |
| `get_event_catalog` | `analytics` | `mcp:read` + `analytics:read` | Discover event names, window-local occurrence counts and first/last event times for an exact project/window. Expiring cursors bind all filters; receipt cutoff is not a frozen snapshot or consumption watermark. Platform and upstream completeness remain unknown, including empty results. |
| `get_event_schema` | `analytics` | `mcp:read` + `analytics:read` | Discover permitted literal property keys and JSON type/presence counts for one event in an exact project/window. Derived content schema obeys requesting scope and current policy/retention; no raw examples. Missing keys and empty results do not prove absence or completeness. |
| `get_metric_watch` | `analytics` | `mcp:read` + `alerts:rules:read` | Read project metric-watch definitions and exact current versions without executing telemetry; list pagination scans bounded project rule pages and claims no watch total. |
| `get_saved_insight` | `analytics` | `mcp:read` + `insights:read` | Read a current or exact retained saved-insight definition under current metadata authority. Use format portable with an exact revision to export a reusable file without ownership/history. Lossless untrusted configuration JSON; does not execute telemetry queries. |
| `get_tracking_plan` | `analytics` | `mcp:read` + `tracking_plans:read` | Read current or retained tracking-plan configuration; portable export requires an explicit positive revision. Retired plans are unavailable; exact configuration is ASCII-escaped JSON marked as untrusted data. No capture, deployment or write authority. |
| `get_tracking_plan_drift` | `analytics` | `mcp:read` + `analytics:read` + `tracking_plans:read` | Compare one pinned tracking event declaration with permitted stored schema for an exact project, environment and time window. Missing or withheld evidence stays unknown; observed mismatches warn without blocking capture. No deployment or completeness proof. |
| `list_analytics_audience_members` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Page exact retained audience person UUIDs under current inherited source authority. Full population count is separate from page size; cursor binds generation, tenant, limit and expiry. No current-generation substitution or signal-access grant. |
| `list_analytics_audiences` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Discover project-visible derived audience names and exact generation references. Live metadata pagination; no membership, counts, source details or usability claim. Exact get retains current source checks. |
| `list_analytics_participants` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Page one frozen contributor selection with current source/identity checks. Exact cursor binding; no live rerun, audience creation or export. |
| `list_metric_watch_runs` | `analytics` | `mcp:read` + `alerts:rules:read` + `analytics:read` + `insights:read` + `persons:read` | Read retained evaluation history across metric-watch revisions under current source permissions. Missing artifacts omit samples; no execution or delivery. Follow scope-bound keyset cursors with the same limit. |
| `list_metric_watches` | `analytics` | `mcp:read` + `alerts:rules:read` | Read project metric-watch definitions and exact current versions without executing telemetry; list pagination scans bounded project rule pages and claims no watch total. |
| `list_saved_insights` | `analytics` | `mcp:read` + `insights:read` | List/search live saved-insight metadata with project scope and UUID pagination; no snapshot or total count is claimed. |
| `list_tracking_plans` | `analytics` | `mcp:read` + `tracking_plans:read` | List bounded live tracking-plan metadata with project scope and UUID pagination. Expected instrumentation is not evidence of deployment or completeness. |
| `preview_analytics_audience` | `analytics` | `mcp:read` + `analytics:read` + `persons:read` | Assess a complete frozen selection for a derived person audience; exact counts and source scopes, no member IDs, mutation or publication grant. Unresolved people, account selections and selections over the member limit remain distinct. |
| `preview_metric_watch` | `analytics` | `mcp:read` + `analytics:query` + `analytics:read` + `insights:read` + `persons:read` | Preview a native closed-period scalar and threshold from an exact saved insight revision under current source permissions. Explicit execution key and as_of freeze scalar arguments; no watch, schedule or notification changes. Missing evidence remains null with a reason. |
| `query_product_analytics` | `analytics` | `mcp:read` + `analytics:query` + `analytics:read` + `persons:read` | Execute a bounded trend, ordered person funnel or exact-period retention query. Supply exactly one inline definition or saved_insight with an exact positive decimal-string revision; the saved form also requires insights:read. An explicit retry key freezes result and selection references under current source permissions. wait_millis (default 20000, max 25000) blocks for a terminal execution status; a pending, running or other non-ready answer reports status, result id and failure reason with no payload -- poll get_analytics_result with that result id rather than retrying. Unknown coverage cannot prove drop-off or mature retention. No saved insight or audience is created. |
| `validate_saved_insight` | `analytics` | `mcp:read` + `insights:read` | Validate a portable saved-insight document and current references in its target project; no query, mutation or future approval. Import via create_saved_insight with document and preview/confirmation. |
| `validate_tracking_plan` | `analytics` | `mcp:read` + `tracking_plans:read` | Validate a portable tracking document in the current target project without mutation, capture query or approval. Expected declarations do not transfer effective sensitivity history. |
| `get_connection` | `connections` | `mcp:read` + `connections:read` | Read one connection by identifier, including the current version a credential rotation must quote; call it immediately before rotating so the version quoted is the freshest one. |
| `list_connections` | `connections` | `mcp:read` + `connections:read` | List the organization's third-party connections with each one's identifier, provider, kind, status, whether a credential is stored, and the current version a credential rotation must quote. |
| `get_dashboard` | `dashboard` | `mcp:read` + `dashboard:read` | Get one dashboard's current version and every widget's id, type, title and query configuration. |
| `get_saved_insight_widget_status` | `dashboard` | `mcp:read` + `dashboard:read` + `insights:read` | Read one saved widget's exact pin, owning revision and confirmation state. A newer source revision is informational only; missing and retired sources are unavailable. Requires current dashboard and saved-insight metadata access. |
| `list_dashboards` | `dashboard` | `mcp:read` + `dashboard:read` | List the dashboards visible to the credential with each dashboard's id, current version and widget count. |
| `query_saved_insight_widget` | `dashboard` | `mcp:read` + `analytics:query` + `analytics:read` + `dashboard:read` + `insights:read` + `persons:read` | Execute one confirmed saved widget at the exact owning revision with an explicit retry key. Current credential and all source permissions are rechecked. Editing/removing the widget refuses the old execution; no latest-revision substitution or dashboard time override. |
| `get_doc` | `docs` | `mcp:read` + `docs:read` | Read one documentation page as markdown, with its H2-H6 heading outline; pass a heading to get just that section, which is how to read one endpoint out of a reference page without paging the whole thing. |
| `search_docs` | `docs` | `mcp:read` + `docs:read` | Search Anectico's product documentation and get back the matching pages with their titles, sections, public URLs, and a ranking score — the same pages, and the same ranking, as the published documentation site. |
| `get_problem_report` | `errors` | `mcp:read` + `agents:content:read` + `errors:read` | Read a redacted customer report and its caller-supplied correlation context; identifiers are not proof of a causal link. |
| `list_problem_reports` | `errors` | `mcp:read` + `agents:content:read` + `errors:read` | List explicit customer problem reports from the last seven days with a continuation cursor. Pixels require separate replay content access. |
| `list_escalation_policies` | `escalation` | `mcp:read` + `escalation:read` | List one project's escalation policies with their identifier, name, active state, number of escalation levels, repeat interval and matched severities. |
| `compare_eval_experiment` | `evaluation` | `mcp:read` + `evals:read` | Compare every challenger arm of one experiment with its declared baseline on the same frozen cases, with the declared multiple-comparison correction applied across the whole family and the guarantee that correction carries stated in words. |
| `get_eval_dataset` | `evaluation` | `mcp:read` + `evals:read` | Read one evaluation dataset with every sealed version, when each was sealed and how many cases it holds. Versions are immutable: a promotion or a removal seals a new one. |
| `get_eval_experiment` | `evaluation` | `mcp:read` + `evals:read` | Read one experiment's declaration — the pinned dataset version, the exact evaluator versions, the candidate arms with their declared baseline, and the multiple-comparison correction — together with how much of it has been run. |
| `get_release_gate` | `evaluation` | `mcp:read` + `evals:read` | Read one release gate: what evidence it reads, the objectives it must meet, and every decision it has reached, newest first — each with its verdict, the reason, and per objective whether the value was measured at all. |
| `list_eval_datasets` | `evaluation` | `mcp:read` + `evals:read` | List the project's evaluation datasets — the frozen case sets experiments and release gates are measured on — with each one's sealed version count and newest version. |
| `list_eval_experiments` | `evaluation` | `mcp:read` + `evals:read` | List the project's evaluation experiments — paired comparisons of two or more configurations over one pinned dataset version — with the dataset each is bound to. |
| `list_release_gates` | `evaluation` | `mcp:read` + `evals:read` | List the project's release gates with each one's latest verdict, optionally narrowed to the gates declared about one release label. A gate that has never been evaluated reports PENDING, which is not a pass. |
| `get_export_download` | `export` | `mcp:read` + `export:download` | Issue a download grant for one completed export job after rechecking access to the exported content. |
| `get_export_job` | `export` | `mcp:read` + `export:read` | Get one export job's lifecycle status, progress, retry state and expiry without revealing its source query. |
| `list_export_jobs` | `export` | `mcp:read` + `export:read` | List one project's export jobs with lifecycle status, progress, retry state, expiry and signed-cursor pagination. |
| `list_flags` | `flags` | `mcp:read` + `flags:read` | List one project's feature flags with each flag's stable key, active state and multivariate rollout percentages. |
| `instrumentation_doctor` | `instrumentation` | `mcp:read` + `query:read` | Explain bounded trace and log evidence or verify one identified customer story across browser, backend, error, event and optional replay, preserving permission and evidence limits. Optional paired tracking_plan_id/revision for browser/mobile additionally require tracking_plans:read and analytics:read, returning a separate project-event sample without changing journey_verified. |
| `list_diagnostic_captures` | `instrumentation` | `mcp:read` + `persons:read` | List unexpired diagnostic requests; acknowledgment and allocation do not prove delivery. |
| `list_invitations` | `invitations` | `mcp:read` + `members:read` | List the organization's member invitations with their identifier, invitee, role, lifecycle status and expiry. |
| `llm_cost_series` | `llm_cost` | `mcp:read` + `llm:read` | Return model spend over time as a bucketed series, with each bucket's cost, tokens and call count. |
| `llm_cost_summary` | `llm_cost` | `mcp:read` + `llm:read` | Summarize model spend over a window: total cost, tokens and calls, broken down per model and per agent. |
| `llm_cost_top_persons` | `llm_cost` | `mcp:read` + `llm:read` | Rank the people accounting for the most model spend over a window, with each one's cost, tokens and call count. |
| `get_notification_delivery` | `notifications` | `mcp:read` + `channels:read` | Inspect one delivery receipt in full: every attempt and its timing, the retry schedule, the provider correlation ids and the last error. |
| `list_notification_deliveries` | `notifications` | `mcp:read` + `channels:read` | List one project's alert and incident delivery receipts with their status, retry state and provider correlation ids, optionally filtered by alert, incident or channel. |
| `get_oncall_schedule` | `oncall` | `mcp:read` + `members:read` + `oncall:read` + `projects:read` | Get one on-call schedule with its ordered rotation layers, their restrictions and every override recorded against it. |
| `list_contact_methods` | `oncall` | `mcp:read` + `oncall:read` | List your own paging contact methods with their transport, address, verification state, contact order and identifier. |
| `list_oncall_schedules` | `oncall` | `mcp:read` + `members:read` + `oncall:read` + `projects:read` | List one project's on-call schedules with their active state, time zone and number of rotation layers. |
| `resolve_oncall` | `oncall` | `mcp:read` + `members:read` + `oncall:read` + `projects:read` | Answer who is on call for one schedule at a given instant, and explain whether an override or a specific rotation layer selected them. |
| `compare_issue_customers` | `persons` | `mcp:read` + `analytics:read` + `errors:read` + `persons:read` | Compare affected customers with explicit-success controls in one bounded window. Association, not causation; missing values and partial counts are explicit. |
| `customer_recovery` | `persons` | `mcp:read` + `analytics:read` + `errors:read` + `persons:read` | Observe explicit workflow success and subsequent issue failures for a bounded live customer cohort; requires errors:read and analytics:read in addition to persons:read. |
| `get_friction_signals` | `persons` | `mcp:read` + `analytics:read` + `persons:read` | Read opt-in click friction with person, operation and replay references in an explicit bounded window. Observations do not prove frustration or churn. |
| `get_recovery_watch` | `persons` | `mcp:read` + `analytics:read` + `errors:read` + `persons:read` | Recheck a frozen recovery baseline under current permissions, retention and erasure. |
| `get_release_impact` | `persons` | `mcp:read` + `analytics:read` + `errors:read` + `persons:read` + `releases:read` | Compare release customer impact across explicit windows: failures, accounts, operation outcomes, friction and operation-matched recovery. Bounded evidence, not causation. |
| `list_recovery_watches` | `persons` | `mcp:read` + `analytics:read` + `errors:read` + `persons:read` | List durable recovery definitions and background observation timestamps; no cached customer evidence. |
| `preview_identity_correction` | `persons` | `mcp:read` + `persons:read` | Inspect recent alias mapping history and preview separation with a revision; existing properties stay on the original person. |
| `list_projects` | `projects` | `mcp:read` + `projects:read` | List the projects visible to the credential with each project's id, name, slug, active state and retention period. |
| `verify_receipt_chain` | `receipt_chains` | `mcp:read` + `agents:read` | Verify that this project's action receipt chain is intact — digests, links and sequence — reporting the entry count split into platform-attested and agent-reported, and the head digest to compare against a checkpoint retained outside Anectico. |
| `get_replay_highlights` | `replay` | `mcp:read` + `replay:content:read` | Read event-based replay highlights with timestamps and issue/trace references under current recording retention. |
| `get_saved_search` | `saved_searches` | `mcp:read` + `saved_search:read` | Get one visible saved search with its full filter query and the current version an update has to quote. |
| `list_saved_searches` | `saved_searches` | `mcp:read` + `saved_search:read` | List the saved searches visible to the caller for one signal — their own and the ones shared in the project — with each one's owner and version. |
| `get_onboarding_setup` | `settings` | `mcp:read` + `settings:read` | Read the bounded first-application setup draft for one project. Saved test identifiers and setup choices are not proof of successful instrumentation; verify with instrumentation_doctor. |
| `list_configurations` | `settings` | `mcp:read` + `settings:read` | List the organization's configuration entries by key, category and scope, with each entry's identifier. The stored values are not returned. |
| `get_ticket` | `tickets` | `mcp:read` + `connections:read` + `errors:read` + `tickets:read` | Get one external ticket link with the connection it is pinned to, its external status and its synchronization state. |
| `list_tickets_for_issue` | `tickets` | `mcp:read` + `connections:read` + `errors:read` + `tickets:read` | List the external tickets linked to one error issue, with each link's provider, external status and synchronization state. |
| `get_org_usage` | `usage` | `mcp:read` + `usage:read` | Read the organization's plan, retention, quota posture and full event, metric-series and replay-session meters for a billing month. |

### Promoted write tools

The daily-driver mutations, registered as their own tools so a host can tell a benign acknowledgement from a destructive delete.

**Safety** is the blast radius. *Destructive* destroys data or access you cannot restore with the same key — which includes replacing a value your key may write but may not read, because there is then nothing left to restore it from; *reversible* changes only state you can change back. *Leaves Anectico* means the call causes something outside your organization — a message delivered, an email sent, an issue opened or closed in a connected tracker — that undoing the Anectico-side record does not take back; a capability can be both. *Previews first* means the first call applies nothing and returns a preview plus a `confirm_token` — repeat the identical call with that token to apply it.

**Retry** is what happens if you make the SAME call a second time — the question that matters when a response never arrives and you cannot tell whether the first call landed. *Safe to retry* means the second call leaves the same end state, so you may repeat it freely. *Retry duplicates* means a second call commits a second effect — another record, another message — so send an `idempotency_key` with the first call instead of repeating it blind. *Retry refused* means the second call is rejected rather than applied: nothing is duplicated, but repeating the identical call cannot succeed, so read the object back and decide again. Every write action accepts an optional `idempotency_key`: reusing the same key with the same arguments replays the first result instead of running the action again.

| Tool | Area | Required scopes | Safety | Retry | What it does |
| --- | --- | --- | --- | --- | --- |
| `acknowledge_alert` | `alerts` | `mcp:write` + `alerts:acknowledge` | Destructive · previews first | Safe to retry | Acknowledge a firing alert, recording that a responder has taken it, after a preview and confirmation. |
| `resolve_alert` | `alerts` | `mcp:write` + `alerts:resolve` | Destructive · previews first | Retry refused | Resolve a firing alert with an optional resolution note, marking the underlying condition handled. |
| `set_issue_status` | `errors` | `mcp:write` + `errors:write` | Destructive · leaves Anectico · previews first | Retry refused | Resolve, ignore, unresolve or assign an error issue at the exact version the caller read, with an optional note, after a preview and confirmation. Assigning to a person additionally requires `members:read`; every other action does not. A later call reverses the status only — the resolution note, resolver, release baseline and regression state are not restored. |
| `snooze_issue` | `errors` | `mcp:write` + `errors:write` | Destructive · previews first | Retry refused | Snooze an error issue until a condition trips — a timestamp, a count of new occurrences or newly affected people, escalation, or indefinitely — after a preview and confirmation. Snoozing an already-snoozed issue restarts its window and counters. |
| `comment_incident` | `incidents` | `mcp:write` + `incidents:respond` | Reversible | Safe to retry | Append a comment to an incident's timeline at the version the caller read, with a required retry key so a repeat appends exactly once. |
| `create_incident` | `incidents` | `mcp:write` + `incidents:write` | Reversible · leaves Anectico · previews first | Retry duplicates | Open a new incident with a title, description and severity, after a preview and confirmation. Opening one notifies every enabled channel, and those messages cannot be recalled. |

### Write actions

Found through `list_write_actions` and run with ONE of two doors, chosen by how far the action reaches: `execute_internal_action` for an action whose effect stops inside your organization, `execute_external_action` for one that also causes something Anectico cannot retract. Each action's `execute_with` names its door, and calling the other one is refused. The per-action scope and the confirmation rules are the same as a promoted tool's.

| Action | Area | Required scopes | Safety | Retry | What it does |
| --- | --- | --- | --- | --- | --- |
| `create_silence` | `alerts` | `mcp:write` + `silences:write` | Destructive · previews first | Retry duplicates | Silence the alerts matching a set of label matchers for a bounded window, after a preview and confirmation, so they stop notifying until it ends. Pages suppressed while it is active are not delivered later, even if the silence is removed. |
| `delete_alert_rule` | `alerts` | `mcp:write` + `alerts:rules:delete` | Destructive · previews first | Safe to retry | Delete an alert rule after a preview and confirmation, so it stops evaluating and firing. |
| `delete_silence` | `alerts` | `mcp:write` + `silences:delete` + `silences:read` | Destructive · previews first | Safe to retry | Remove a silence after a preview and confirmation, so the alerts it was suppressing can fire again. |
| `cancel_analytics_result` | `analytics` | `mcp:write` + `analytics:query` + `analytics:read` + `persons:read` | Destructive · previews first | Safe to retry | Stop a product-analytics execution that is still pending or running, and report the status that stands afterwards. The first call previews what would stop and returns a confirm_token; call again with the same arguments plus that token to apply. Stopping is permanent — a stopped execution publishes no result and cannot be resumed. An execution that already reached a terminal status keeps it: the call reports that status rather than rewriting it, so stopping a result that is already ready, failed or stopped changes nothing. |
| `create_cohort` | `analytics` | `mcp:write` + `cohorts:write` | Reversible | Retry refused | Create a person cohort — behavioral, property-based or a static member list — and report how many supplied identities resolved to people. |
| `delete_cohort` | `analytics` | `mcp:write` + `analytics:read` + `cohorts:delete` | Destructive · previews first | Safe to retry | Delete a cohort after a preview and confirmation. This cannot be undone. |
| `refresh_cohort` | `analytics` | `mcp:write` + `cohorts:write` | Reversible | Retry duplicates | Recompute a cohort's membership now rather than waiting for its next scheduled refresh. Incomplete canonical identity evidence refuses the refresh and preserves the previous generation; retry after identity processing recovers. |
| `replace_static_cohort_members` | `analytics` | `mcp:write` + `cohorts:write` | Destructive · previews first | Retry refused | Replace a static cohort's entire membership at the exact generation the caller read, after a preview and confirmation; an empty list clears it. |
| `create_notification_channel` | `channels` | `mcp:write` + `channels:write` | Reversible | Retry duplicates | Create an organization-wide notification channel — email, chat, pager or webhook — that alerts and incidents can be delivered to. |
| `delete_notification_channel` | `channels` | `mcp:write` + `channels:delete` | Destructive · previews first | Safe to retry | Delete a notification channel after a preview and confirmation, so alerts routed to it stop delivering. This cannot be undone. |
| `test_notification_channel` | `channels` | `mcp:write` + `channels:write` | Reversible · leaves Anectico · previews first | Retry duplicates | Send a real test message through a stored notification channel, after a preview and confirmation, to verify its delivery configuration. |
| `update_notification_channel` | `channels` | `mcp:write` + `channels:write` | Destructive · previews first | Safe to retry | Replace a notification channel's name, transport, delivery configuration and enabled state, after a preview and confirmation; the configuration sent replaces the stored one entirely, so omitting it clears the delivery target. |
| `create_analytics_audience` | `cohort` | `mcp:write` + `analytics:read` + `cohorts:write` + `mcp:read` + `persons:read` | Reversible · previews first | Safe to retry | Preview and create a derived person audience from a complete result selection. Confirmation and stable UUID key required; replacement uses exact generation CAS. Current inherited source permissions apply. Reuse is supported in product queries and exact-generation flag conditions; members support external-agent investigation. Generic cohort editors and mirrors remain separate. |
| `replace_analytics_audience` | `cohort` | `mcp:write` + `analytics:read` + `cohorts:write` + `mcp:read` + `persons:read` | Destructive · previews first | Safe to retry | Preview and replace a derived person audience from a complete result selection. Confirmation and stable UUID key required; replacement uses exact generation CAS. Current inherited source permissions apply. Reuse is supported in product queries and exact-generation flag conditions; members support external-agent investigation. Generic cohort editors and mirrors remain separate. |
| `create_connection` | `connections` | `mcp:write` + `connections:write` | Reversible | Retry refused | Store a third-party connection — an API token, webhook secret or basic credential — in the organization's vault, encrypted and never returned. |
| `delete_connection` | `connections` | `mcp:write` + `connections:delete` | Destructive · previews first | Safe to retry | Delete a stored connection and its credential after a preview and confirmation, breaking anything that delivers through it. This cannot be undone. |
| `update_connection` | `connections` | `mcp:write` + `connections:write` | Destructive · previews first | Retry refused | Change a stored connection's label, status, non-secret configuration, or rotate its credential, after a preview and confirmation; anything left out is unchanged, the secret is never returned, and a rotated credential replaces one that cannot be recovered. |
| `add_widget` | `dashboard` | `mcp:write` + `dashboard:write` | Reversible | Retry refused | Add a chart to a dashboard at the exact version the caller read, described by structured query targets, expressions and display settings. Native saved_insight uses an exact decimal-string recipe revision, requires insights:read, accepts no query/display overrides and waits for dependency confirmation before execution. |
| `clone_dashboard` | `dashboard` | `mcp:write` + `dashboard:write` | Reversible | Retry duplicates | Copy an existing dashboard, with all of its widgets, into a new dashboard owned by the caller. |
| `create_dashboard` | `dashboard` | `mcp:write` + `dashboard:write` | Reversible | Retry duplicates | Create an empty dashboard in a project, owned by the caller, with its optional tags and dashboard variables. |
| `delete_dashboard` | `dashboard` | `mcp:write` + `dashboard:delete` + `dashboard:read` | Destructive · previews first | Retry refused | Delete a dashboard at the exact version the caller read, after a preview and confirmation. This cannot be undone. |
| `delete_widget` | `dashboard` | `mcp:write` + `dashboard:delete` + `dashboard:read` | Destructive · previews first | Retry refused | Remove a widget from a dashboard at the exact version the caller read, after a preview and confirmation. This cannot be undone. |
| `update_dashboard` | `dashboard` | `mcp:write` + `dashboard:write` | Destructive · previews first | Retry refused | Replace a dashboard's name, description, tags and variables at the exact version the caller read, after a preview and confirmation; its widgets are untouched. |
| `update_widget` | `dashboard` | `mcp:write` + `dashboard:write` | Destructive · previews first | Retry refused | Replace a widget's type, title, structured query and display settings at the exact dashboard version the caller read, after a preview and confirmation. A new saved_insight pin requires insights:read and preserves the recipe's native result and window. |
| `create_recovery_watch` | `errors` | `mcp:write` + `analytics:read` + `errors:read` + `errors:write` + `persons:read` | Reversible · previews first | Safe to retry | Save a bounded recovery watch with a caller-owned UUID and fixed baseline references; confirmation required. |
| `delete_problem_report` | `errors` | `mcp:write` + `errors:delete` | Destructive · previews first | Safe to retry | Delete one problem report. Replay screenshots remain governed by the recording's separate deletion control; confirmation required. |
| `delete_recovery_watch` | `errors` | `mcp:write` + `analytics:read` + `errors:read` + `errors:write` + `persons:read` | Destructive · previews first | Safe to retry | Permanently delete a recovery definition and its frozen baseline references; confirmation required. |
| `merge_issues` | `errors` | `mcp:write` + `errors:write` | Destructive · leaves Anectico · previews first | Retry duplicates | Merge one or more source error issues into a canonical issue after a preview and confirmation, hiding the sources and attributing their events to the survivor. |
| `submit_problem_report` | `errors` | `mcp:write` + `ingest:write` | Reversible · previews first | Safe to retry | Submit an explicit problem report with a stable UUID, bounded description and correlation context. Ingest scope grants no report reads; confirmation required. |
| `unmerge_issue` | `errors` | `mcp:write` + `errors:write` | Destructive · previews first | Safe to retry | Split a previously merged error issue back out into its own standalone issue, after a preview and confirmation. |
| `create_escalation_policy` | `escalation` | `mcp:write` + `escalation:write` | Reversible | Retry refused | Create an escalation policy: ordered levels that notify channels, users and on-call schedules after their delays, with optional severity and label matching. |
| `delete_escalation_policy` | `escalation` | `mcp:write` + `escalation:delete` | Destructive · previews first | Safe to retry | Delete an escalation policy after a preview and confirmation, so alerts stop escalating through it. This cannot be undone. |
| `update_escalation_policy` | `escalation` | `mcp:write` + `escalation:read` + `escalation:write` | Reversible · previews first | Safe to retry | Replace an escalation policy's definition — matching, repeat behavior, active state and its complete ordered level set — after a preview and confirmation. A level left out is deleted; a name or description left out keeps the stored value. |
| `create_release_gate` | `evaluation` | `mcp:write` + `evals:write` | Destructive · previews first | Retry refused | Declare one immutable release gate under a caller-supplied gate id. A retry conflicts on that id; there is no delete, void, or correction path. |
| `evaluate_release_gate` | `evaluation` | `mcp:write` + `evals:write` | Destructive · previews first | Safe to retry | Permanently decide one release gate. Reusing its required idempotency key returns the existing evidence snapshot; use a new key to evaluate newly arrived evidence. |
| `submit_annotation` | `evaluation` | `mcp:write` + `scores:write` | Destructive · previews first | Safe to retry | Record or edit your own human quality judgment of one agent run — a metric name, an optional number, an optional label and a rationale — attributed to the calling user, after a preview and confirmation. Re-judging the same run and metric replaces your previous judgment and nobody else's. |
| `cancel_export_job` | `export` | `mcp:write` + `export:write` | Destructive · previews first | Retry refused | Cancel a pending, running or retrying export job after a preview and confirmation. A canceled job cannot be resumed. |
| `create_analytics_export` | `export` | `mcp:write` + `analytics:read` + `export:write` + `persons:read` | Reversible · previews first | Safe to retry | Preview and enqueue a frozen analytics measurement or full participant selection as CSV, JSON or Parquet. Confirmation and stable idempotency key required; current source authority and expiry apply. Poll the export job before downloading. |
| `create_export_job` | `export` | `mcp:write` + `export:write` | Reversible | Safe to retry | Enqueue a durable export of one signal — logs, traces, metrics, errors or unified search — over a window and filter set, returning the job id to poll. |
| `export_logs` | `export` | `mcp:write` + `export:write` | Reversible | Safe to retry | Enqueue a durable logs export with a standard column set, narrowed by service, level, environment, people or free-text search. |
| `retry_export_job` | `export` | `mcp:write` + `export:write` | Destructive · previews first | Retry refused | Re-run a permanently failed export job with its original, unchangeable scope, query, columns and format, after a preview and confirmation. The recorded failure reason, progress and timings are cleared and cannot be recovered. |
| `create_flag` | `flags` | `mcp:write` + `flags:write` | Reversible | Retry refused | Create a feature flag — boolean or multivariate — with its fallback decision, variants and targeting rules, optionally active immediately. |
| `delete_flag` | `flags` | `mcp:write` + `flags:delete` | Destructive · previews first | Safe to retry | Delete a feature flag after a preview and confirmation. This cannot be undone. |
| `set_flag_active` | `flags` | `mcp:write` + `flags:write` | Destructive · previews first | Safe to retry | Turn a feature flag on or off after a preview and confirmation, leaving its variants and targeting rules untouched. |
| `update_flag` | `flags` | `mcp:write` + `flags:write` | Destructive · previews first | Safe to retry | Replace a feature flag's complete definition after a preview and confirmation; anything left out is cleared rather than preserved. |
| `delete_incident` | `incidents` | `mcp:write` + `incidents:delete` | Destructive · previews first | Safe to retry | Delete an incident and its entire timeline after a preview and confirmation. This cannot be undone. |
| `set_incident_status` | `incidents` | `mcp:write` + `incidents:respond` | Destructive · leaves Anectico · previews first | Safe to retry | Acknowledge, resolve or reopen an incident at the exact version the caller read, after a preview and confirmation, with a required retry key so a repeat applies once. |
| `update_incident` | `incidents` | `mcp:write` + `incidents:write` | Destructive · previews first | Retry refused | Change an incident's title, description or severity after a preview and confirmation; fields left out keep their current values. |
| `cancel_investigation` | `investigations` | `mcp:write` + `investigations:run` | Destructive · previews first | Safe to retry | Stop a running investigation, settling it and its in-flight turn and returning the unused allowance. The first call previews what would stop and returns a confirm_token; call again with that token to apply. Already-canceled is answered the same way as the first cancellation; an investigation that has finished or failed cannot be stopped, and a stopped one can never be continued. |
| `continue_investigation` | `investigations` | `mcp:write` + `investigations:run` | Reversible | Retry duplicates | Ask a follow-up question in an existing investigation, answered with the earlier turns in context and with freshly assembled evidence. It returns the new turn's id once the turn is durable; read the answer with get_investigation. A follow-up cannot be asked while the previous turn is still running, and never in a canceled investigation. |
| `create_invitation` | `invitations` | `mcp:write` + `members:write` | Reversible · leaves Anectico · previews first | Retry refused | Invite someone into the organization by email address with the role they will hold once they accept, after a preview and confirmation. The invitation email cannot be recalled once sent. |
| `revoke_invitation` | `invitations` | `mcp:write` + `members:write` | Destructive · previews first | Safe to retry | Revoke a pending invitation after a preview and confirmation, so it can no longer be accepted. |
| `delete_log` | `logs` | `mcp:write` + `logs:delete` | Destructive · previews first | Safe to retry | Permanently delete one exact log record from the project the calling credential is signed for, after a preview and confirmation. Its correlated trace is kept. |
| `remove_member` | `members` | `mcp:write` + `members:write` | Destructive · previews first | Safe to retry | Remove a member from the organization after a preview and confirmation, revoking their access, and wait until the roster reflects it. |
| `update_member_role` | `members` | `mcp:write` + `members:write` | Destructive · previews first | Retry duplicates | Change an organization member's role, and with it every capability their credentials are minted with, after a preview and confirmation. |
| `create_metric_watch` | `metric_watch` | `mcp:write` + `alerts:rules:read` + `alerts:rules:write` + `mcp:read` | Reversible · previews first | Retry duplicates | Preview and create a project metric watch with confirmation. Create starts paused; updates, pauses and resumes compare exact versions. Delete selects an identity, not a revision. Source validation does not compute a scalar or prove delivery. Create has no durable backend replay key; reconcile ambiguous outcomes before another approval. |
| `delete_metric_watch` | `metric_watch` | `mcp:write` + `alerts:rules:delete` + `alerts:rules:read` + `mcp:read` | Destructive · previews first | Retry refused | Preview and delete a project metric watch with confirmation. Create starts paused; updates, pauses and resumes compare exact versions. Delete selects an identity, not a revision. Source validation does not compute a scalar or prove delivery. Create has no durable backend replay key; reconcile ambiguous outcomes before another approval. |
| `pause_metric_watch` | `metric_watch` | `mcp:write` + `alerts:rules:read` + `alerts:rules:write` + `mcp:read` | Destructive · previews first | Retry refused | Preview and pause a project metric watch with confirmation. Create starts paused; updates, pauses and resumes compare exact versions. Delete selects an identity, not a revision. Source validation does not compute a scalar or prove delivery. Create has no durable backend replay key; reconcile ambiguous outcomes before another approval. |
| `resume_metric_watch` | `metric_watch` | `mcp:write` + `alerts:rules:read` + `alerts:rules:write` + `mcp:read` | Destructive · leaves Anectico · previews first | Retry refused | Preview and resume a project metric watch with confirmation. Create starts paused; updates, pauses and resumes compare exact versions. Delete selects an identity, not a revision. Source validation does not compute a scalar or prove delivery. Create has no durable backend replay key; reconcile ambiguous outcomes before another approval. |
| `update_metric_watch` | `metric_watch` | `mcp:write` + `alerts:rules:read` + `alerts:rules:write` + `mcp:read` | Destructive · leaves Anectico · previews first | Retry refused | Preview and update a project metric watch with confirmation. Create starts paused; updates, pauses and resumes compare exact versions. Delete selects an identity, not a revision. Source validation does not compute a scalar or prove delivery. Create has no durable backend replay key; reconcile ambiguous outcomes before another approval. |
| `create_contact_method` | `oncall` | `mcp:write` + `oncall:contacts:write` | Reversible | Retry refused | Add a contact method — email, SMS, chat DM — for a user so escalations can reach them, with a rank deciding which is tried first. |
| `create_oncall_override` | `oncall` | `mcp:write` + `members:read` + `oncall:write` + `projects:read` | Reversible | Retry refused | Put a specific user on call for a schedule over a fixed window, taking precedence over the rotation for that window. |
| `create_oncall_schedule` | `oncall` | `mcp:write` + `members:read` + `oncall:write` + `projects:read` | Reversible | Retry refused | Create an on-call schedule with its ordered rotation layers, their rotation length and any on-call-window restrictions. |
| `delete_contact_method` | `oncall` | `mcp:write` + `oncall:contacts:write` | Destructive · previews first | Safe to retry | Delete a contact method after a preview and confirmation, so escalations stop delivering to it. |
| `delete_oncall_override` | `oncall` | `mcp:write` + `oncall:delete` | Destructive · previews first | Safe to retry | Delete an on-call override after a preview and confirmation, restoring the normal rotation for its window. |
| `delete_oncall_schedule` | `oncall` | `mcp:write` + `oncall:delete` | Destructive · previews first | Safe to retry | Delete an on-call schedule and its overrides after a preview and confirmation. This cannot be undone. |
| `update_contact_method` | `oncall` | `mcp:write` + `oncall:contacts:write` + `oncall:read` | Reversible · previews first | Safe to retry | Update a contact method's transport, address, label and rank, after a preview and confirmation; a transport, address or label left out keeps its stored value. |
| `update_oncall_schedule` | `oncall` | `mcp:write` + `members:read` + `oncall:write` + `projects:read` | Destructive · previews first | Safe to retry | Replace an on-call schedule's definition — name, description, time zone, active state and its complete ordered layer set — after a preview and confirmation. A layer left out is deleted, and with it whoever it rotated on call. |
| `correct_identity` | `persons` | `mcp:write` + `persons:correct` | Destructive · previews first | Retry refused | Separate an alias into a new merge-protected person after preview and confirmation, recording the operator and reason. A stale revision conflicts. |
| `create_project` | `projects` | `mcp:write` + `projects:write` | Reversible | Retry refused | Create a project in the organization with a name, slug and ingest sampling rate; its retention follows the organization's plan rather than being set here. Retry temporary service unavailability; after a timeout, check the project list before retrying the same slug. |
| `update_project` | `projects` | `mcp:write` + `projects:write` | Destructive · previews first | Safe to retry | Change a project's name, description or ingest sampling rate after a preview and confirmation; fields left out keep their current values. |
| `upsert_release` | `releases` | `mcp:write` + `releases:write` | Destructive · previews first | Safe to retry | Register or update a release for regression tracking, with its deploy time, commit, ref, author and a link to the deploy, after a preview and confirmation. Any of those details you leave out is cleared rather than kept. |
| `create_saved_insight` | `saved_insight` | `mcp:write` + `insights:read` + `insights:write` + `mcp:read` | Reversible · previews first | Safe to retry | Preview and create a project saved-insight recipe with exact revision checks and durable UUID idempotency; confirmation required. Does not execute telemetry. Retirement permanently hides all revisions and is blocked by active dependents. |
| `delete_saved_insight` | `saved_insight` | `mcp:write` + `insights:delete` + `insights:read` + `mcp:read` | Destructive · previews first | Safe to retry | Preview and delete a project saved-insight recipe with exact revision checks and durable UUID idempotency; confirmation required. Does not execute telemetry. Retirement permanently hides all revisions and is blocked by active dependents. |
| `update_saved_insight` | `saved_insight` | `mcp:write` + `insights:read` + `insights:write` + `mcp:read` | Reversible · previews first | Safe to retry | Preview and update a project saved-insight recipe with exact revision checks and durable UUID idempotency; confirmation required. Does not execute telemetry. Retirement permanently hides all revisions and is blocked by active dependents. |
| `create_saved_search` | `saved_search` | `mcp:write` + `saved_search:write` | Reversible | Safe to retry | Save a reusable filter set for one signal page, owned by the caller and optionally shared with the whole project. |
| `delete_saved_search` | `saved_search` | `mcp:write` + `saved_search:delete` + `saved_search:read` | Destructive · previews first | Retry refused | Delete a saved search the caller owns, at the exact version they read, after a preview and confirmation. This cannot be undone. |
| `duplicate_saved_search` | `saved_search` | `mcp:write` + `saved_search:write` | Reversible | Safe to retry | Copy any saved search visible to the caller into a private one they own, at the exact source version they read. |
| `update_saved_search` | `saved_search` | `mcp:write` + `saved_search:write` | Destructive · previews first | Retry refused | Change a saved search's name, stored filter set or project sharing at the exact version the caller read, after a preview and confirmation; a supplied filter set replaces the stored one entirely. |
| `cancel_diagnostic_capture` | `settings` | `mcp:write` + `persons:read` + `settings:write` | Destructive · previews first | Safe to retry | Stop new diagnostic allocations; existing acknowledged grants expire within 30 seconds. Confirmation required. |
| `create_diagnostic_capture` | `settings` | `mcp:write` + `persons:read` + `settings:write` | Reversible · previews first | Safe to retry | Request opt-in diagnostic sampling for one identifier and environment with a finite budget and expiry. Caller-owned UUID; confirmation required. |
| `delete_configuration` | `settings` | `mcp:write` + `settings:delete` | Destructive · previews first | Safe to retry | Delete one configuration entry by id after a preview and confirmation. This cannot be undone. |
| `delete_llm_pricing` | `settings` | `mcp:write` + `settings:delete` | Destructive · previews first | Safe to retry | Remove the organization's price override for one model after a preview and confirmation, returning its cost attribution to the platform default. |
| `set_configuration` | `settings` | `mcp:write` + `settings:write` | Destructive · previews first | Safe to retry | Set an organization-level configuration value, or a project-level one when a project is named, to any JSON value, after a preview and confirmation. The value replaces the stored one entirely rather than merging into it. config_type may be retention, sampling, alert, dashboard, general, notification, or integration; empty defaults to general and any other value is rejected. |
| `set_github_config` | `settings` | `mcp:write` + `github_config:write` | Destructive · previews first | Safe to retry | Point the organization at the source repository used to suggest which commits likely caused an error, and enable or disable that resolution, after a preview and confirmation. A source-root prefix left out is cleared. |
| `upsert_llm_pricing` | `settings` | `mcp:write` + `settings:write` | Destructive · previews first | Safe to retry | Set the organization's own per-token prices for one model — input, output and cache reads and writes — overriding the default used for cost attribution, after a preview and confirmation. All four prices are replaced together, so one left out is set to zero. |
| `create_ticket` | `tickets` | `mcp:write` + `connections:read` + `errors:read` + `tickets:write` | Reversible · leaves Anectico · previews first | Safe to retry | File a real ticket in a connected issue tracker for an error issue and link it back, after a preview and confirmation. |
| `unlink_ticket` | `tickets` | `mcp:write` + `tickets:delete` | Destructive · previews first | Safe to retry | Remove the link between an error issue and its external ticket after a preview and confirmation; the external ticket itself is left in place. |
| `delete_trace` | `traces` | `mcp:write` + `traces:delete` | Destructive · previews first | Safe to retry | Permanently delete every span of one exact trace from the project the calling credential is signed for, after a preview and confirmation. Correlated logs are kept. |
| `create_tracking_plan` | `tracking_plan` | `mcp:write` + `mcp:read` + `tracking_plans:read` + `tracking_plans:write` | Reversible · previews first | Safe to retry | Validate, preview and create a versioned tracking plan with exact revision and durable UUID idempotency; confirmation required. No SDK deployment or capture rejection. Sensitive declarations survive edits/deletion. |
| `delete_tracking_plan` | `tracking_plan` | `mcp:write` + `mcp:read` + `tracking_plans:delete` + `tracking_plans:read` | Destructive · previews first | Safe to retry | Validate, preview and delete a versioned tracking plan with exact revision and durable UUID idempotency; confirmation required. No SDK deployment or capture rejection. Sensitive declarations survive edits/deletion. |
| `update_tracking_plan` | `tracking_plan` | `mcp:write` + `mcp:read` + `tracking_plans:read` + `tracking_plans:write` | Reversible · previews first | Safe to retry | Validate, preview and update a versioned tracking plan with exact revision and durable UUID idempotency; confirmation required. No SDK deployment or capture rejection. Sensitive declarations survive edits/deletion. |

<!-- END GENERATED CAPABILITY REFERENCE. -->

## When a tool fails

A failed call returns an error result whose text always tells you two things: what went wrong, and
whether calling again can change the answer. That second part is the one worth coding against — an
agent that retries a permanent refusal loops, and an agent that gives up on a transient one loses an
answer it could have had.

There are two kinds of failure and they behave differently on purpose.

**Something about your call.** A wrong id, an argument the tool will not accept, a scope your key does
not carry, a conflicting write, a rate limit. The message names the problem and keeps the specific
detail — which field, which id, which limit — because that detail is how you correct the call. These
are the failures you can act on directly.

**Something on our side.** The message says an internal error occurred and that repeating the identical
call is unlikely to help; it deliberately carries no further detail. This is not an oversight and it is
not something a different argument will unlock: when the fault is ours, the specifics describe our
systems rather than your request, so they stay in our logs. Try a different tool or a narrower question,
and report it if it persists. Two failures worth distinguishing get their own wording: a temporary
unavailability or a timeout says to retry, and an operation that is simply not served says not to.

**An action that cannot be accounted for is not performed.** A mutation whose effect reaches outside
your organization, or that removes state your key cannot restore, is written into a tamper-evident
action log *before* it runs. On the rare occasion that record cannot be written, the call is refused
and nothing happens — the message says so and tells you to retry shortly. Treat it as transient: it
is a deliberate refusal rather than a failure of the action itself, and the retry runs the action
exactly once.

Those records name the rule they were decided under: every entry this surface writes — the
authorization, its outcome, and a refusal — carries `policy_id: mcp:write_gateway_authorization`
with its version, so a refused destructive call is readable as a decision rather than as a gap. Read
them through `GET /api/v1/action-receipts`.

Error text is bounded. Characters that a terminal or a transcript would read as formatting rather than
as content — escape sequences, line breaks, direction overrides, invisible characters — are replaced
with `�` before the message reaches you, and the message is capped in length. Nothing a tool
legitimately reports is affected by either. If you are building on this surface, treat the replacement
character in an error as a signal that the original text contained something that does not belong in a
one-line diagnostic.

### `search` reports each source separately

`search` fans your query out across several sources, and any one of them can fail while the others
answer. When that happens you still get a successful result: the sources that answered contribute
their hits, the result is marked `partial`, and the per-source report names the one that did not and
why. What is present is true; what is missing is known to be missing.

If **no** source answered, `search` fails rather than returning an empty result. The distinction
matters: "nothing matched your query" and "nothing ran" look identical if you only read the hit count,
and only one of them is worth retrying with a wider window.

## Read contract details

Entity results include dashboard links when there is a specific object to inspect.

### Reaching an administrative read

Call `list_read_actions` with no arguments to browse: it returns every read action your key can run,
grouped by domain, with a one-line summary each. Pass a `domain` (for example `oncall`, `tickets`,
`saved_searches`, `usage`, `llm_cost`, `accounts`, `definitions`, `notifications`, `docs`) or a free-text
`query` to drill in and get each matching action's full argument schema. Then call
`execute_read_action` with `action` set to the id and `arguments` set to an object matching that
schema.

Both tools are read-only and change nothing, so a host may run them without prompting. An action id
your key is not authorized for is refused with the same message an unknown id gets, and nothing
runs. The organization always comes from your API key and can never be supplied in `arguments`.

### Reading the documentation from the endpoint

`search_docs` and `get_doc` serve this documentation over the same connection, so an agent can look
up a scope name, an alert expression, a metric name or an SDK call instead of guessing one. Both are
read actions reached with `execute_read_action`, and both need `docs:read` — a scope every role
holds, and the only one on this surface that discloses nothing about your organization. The `search`
and `fetch` pair covers the same ground for a client that only knows those two: the source is `docs`
and the reference kind is `doc`.

`search_docs` takes a `query` and an optional `limit` (1–20, default 8). Every word in the query has
to appear somewhere in a page's title, description, section or body, and the ranking is the
published documentation site's own — the same words return the same page in both places. Each hit
carries the page's `slug`, `title`, `description`, `section`, public `url`, raw `markdown_url`, and a
stable `ref` that can be passed to `fetch`.

`get_doc` takes that `slug` and returns the page as markdown. Two things about the response are
worth planning for:

- **The whole page is capped at 48 KiB.** Two reference pages are well past that. When the cap
  applies, `truncated` is `true`, the markdown is an exact *prefix* of the real page (never a
  summary), ending at a complete line outside a fenced code block. The envelope records the cut.
- **`outline` is always the page's complete H2–H6 outline**, even when the markdown is one section
  or a truncated prefix. Every entry includes `heading`, `anchor`, `depth`, and the unambiguous
  `parent_anchor` when it is nested. Pass a heading or anchor back as `heading` to get exactly that
  nested section. Prefer the anchor when visible text repeats. A heading that is not on the page
  answers `not_found` *with the outline*, so the next call is informed rather than another guess.

The returned markdown body is byte-identical to the source body published at
`https://anectico.com/docs`; repository frontmatter is not included. Every hit and page carries its
public URL, so a citation remains checkable.

For retrieval without MCP, every page also has a raw Markdown address and the website publishes a
versioned page manifest. See [Machine-readable documentation](/docs/reference/machine-readable-docs).

### Investigations answer after the call returns

`investigate` and `continue_investigation` do not carry the answer. An investigation assembles
evidence across every signal and then narrates a grounded conclusion over it, which takes tens of
seconds, so both return as soon as the investigation is durable and give you an `investigation_id`
and a `turn_id`. Read the answer with `get_investigation`, polling while its `status` is `running`.
Nothing is lost by not waiting: the work continues whether or not you are still connected, and the
id is all you need to collect it — later, from another session, or from the dashboard.

Each completed turn's conclusion includes `evidence_disclosure.omissions`, with closed `source` and
`reason` enum strings, beside the human Markdown notices. Read this field instead of parsing prose
to decide whether evidence was omitted. `omissions: []` means disclosure was evaluated and nothing
was omitted; no `evidence_disclosure` property means the producer did not populate the contract and
must not be treated as complete. The reasons distinguish a missing permission, a project-policy
refusal, an unavailable read, and evidence omitted by the input limit.

Two shortcuts are worth knowing. `investigate` returns `cached: true` when an identical
investigation has already been answered: no model call was made, nothing was charged, and one
`get_investigation` returns the stored answer. And the `impact` it returns — how many people are
affected and which accounts most — is computed exactly, not written by the model, and arrives with
the id rather than with the conclusion, so you can act on the blast radius immediately.

Each investigation draws down your organization's monthly investigation allowance and makes a paid
model call, so prefer one specific question over several broad ones. A follow-up cannot be asked
while the previous turn is still running. Stopping an investigation with `cancel_investigation`
returns the unused allowance and is permanent: a stopped investigation can never be continued, so
start a new one on the same subject instead.

Turn content — the conclusion and its citations — is your own captured data narrated back to you.
It arrives marked as untrusted content, and an agent should treat it as evidence to reason about
rather than as instructions to follow.

### Bounded service-health waits

`get_service_health` normally returns the same immediate all-service snapshot or service RED series as
before. For a cancelable health-state watch, add `wait_seconds` from 5 through 60 and optionally
`poll_interval_ms` from 1000 through 5000 (default 1000). Wait mode takes a real service-health baseline,
emits the standard MCP progress notification `service-health-wait-armed`, and then polls only for a
change in the selected service's health state—or any service when `service` is omitted. The progress
notification echoes the client's MCP progress token, so clients must supply a bounded string progress
token before using wait mode.

A state change returns the current truthful snapshot immediately. Reaching the deadline returns a
normal result that explicitly says no health-state change was observed within the requested duration.
The highest-cost supported call, 60 seconds at a one-second cadence, is one baseline read plus at most
60 further reads; it remains a single rate-limited MCP request and never mutates telemetry or
configuration.

**Cancellation depends on your protocol revision.** On `2026-07-28`, cancelling the request stops the
wait and the lookup it is in the middle of. On the earlier revisions there is no request-cancellation
signal to act on, so disconnecting ends your side of the exchange and leaves the wait to reach its own
deadline. Either way it is bounded by `wait_seconds`, which is why the ceiling is 60.

Waits are admitted rather than queued: each API key may hold at most **two** concurrently, and the
endpoint admits at most **64** at a time overall. Ordinary immediate `get_service_health` reads
consume neither. A key at its limit, or an endpoint at its limit, gets a definite error before any
health lookup runs, and can retry once another wait exits. Treat the 64 as an availability property
rather than a promise about a single number — the request-rate limit that applies to every call also
bounds how fast waits can be started.

Agent-run list and detail reads always resolve to one project. Supply `project_id` when using an
organization-level credential. A project-scoped key may omit it; if it supplies another value,
Anectico ignores that value and keeps the read pinned to the key's signed project. Omitted scope from an
organization-level key fails before a query runs, and foreign or random project/run identifiers do
not reveal whether the target exists.

`get_incident` returns one incident's whole case file — current version, ordered timeline, immutable
evidence, linked signals and delivery receipts — as a single all-or-error result: you get the
complete picture or an error, never a partial one. `list_oncall_schedules`, `get_oncall_schedule`, and
`resolve_oncall` are read actions reached through `execute_read_action` and require `oncall:read`.
`resolve_oncall` answers with who is on call right now and explains why — which override or rotation
layer produced that answer.
`create_contact_method`, `update_contact_method`, and `delete_contact_method` require
`oncall:contacts:write` — not the schedule-administration scopes — and only ever affect the contact
methods of the member the key acts as.
`list_notification_deliveries` and `get_notification_delivery` are read actions reached through
`execute_read_action`; they require `channels:read`, support
project-pinned receipt inspection and opaque pagination, and never render stored notification
payloads or credential secrets.

`get_org_usage` is a read action reached through `execute_read_action`, listed only when the key has
both `mcp:read` and `usage:read`. Omit `period` for
the current UTC billing month or supply one exact `YYYY-MM` value. The organization is always taken
from the authenticated key; the action has no organization argument. It returns the same plan tier,
retention window, OK/WARN/DEGRADE posture, pooled events and error breakdown, active metric-series
meter, replay-session meter, and computation time exposed by the dashboard, REST API, and CLI. A new
organization with no computed snapshot returns a normal empty-state message rather than invented
zero usage.

`list_tickets_for_issue` and `get_ticket` are read actions reached through `execute_read_action` and
require `tickets:read`. They are pinned to one effective
project and expose the provider link, pinned `connection_id`, current external status, sync state,
attempt count, last sync time, and safe retry error without exposing credentials. `create_ticket`
requires an absolute `issue_url` and a stable `idempotency_key`; retries must reuse that key only
for the exact same request.

Filing a ticket touches a system outside Anectico, so `create_ticket` has one outcome that is neither
success nor failure: the ticket was created in your tracker and Anectico could not record the link.
It reports this as *already exists*, and the message names the provider ticket id, its URL, and the
one safe next step — **retry with the same `idempotency_key`**, which adopts the existing ticket
rather than filing a second one. Never mint a new key in response to it, and never treat it as a
create that did not happen. Anectico will never report a ticket it created as a call that had no
effect.

There is a second outcome in the same family: your tracker accepted the request but never returned a
usable answer, so nobody — including Anectico — knows yet whether a ticket exists. This is reported
as *unavailable*, with the same remedy: retry with the same `idempotency_key`. Anectico briefly holds
the request while your tracker's own search catches up, so a retry during that window is answered
"already in progress" rather than filing a second ticket; keep retrying the unchanged call with the
same key and it resolves to the ticket that exists, or files one if none does. A request your tracker
explicitly *rejected* is a *failed precondition* and is not held — nothing was filed, so repair the
authorization, permissions or target before sending it again. Repeating it unchanged cannot help.

A create that already reached your tracker stays bound to the connection and destination it reached,
so a retry goes there and nowhere else — a connection that has since become the active one for that
provider is not substituted. If that destination is gone or has been repointed, the retry is refused
as a *failed precondition* naming the destination it is waiting for. Do not mint a new key in
response: a ticket may already exist where the first attempt went. Restore the connection to that
target and retry with the same key.

`idempotency_key` is scoped to one project. The same key used in two projects is two separate
creates and files two tickets, which is what you want: an issue in one project is not an issue in
another.

Organization-level credentials must supply `project_id`.
Project-scoped credentials may omit it or repeat their exact signed project; any explicit different
value receives the same generic not-found denial for real, foreign, and unknown projects — and it
arrives before anything is read, previewed, confirmed or written, so the denial reveals nothing about
whether that project exists. This contract applies to list, get, create, and unlink.

Paginated MCP reads return an opaque `next_cursor`. Pass that value back unchanged as `cursor` to
continue logs, traces, person or account timelines, affected-customer results, and notification
delivery receipts. Anectico rejects a malformed non-empty cursor instead of silently restarting at the
first page, so an agent cannot mistake duplicated first-page rows for a valid continuation.

The canonical cohort read tools are `list_cohorts`, `preview_cohort`,
`list_cohort_generations`, and `get_cohort_members`; they appear only with both
`mcp:read` and `analytics:read`. These are discovery permissions; reading computed
membership also requires its source scopes: `persons:profile:read` for profile predicates,
and `agents:content:read` for content event-property filters. Current sensitive-property
declarations can also restrict stored generations. Preview and member-page calls fail
when their required source scopes are missing. Cohort list/detail and history retain
metadata but mask protected counts to zero; those zeros do not prove an empty cohort.
History counts require the scopes of both the selected and preceding generation.
Pass `cohort_id` to `list_cohorts` for exact detail mode;
detail mode cannot be combined with `limit` or `cursor`. This keeps every cohort capability
reachable as first-class tools while the whole surface stays inside the host-safe tool limit.
Organization-level keys must pass a project UUID, while project-scoped keys remain pinned to their
signed project.
List/member `limit` may be omitted for the default or supplied from 1 through 1,000.
Their signed cursors are scope-bound and must be passed unchanged. Member cursors
also pin the materialized generation. Supply `generation` to read one retained historical
snapshot; omit it to capture the current generation on the first page. `get_cohort_members`
exposes the exact `total_count` on an authorized member-page response, including zero, and supports every page without a hidden
25-row cap. `preview_cohort` evaluates a behavioral or property definition without saving
it or creating a membership generation. `list_cohort_generations` returns immutable,
newest-first materialization history with added/removed counts, reason, retention, definition
snapshot/hash, and alert-mirror state.

Preview rechecks current project/history, source scopes, Governance and tracking declarations
before disclosure. Filtered behavioral predicates inspect selected values on matching and
nonmatching candidates, including nested content; profile predicates require complete consulted
profile-age evidence. Each behavioral preview condition is bounded to 250,000 candidate events and 64 MiB of
inspected source payload. Any source, policy, history or limit failure refuses the whole preview.
The shared time anchor does not freeze incoming events, paged profiles or individual deletions.

`refresh_cohort` receipts preserve the committed generation even if the count is withheld.
An unavailable identity reader or invalid/missing canonical mapping refuses refresh before any
membership generation changes. Retry after identity processing recovers; no partial audience
is committed. A valid-looking mapping can still be stale, so this is not an atomic identity
or erasure snapshot.
Because its RPC cannot distinguish a genuinely empty count from a permission-masked zero,
the MCP receipt reports either as `members=unknown`, omits the `/member_count` change,
and includes a warning. A positive returned count remains exact. To establish an exact
zero, use `get_cohort_members` with the required source permissions for that generation.

The event-discovery reads are `list_event_names` and `list_event_triggerers`; they appear
with both `mcp:read` and `analytics:read` and require one effective project. Triggerers also
requires exact RFC 3339 `start` and `end` values. Both return structured cursor pagination;
keep the project, filters, event and window unchanged when paging. Names and distinct IDs
are untrusted telemetry, never agent instructions.

Trend and person-funnel measurements use the `query_product_analytics` read action with `analytics:query`,
`analytics:read`, `persons:read` and applicable source scopes. Use `get_analytics_result` and
`list_analytics_participants` for the same frozen measurement. `get_analytics_contribution` reads
a funnel participant chain using exact result/snapshot/selection IDs, a decimal-string ordinal
and its contribution reference. It returns event references and first-entry attribution, not
arbitrary event properties. `cancel_analytics_result` is the one write in this family: it stops a
measurement that is still pending or running and reports the status that stands afterwards. It
needs `mcp:write` alongside `analytics:query`, is confirm-gated like every destructive write, and
never rewrites a status that is already final — so repeating it, or stopping a measurement that
finished first, changes nothing. See
[Product analytics](/docs/investigate/product-analytics) for execution keys, coverage, the status
vocabulary and the lossless JSON result envelope.

`decide_feature_flags` and `get_local_evaluation_snapshot` appear only with both `mcp:read` and
`flags:read`. They require one effective project, with project-scoped keys pinned to their signed
project. Decisions return complete structured flag values, payloads, and the fail-closed error bit.
Snapshots return complete flag definitions plus `schema_version`, `snapshot_version`, `updated_at`,
`max_age_seconds`, `etag`, and `project_id`, so an agent can compare a remote decision with the exact
downloaded snapshot without dropping freshness or cache identity.

`list_saved_searches` and `get_saved_search` are read actions reached through `execute_read_action`,
and are listed only when the key has both `mcp:read` and
`saved_search:read`. They require one effective project and expose the saved search's current
`version`. Saved-search cursors are bound to the organization, project, and signal; reusing one
under another filter fails instead of skipping or repeating rows. Supply `project_id` for an
organization-level credential. A project-scoped credential may omit it or repeat its exact signed
project; any explicit different value receives the same generic not-found result for real and
unknown projects before the lookup runs. The same project-selection rule applies to create,
update, duplicate, and delete actions.

Export reads are separate actions reached through `execute_read_action`, so they do not add entries
to the agent's tool list. Use `list_export_jobs` with optional `status`, `format`, `limit`, and the
previous signed `cursor`; use `get_export_job` to inspect one job; and use
`get_export_download` to resolve the download address of an unexpired completed result. Job
list/detail requires `export:read`; resolving the download requires `export:download`. The download
address is a path on the Anectico API which
re-authorizes on every request rather than a link that carries its own authority, and resolving it
requires that the caller still hold the read scopes the export's rows came from and be the job's
creator or an org owner/admin. Possessing the address grants nothing. Export cursors are bound to the organization,
effective project, and filters and expire after 15 minutes. They must be passed back unchanged.
Supply `project_id` when the MCP credential is not already project-scoped; a project-scoped
credential may omit it or repeat its exact signed project. Any explicit different value is denied
with the same generic not-found result without checking whether that project exists. This applies
to export list, detail, download, create, cancel, and retry tools.

## Write tools

A write-enabled key can perform selected daily actions directly and discover less common actions
through the write gateway. Each action requires `mcp:write` and its own domain scope.

Whether an action previews first is stated per row in the Safety column above, as *previews first*.
Every destructive action previews, without exception, and a few more preview because of their blast
radius rather than because they remove anything — opening an incident, inviting a person, filing a
ticket, sending a test message. So *previews first* is now the wider of the two labels: reading it as
"this destroys something" over-reads it, and reading *destructive* as "this will ask me first" is
correct. Every action that applies on the first call creates or appends; none of them replaces a
stored value. Writes that do not preview are audited and budgeted exactly like the ones that do. The
budget, the `idempotency_key` namespace and the confirmation token are all scoped to the individual
caller, so two people working in the same organization never share a budget, replay each other's
retries, or apply each other's confirmations.

Two costs are worth knowing before you design a retry loop. **A preview is free** — the first,
tokenless call of a confirm-gated action does not draw down the mutation budget, and neither does a
rejected or expired token, so previewing widely to decide is safe. **A replayed retry is not**: a call
that returns its earlier result rather than re-executing still costs one unit, so a client cannot spin
the budget by retrying.

Every incident write — create, update, status, comment, and delete — is addressed within one
project. Supply `project_id` when the MCP credential is not already project-scoped; a project-scoped
credential may omit it. Project ids come from the `list_projects` read action.

`acknowledge_alert` is approval-gated and requires a stable `idempotency_key`. Incident lifecycle
and comment writes require both the latest `expected_version` and a stable `idempotency_key`.
Their discovered MCP input schemas mark `idempotency_key` as required, while tools such as
`create_incident` and `resolve_alert` continue to advertise it as an optional retry safeguard.
Duplicate-sensitive writes **fail closed** when duplicate protection cannot be guaranteed: nothing is
attempted at all, so a retry is safe once the error stops. For incident `acknowledge`, `resolve`, and
`reopen`, the key is remembered for the life of the incident rather than for a few minutes, so an
exact retry keeps returning the original success indefinitely — while reusing that key with different
transition fields, or from a different API key, is rejected.

Dashboard update/delete and widget add/update/delete tools require `expected_version` from the
latest dashboard definition. Dashboard definitions include `version`; successful widget writes
return the new dashboard version. A stale mutation is rejected, so read again, reconcile the
changed dashboard, and request a new confirmation token where required.

Saved-search create and duplicate actions require a stable `idempotency_key`, and it is remembered
for the life of the saved search rather than for a few minutes: an exact retry keeps returning the
original copy however long you leave it, and reusing that key with different arguments returns a
conflict.
Update, duplicate, and delete also require the latest `expected_version`. Delete remains
confirmation-gated and requires `saved_search:delete`; the other mutations require
`saved_search:write`.

`create_export_job` and `export_logs` require a stable `idempotency_key`; this key is persisted
durably alongside the export job, so an exact retry remains safe across restarts. The key must be
1–128 ASCII letters, digits, `.`, `_`, `:`, or `-`; it is never whitespace-trimmed or Unicode-
normalized. Formats are limited to `csv`, `json`, and `parquet`, and time bounds must be exact RFC
3339 values with start before end. `cancel_export_job` is confirmation-gated for pending, running,
or retrying jobs.
Its `job_id` must be the exact lowercase canonical hyphenated UUID returned by creation. Malformed,
control/Unicode-contaminated, and oversized IDs are rejected before preview and never receive a
`confirm_token`. Preview enrichment is best-effort so `export:write` remains sufficient to cancel;
`export:read` is not required, and the confirmed mutation is still fully validated server-side.
`retry_export_job` re-enqueues only a terminally failed job with its original immutable scope and
query, and it is confirmation-gated for a reason worth reading before you confirm: re-running a job
CLEARS the recorded failure reason and code, the progress and row counts, the partial result and
every timestamp. Nothing restores them at any scope, so read what you need from the preview — it is
the last place that diagnosis exists. `cancel_export_job` and `retry_export_job` accept `project_id`
for an unpinned credential;
their target preview and mutation use the same effective project. For a project-pinned credential,
omitting `project_id` or sending the exact signed project succeeds; an explicit different value is
denied before either the preview read or mutation is attempted.
After `create_export_job` returns a job ID, MCP clients poll it with `execute_read_action` using
action `get_export_job` and arguments `project_id=<id> job_id=<job-id>`, then call
`get_export_download` with the same identifiers when the job completes. Polling requires
`export:read`; resolving the download requires `export:download` plus the export's own source read
scopes. A key with only `export:write` can create a job but cannot poll or download it.

`create_cohort` requires an explicit `kind` — `behavioral`, `property`, or `static`. There is no
default. A behavioral or property cohort also requires a `definition` predicate and rejects a
`members` list; a static cohort requires 1–5000 `members` and takes no definition.

`replace_static_cohort_members` is a `cohorts:write` gateway action that replaces the
complete membership of a static cohort. It requires the latest `expected_generation` and an
explicit `members` array; an empty array intentionally clears membership. Because replacement
is destructive, the first call only previews. Its confirmation token binds the cohort, project,
expected generation, and full ordered member input. The confirmed result reports resolved,
duplicate, and unresolved input counts plus the committed generation and alert-mirror state.

### Exact telemetry deletion

Project-scoped MCP keys can discover two destructive gateway actions when they carry the matching
domain scope:

- `delete_trace` requires `mcp:write` plus `traces:delete` and deletes every span of one exact trace;
- `delete_log` requires `mcp:write` plus `logs:delete` and accepts only a canonical 32-character
  uppercase hexadecimal log ID.

Neither action accepts an organization or project argument. The project comes only from the API
key's signed project binding, so an agent cannot override it. An organization-wide key does not see
these actions; create a narrowly scoped project key for this workflow. The first call only previews
the exact project and target. The second identical call with its `confirm_token` applies the durable
deletion. Deleting a trace does not delete correlated logs, and deleting a log does not delete its
trace. Repeating a confirmed deletion is harmless; `idempotency_key` additionally prevents a
transport retry from re-running the action.

A confirmed deletion is durable rather than a filter: the target stops appearing in searches,
timelines, dashboards and exports, a late or retried copy from an SDK stays hidden instead of
reappearing, and **alert rules honour it too**, so deleted telemetry cannot fire an alert.

## Discover the current surface

Use your MCP client's tool inspector, ask the agent to list its Anectico tools, or run:

```bash
anectico mcp verify
anectico docs
```

Tool definitions include their arguments and descriptions. If a tool is absent, check the key's
scopes before assuming the server does not support the operation.

For connection instructions, see [Connect an AI agent with MCP](/docs/agents/connect-mcp).