MCP tool reference

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.

How the surface is organized

MCP hosts have a practical limit on how many tools they handle well: many silently drop tools past about 40, and tool-selection accuracy degrades past about 50. Nothing reports this — the extra tools simply stop being offered to the model inside your client. Anectico therefore 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 / execute_write_action reach the less common mutations, alongside a few daily write actions promoted to first-class tools.

Nothing is unavailable behind a gateway. A gatewayed action requires exactly the same scopes its own tool would, and an action your key is not scoped for is neither listed nor runnable.

Read tool families

Read-only agents can work with:

• customers, aliases, profiles, accounts, and timelines;
• Issues and affected customers;
• logs, traces, metrics, services, and anomalies;
• replay and related evidence;
• alerts and incidents;
• on-call schedules, overrides, time-specific rotation resolution, and notification delivery receipts;
• organization plan, retention, and usage/quota meters;
• releases, events, flags, dashboards, project-scoped saved searches, and durable exports; and
• agent runs, scores, model calls, and LLM cost.

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) 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.

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. Canceling the MCP request stops the request handler and also cancels a downstream query when a poll is active at that moment. The highest-cost supported call, 60 seconds at a one-second cadence, performs one baseline read plus at most 60 poll reads; it remains one rate-limited MCP request and never mutates telemetry or configuration.

Each authenticated API key may hold at most two waits concurrently, with a 64-wait cap per server replica. Ordinary immediate get_service_health reads do not consume these permits. A saturated key or replica receives a deterministic MCP tool error before the health lookup runs and can retry after another wait exits. The admission cap is process-local rather than a distributed lock, so a multi-replica fleet has one 64-wait pool per replica; Anectico’s shared request-rate limiter separately bounds wait starts across the fleet. The server stores only a SHA-256 principal identity while a permit is active and removes it after the final wait exits.

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.

Incident reads use the strict case-file RPC: get_incident returns the current version, ordered timeline, immutable evidence, linked signals, and durable delivery receipts as one all-or-error result. list_oncall_schedules, get_oncall_schedule, and resolve_oncall are read actions reached through execute_read_action and require oncall:read; resolution uses the authoritative service and explains the active override or rotation layer. 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. 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 before a read, write preview, confirmation token, or Tickets RPC occurs. 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. 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. Do not use list_product_definitions for cohorts. 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, 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.

The canonical event reads are list_event_names, query_event_trends, and list_event_triggerers; they appear only with both mcp:read and analytics:read. The list_product_definitions read action no longer has an event_names mode. All three tools require one effective project. Trends and triggerers also require exact RFC 3339 start and end values; the service never guesses a relative lookback. Event-name and triggerer pages expose structured pagination.next_cursor/has_more; pass the cursor unchanged with the same project, filters, event, and time window. Event names, trend labels, and distinct IDs are delimited as untrusted telemetry in the human-readable result and must never be treated as agent instructions.

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 use the list_product_definitions read action with kind=exports, reached through execute_read_action, so the agent’s tool list stays within the host-safe limit. Omit id to list jobs with optional status, format, limit, and the previous signed cursor; pass id to inspect one job, or id plus download=true to mint a short-lived URL for an unexpired completed result. 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.

Destructive actions return a preview and confirmation token before they apply. Non-destructive writes still produce an audit record and are subject to per-key budgets.

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 idempotency storage is unavailable: no downstream mutation is attempted, so retry only after protection is restored. For incident acknowledge, resolve, and reopen, the key is also persisted durably alongside the incident record: an exact retry returns the original success even after a short-lived request-level retry cache is lost, while key reuse with different transition fields or a different authenticated 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, persisted durably alongside the saved search rather than only in a short-lived request-level cache. Exact retries return the original created copy after service restarts; reusing a 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. 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 list_product_definitions and arguments kind=exports project_id=<id> id=<job-id>, then repeat the read with download=true to mint a short-lived download URL when the job completes (requires export:download).

replace_static_cohort_members is an analytics: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.

Discover the current surface

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

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.