> ## Documentation Index > Fetch the complete documentation index at: https://docs.superlog.sh/llms.txt > Use this file to discover all available pages before exploring further. # Superlog MCP Tool Reference > Complete reference for all Superlog MCP tools — query telemetry, search incidents, manage dashboards, configure agents, and set alerts. Every tool registered in the Superlog MCP server is documented below. Tools are grouped by category. All tools default to the session's **active project** when you omit `project_id` — use `set_active_project` once at the start of a session to avoid repeating it on every call. Call `set_active_project` first in any new session. After that, you can omit `project_id` from every subsequent tool call. Telemetry-only tokens (scope `superlog:telemetry`) can only access the [Telemetry](#telemetry-tools) and [Project](#project-tools) tools. Incident, Dashboard, Alert, and Agent Config tools require a full-access token. See [MCP Overview](/api/mcp-overview) for token setup. *** ## Telemetry Tools ### query\_logs Search OpenTelemetry log records stored in the active project. Error-level rows automatically include flattened `exception_type`, `exception_message`, and `exception_stacktrace` fields when the log carries an exception attribute. Project to query. Defaults to the session's active project. Time window. Both fields accept an ISO-8601 timestamp or a ClickHouse time expression such as `now() - INTERVAL 1 HOUR`. Defaults to the last hour. * `since` — start of the window (inclusive) * `until` — end of the window (inclusive) Filter by `service.name`. Exact match. Filter by severity text, e.g. `ERROR`, `WARN`, `INFO`. Case-insensitive. Case-insensitive substring match on the log body. Filters on OTel resource attributes. Each entry is `{ key, value, op? }` where `op` is `eq` (default), `neq`, or `not_contains`. Example: `[{ "key": "deployment.environment", "value": "prod" }]` Equality filters on per-record log attributes (`LogAttributes`). Each entry is `{ key, value }`. Example: `[{ "key": "event.name", "value": "auth.failure" }]` Maximum rows to return. Range: 1–500. Default: `50`. *** ### query\_traces Search OpenTelemetry spans stored in the active project. Spans with exception events automatically include flattened `exception_type`, `exception_message`, and `exception_stacktrace` fields. Project to query. Defaults to the session's active project. Time window with `since` and `until`. Same format as `query_logs`. Filter by `service.name`. Exact match. Filter by span name. Exact match. OTel span-level status: `STATUS_CODE_OK`, `STATUS_CODE_ERROR`, or `STATUS_CODE_UNSET`. **Note:** By the OTel HTTP semantic conventions, only 5xx server responses automatically set `STATUS_CODE_ERROR` on a span — 4xx responses (including 410, 404, etc.) remain `STATUS_CODE_UNSET`. To filter spans by HTTP status code, use `span_attrs` with `key: "http.response.status_code"` instead. Only return spans whose duration is at least this many milliseconds. Filters on resource attributes. Same format as `query_logs`. Equality filters on per-span attributes (`SpanAttributes`). Each entry is `{ key, value }`. Use this to filter by HTTP status code, route template, database statement, etc. — those live in `SpanAttributes`, not in the span's OTel `status_code`. Example: `[{ "key": "http.response.status_code", "value": "410" }]` Maximum rows to return. Range: 1–500. Default: `50`. *** ### query\_metrics Fetch metric data points across gauge, sum, histogram, and summary tables. Gauge and sum points carry a scalar `value`. Histogram and summary points carry `count` and `sum` (plus `min` and `max` for histograms) instead, because they have no single scalar value. Project to query. Defaults to the session's active project. Filter by metric name. Exact match. Filter by `service.name`. Exact match. Time window with `since` and `until`. Same format as `query_logs`. Filters on resource attributes. Same format as `query_logs`. Maximum rows to return. Range: 1–500. Default: `100`. *** ### list\_services List distinct `service.name` values that have emitted telemetry in the given time window. Project to query. Defaults to the session's active project. Time window with `since` and `until`. Defaults to the last hour. *** ## Incident Tools Incident tools require a full-access token. Telemetry-only tokens cannot access these tools. ### get\_incident Fetch one incident by its UUID and everything needed to explain it. No `project_id` is required — the project is resolved from the incident record itself. The response includes the incident summary with the agent's findings (`root_cause_text`, `agent_summary`, `estimated_impact_text`), every linked issue with its stored telemetry sample (trace ID, span ID, stacktrace, attributes), and a pointer to the latest investigation run. To pull live telemetry, take a sample's `trace_id` and call `query_traces`, or filter `query_logs` / `query_traces` by the issue's service and exception type — passing the returned `project_id`. The UUID from the incident's URL: `https://superlog.sh/incidents/`. *** ### search\_incidents Search incidents in the active project, sorted by most recent activity first. By default, agent-classified noise (`status: autoresolved_noise`) is hidden. Pass `status: "all"` to include it, or `status: "autoresolved_noise"` to inspect only the noise pile. Project to search. Defaults to the session's active project. Filter by incident status: `open`, `resolved`, `autoresolved_noise`, `merged`, or `all`. Omitting this hides auto-classified noise. Filter by assigned severity: `SEV-1`, `SEV-2`, or `SEV-3`. Exact match on the incident's primary `service.name`. Case-insensitive substring matched against the incident title and codename. ISO-8601 timestamp. Only incidents with `last_seen >= since` are returned. ISO-8601 timestamp. Only incidents with `last_seen <= until` are returned. Maximum rows to return. Range: 1–200. Default: `50`. *** ## Project Tools ### list\_projects List every project the authenticated user can access, across all of their organizations. The currently active project is marked with `active: true`. No parameters. *** ### get\_active\_project Return the project that all tools default to when `project_id` is omitted. Useful for confirming the active project at the start of a session. No parameters. *** ### set\_active\_project Change the default project for subsequent tool calls in this session. The new default persists for the lifetime of the access token. The project to make active. Use `list_projects` to discover valid IDs. *** ## Dashboard Tools Dashboard tools require a full-access token. ### list\_dashboards List all dashboards in the active project (or `project_id`). Defaults to the session's active project. *** ### get\_dashboard Fetch a dashboard with all of its widgets. Defaults to the session's active project. Dashboard ID from `list_dashboards`. *** ### create\_dashboard Create a new dashboard, optionally seeding template variables. Dashboard template variables are named picklists that drive widget filters. Define a variable here and reference it in widget filter values with the token `$name` or `${name}` — for example, `{ "key": "deployment.environment", "value": "$env" }`. At view time, the dashboard shows a dropdown per variable and substitutes the selected option into every filter that references it. Defaults to the session's active project. Dashboard display name (max 120 characters). A URL slug is generated automatically. Template variable definitions. Each entry is `{ name, options[], defaultValue?, label?, attributeKey? }`. Variable names must start with a letter and contain only letters, digits, or underscores. *** ### update\_dashboard Rename a dashboard. Defaults to the session's active project. Dashboard to update. New display name (max 120 characters). *** ### add\_dashboard\_widget Append a widget to an existing dashboard. **Widget types:** | Type | Description | Default size | | ------------------- | ---------------------- | --------------------- | | `timeseries_count` | Event count over time | w:6 h:4 (half-width) | | `timeseries_metric` | Metric value over time | w:6 h:4 (half-width) | | `trace_table` | Span search table | w:12 h:6 (full-width) | | `log_table` | Log search table | w:12 h:6 (full-width) | | `markdown` | Freeform markdown text | w:4 h:5 | Omit `layout` to use the standard size for the widget type. The grid is 12 columns wide (`x` is 0–11, `w` is 1–12). Filter values may reference dashboard template variables with `$name` or `${name}`. Defaults to the session's active project. Dashboard to add the widget to. Widget type. One of: `timeseries_count`, `timeseries_metric`, `trace_table`, `log_table`, `markdown`. Widget display title (max 200 characters). Widget configuration object. Shape depends on `type`. Grid placement `{ x, y, w, h }`. Omit to use the standard size for the widget type. *** ### update\_dashboard\_widget Patch a widget's title, config, or layout. Provide only the fields you want to change. Defaults to the session's active project. Dashboard that contains the widget. Widget to update. New display title (max 200 characters). Replacement widget configuration. Replacement grid placement `{ x, y, w, h }`. *** ### delete\_dashboard\_widget Remove a widget from a dashboard. Defaults to the session's active project. Dashboard that contains the widget. Widget to remove. *** ### set\_dashboard\_variables Replace a dashboard's entire template-variable list. This **overwrites** the existing list — call `get_dashboard` first and edit the returned variables if you want to keep any existing ones. Defaults to the session's active project. Dashboard to update. Full set of template variable definitions. Same format as `create_dashboard`. *** ### delete\_dashboard Delete a dashboard and all of its widgets. This action is permanent. Defaults to the session's active project. Dashboard to delete. *** ## Alert Tools Alert tools require a full-access token. ### list\_alerts List all alerts in the active project. Defaults to the session's active project. *** ### get\_alert Fetch a single alert plus its 50 most recent firings. Defaults to the session's active project. Alert ID from `list_alerts`. *** ### create\_alert Create a new alert rule. For `logs` and `traces` sources, `aggregation` must be `count`. For `metric` source, `aggregation` must be `sum` or `avg` and `metric_name` is required. Defaults to the session's active project. Display name for the alert (max 200 characters). Telemetry source: `logs`, `traces`, or `metric`. How to aggregate the data: `count` (logs/traces) or `sum`/`avg` (metric). Comparison direction: `gt` fires when value > threshold; `lt` fires when value \< threshold. The numeric threshold to compare against. Required when `source` is `metric`. Equality filters that narrow the data the alert evaluates. Resource attribute to group by, e.g. `service.name`. When set, use `group_mode` to control how groups fire. `single` rolls all groups up into one evaluation; `per_group` fires independently per distinct `group_by` value. Evaluation window in minutes. Range: 1–1440. Default: `5`. How often the alert is evaluated, in seconds. Range: 15–3600. Whether the alert is active. Defaults to `true`. *** ### update\_alert Patch an existing alert. Provide only the fields you want to change. Validation runs on the merged result. Defaults to the session's active project. Alert to update. New display name. `logs`, `traces`, or `metric`. `count`, `sum`, or `avg`. `gt` or `lt`. New threshold value. Enable or disable the alert. Required when changing `source` to `metric`. Replacement filter definition. Replacement group-by attribute. `single` or `per_group`. Replacement evaluation window in minutes. How often the alert is evaluated, in seconds. Range: 15–3600. *** ### delete\_alert Permanently delete an alert. Defaults to the session's active project. Alert to delete. *** ### preview\_alert Evaluate a draft alert specification against current data without saving it. Returns whether the alert would breach right now. Defaults to the session's active project. Display name for the draft alert (max 200 characters). Telemetry source: `logs`, `traces`, or `metric`. How to aggregate the data: `count` (logs/traces) or `sum`/`avg` (metric). `gt` fires when value > threshold; `lt` fires when value \< threshold. The numeric threshold to compare against. Required when `source` is `metric`. Equality filters that narrow the data the alert evaluates. Resource attribute to group by, e.g. `service.name`. `single` rolls all groups into one evaluation; `per_group` fires independently per distinct `group_by` value. Evaluation window in minutes. Range: 1–1440. Default: `5`. How often the alert is evaluated, in seconds. Range: 15–3600. Whether the alert is enabled in the preview evaluation. *** ### test\_alert Re-evaluate a saved alert against current data and return the result. Defaults to the session's active project. Alert to test. *** ## Agent Config Tools These tools let you tune how Superlog's investigation agent works for a project — its issue filter, project context, and durable memories. Agent config tools require a full-access token. ### get\_issue\_filter Read the project's issue filter: per-kind include/exclude attribute clauses that decide which ERROR events become issues and incidents. Exclude clauses win. A non-empty include list means an event must match at least one include clause to become an issue. Defaults to the session's active project. *** ### update\_issue\_filter Update the project's issue filter. Each bucket you provide **replaces** that bucket; omit a bucket to leave it unchanged; pass `[]` to clear it. Call `get_issue_filter` first if you want to add to existing rules rather than overwrite them. Call `preview_issue_filter` before saving to verify the effect. Defaults to the session's active project. Log events must match at least one of these clauses (if non-empty) to become an issue. Each clause is `{ key, value }`. Span events must match at least one of these clauses (if non-empty) to become an issue. Log events matching any of these clauses are dropped and never become issues. Span events matching any of these clauses are dropped and never become issues. *** ### preview\_issue\_filter Preview which recent ERROR events (last 24 hours) would still become issues under a candidate filter, **without saving**. The buckets you pass are merged over the project's current filter — same semantics as `update_issue_filter`. Omit all buckets to preview the currently saved filter. Defaults to the session's active project. Candidate include clauses for logs. Candidate include clauses for spans. Candidate exclude clauses for logs. Candidate exclude clauses for spans. *** ### get\_project\_context Read the project's freeform context — the human-written description of the system (architecture, conventions, key services) that the investigation agent reads on every run. Defaults to the session's active project. *** ### set\_project\_context Overwrite the project's freeform context (max 8000 characters; longer input is truncated). This **replaces** the whole field. Call `get_project_context` first and edit the returned text if you want to preserve existing content. Use this for durable, system-level facts that apply to every investigation; for narrower learnings, prefer `create_agent_memory`. Defaults to the session's active project. The full context text. Replaces the existing value entirely. *** ### create\_agent\_memory Store a durable, reusable learning so future investigations inherit it. Record a memory whenever you uncover something worth remembering across investigations — a root-cause pattern, an infra or architecture fact, a domain term, or a correction about how to investigate. Keep the title a short handle and the body the specific, reusable fact — not a one-off incident narrative. Check `list_agent_memories` first to avoid creating duplicates. Defaults to the session's active project. Memory category: * `feedback` — a correction or preference for how the agent should behave * `terminology` — a domain term or acronym * `infra` — how the system is deployed or operates * `project` — general project facts Short handle for the memory (max 200 characters). The specific, reusable fact or instruction (max 4000 characters). *** ### list\_agent\_memories List all active (and archived) memories stored for the project. Defaults to the session's active project. *** ### update\_agent\_memory Patch a stored memory. Provide only the fields you want to change. Set `status: "archived"` to retire a memory without deleting it — archived memories stop being injected into investigations but remain visible in `list_agent_memories`. Defaults to the session's active project. Memory ID from `list_agent_memories`. New category: `feedback`, `terminology`, `infra`, or `project`. New title (max 200 characters). New body text (max 4000 characters). `active` or `archived`. *** ### delete\_agent\_memory Permanently delete a stored memory by ID. To retire a memory reversibly, prefer `update_agent_memory` with `status: "archived"` — archived memories stop being injected into investigations but remain visible in `list_agent_memories`. Defaults to the session's active project. Memory ID from `list_agent_memories`. *** ## Related * [MCP Overview](/api/mcp-overview) — authentication setup, client configuration, and token management