> For the complete documentation index, see [llms.txt](https://docs.luciq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luciq.ai/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/mcp-tools-reference.md).

# MCP Tools Reference

Luciq MCP provides **25 tools** across 11 areas. Most are read-only; three write tools (`update_bug`, `write_alerts`, and `write_incidents`) can modify data in your workspace. All tools use JSON-RPC 2.0 over Streamable HTTP and respect your workspace permissions (RBAC).

| **Area**                                 | **Tools**                                                              | **What they cover**                                                                                   |
| ---------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **App Context**                          | `list_applications`                                                    | Which apps you can work with                                                                          |
| **Crash-Level Debugging**                | `list_crashes`, `crash_details`, `crash_patterns`, `crash_diagnostics` | Crash groups, their details & full debugging payload                                                  |
| **Occurrences Deep-dive**                | `list_occurrences_tokens`, `get_occurrence_details`                    | Single crash instances (per device/session)                                                           |
| **Stability Beyond Crashes (App Hangs)** | `list_app_hangs`                                                       | App freezes / UI hangs                                                                                |
| **Performance (APM)**                    | `apm_list_groups`, `apm_group_view`, `apm_occurrence`                  | Network, launches, screen loads, flows, frame drops                                                   |
| **User-Reported Issues (Bugs)**          | `list_bugs`, `bug_details`, `update_bug`                               | User-reported issues via Luciq SDK (read & triage)                                                    |
| **User Sentiment & Store Ratings**       | `list_reviews`                                                         | User reviews and ratings                                                                              |
| **Surveys**                              | `list_surveys`, `survey_details`                                       | In-app surveys, NPS, and their responses                                                              |
| **App Health Overview**                  | `app_insights`                                                         | Aggregated cross-product health snapshot                                                              |
| **Issues & Opportunities**               | `list_issues`, `list_opportunities`, `opportunity_details`             | Unified Issues surface (across crashes, APM, AI-detected issues & bugs) and prioritized Opportunities |
| **Alerts & Rules**                       | `read_alerts`, `write_alerts`, `read_incidents`, `write_incidents`     | Alert rules and the triggered alerts (incidents) they produce                                         |

{% hint style="info" %}
**Read vs. write.** Three tools change data: `update_bug` (a bug's status, priority, tags, or duplicate state), `write_alerts` (create, update, or delete an alert rule), and `write_incidents` (resolve or reopen a triggered alert). Every other tool only reads. One read tool, `crash_diagnostics`, has a side effect: it computes and caches a crash-analysis payload on demand (so it isn't a pure read), but it never changes your crash, bug, or app data. Write actions respect your RBAC permissions and are audit-logged like any dashboard action.
{% endhint %}

Each tool exposes [MCP tool annotations](https://modelcontextprotocol.io/) so your client can reason about its behavior. All tools are `readOnlyHint: true` except the write tools (`update_bug`, `write_alerts`, `write_incidents`, marked `readOnlyHint: false`) and `crash_diagnostics` (`readOnlyHint: false`, `destructiveHint: false`, because it triggers an on-demand computation). No tool reaches outside your Luciq workspace, so every tool is `openWorldHint: false`.

The details and context for each tool are detailed below.

### **1. App Context**

***

### `1.1 list_applications`

#### What it does

Returns all applications accessible to your account.

#### Use this when

* Setting up your MCP config and not sure which `slug` / `mode` to use.
* You work across multiple apps and want a quick list in the IDE.

#### Parameters

**None required.**

Optional:

* `platform`: `ios`, `android`, `react_native`, `flutter`
* `limit`, `offset`

#### Key Fields

* **slug** — Identifier used in most tools
* **name** — Display name
* **token** — Needed for the Reviews tool
* **platform** — App platform
* **mode** — App environment
* **created\_at** — Timestamp

#### Usage Examples

* “List all my applications.”
* “Show only iOS applications.”
* “Which apps do I have access to?”

### **2. Crash-Level Debugging**

***

### `2.1 list_crashes`

#### What it does

Shows crash groups for an app: how often they happen, how many users they affect, and basic cause.

#### Use this when

* You want to know “what should we fix first?”
* You’re scanning production for new, recent, or high-impact crashes.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `date_ms` (time window)
* `status_id` (`1` open, `2` closed, `3` in progress)
* `devices`, `os_versions`
* `app_versions`
* `current_views`, `teams`
* `platform` — `IOS`, `ANDROID`, `DART` (Flutter), `JAVASCRIPT` (React Native)
* `type` — `CRASH`, `ANR`, `OOM`, `NON_FATAL` (which apply depends on platform: Android supports `CRASH`, `ANR`, `NON_FATAL`; iOS supports `CRASH`, `OOM`, `NON_FATAL`; React Native and Flutter support all four)
* `subtype` — `CRITICAL`, `ERROR`, `WARNING`, `INFO` (only when `NON_FATAL` is included in `type`)
* `feature_flags` — scope to crashes seen under a given feature flag or experiment. Use the bare flag name when no variant was set (e.g. `private_mode`), or `flag_name -> variant` when a variant was set (e.g. `checkout_flow -> external_request`).
* `user_attributes` — filter by custom user attributes reported by the SDK (e.g. `Country`, `Plan`). Each attribute name maps to one or more conditions using the operators `contain`, `not_contain`, `equal`, or `not_equal`; conditions on the same attribute combine, and different attributes are AND-ed together. Attribute-name keys are case-sensitive and must match the SDK-reported name exactly; condition values are matched case-insensitively.

#### Sorting & Pagination

* `sort_by` — `last_occurred_at` (default), `occurrences_counter`, `affected_users_counter`, `max_app_version`, `min_app_version`, `severity`, `first_occurred_at`
* `direction` — `asc` or `desc` (default `desc`)
* `limit` (default 20, max 50), `offset`

#### Key Fields

* **number** — Crash ID
* **exception** — Main exception message
* **crash\_cause** — File/function of failure
* **crash\_type** — Fatal or non-fatal
* **occurrences\_counter** — Total occurrences
* **affected\_users\_counter** — Unique users affected
* **app\_version** — Version where it occurred
* **last\_occurred\_at** — Latest timestamp
* **severity / level** — Severity indicators

#### Usage Examples

* “Show production crashes for the last 7 days.”
* “List crashes for version 3.0.1.”
* “Show open crashes only.”
* “What are the top Android crashes?”
* “Show crashes seen under the `checkout_flow` feature flag.”
* “Show crashes from users in Egypt on the free plan.”

### `2.2 crash_details`

#### What it does

Shows everything we know about a single crash (stack, versions, status, severity).

#### Use this when

You need to investigate or reproduce the crash.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` crash number

#### Key Fields

* **exception** — Full exception
* **exception\_name** — Exception class/type
* **crash\_cause** — Main file/line
* **stack\_frames\[]** — Parsed stack trace
* **min\_app\_version**, **max\_app\_version** — Affected versions
* **crash\_type** — Fatal/non-fatal
* **status\_id** — Current status
* **team** — Assigned team
* **sdk\_version** — SDK version
* **package / ndk\_info / path** — Platform extra fields

#### Usage Examples

* “Show details for crash #12.”
* “Explain the stack trace for crash 45.”
* “Which file caused crash #17?”
* “What versions are affected by crash 5?”

### `2.3 crash_patterns`

#### What it does

Groups a crash’s occurrences by **device**, **app version**, **OS**, **view**, etc. to show where it clusters.

#### Use this when

* You want to understand where a crash is concentrated.
* You want to answer: “Is this crash mostly on Pixel 8? On Android 14? On version 3.0.4?”

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` crash number

#### Useful Filters

* `pattern_key` — which dimension to group by: `app_versions` (default), `devices`, `oses`, `current_views`, `app_status`, `experiments`
* `date_ms` (time window)
* `app_versions`, `devices`, `os_versions`
* `sort_by` — `occurrences_count` (default), `last_seen`, `first_seen`; `direction` — `asc` or `desc` (default `desc`)

#### Key Fields

* **value** — Group label (device, OS, version, etc.)
* **occurrences\_count** — Occurrences in that bucket
* **first\_seen**, **last\_seen** — Timestamp range

#### Usage Examples

* “Break down crash #20 by device.”
* “Show OS patterns for crash #12.”
* “Which views are tied to crash #3?”
* “Group crash #5 by app versions.”

### `2.4 crash_diagnostics`

#### What it does

Returns the **full debugging payload** for a single crash in one call: stack trace, device metrics, distributions (OS, device model, app version), and the screen flows leading up to the crash. It’s the fastest way to hand an AI assistant everything it needs to reason about a crash.

#### Use this when

* You ask your assistant to **fix, debug, or investigate** a specific crash.
* You want the stack trace plus the surrounding context (which devices, OS versions, and user journeys are affected) without chaining several calls.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` crash number

#### Notes

* This analysis is computed on demand. If the response comes back with `status: "generating"`, the payload is still being prepared, simply ask again after a moment and it will return the full result.

#### Usage Examples

* “Help me fix crash #42.”
* “Give me the full diagnostics for crash #18.”
* “What led up to crash #7 and which devices are hit hardest?”

### **3. Occurrences Deep Dive**

***

### `3.1 list_occurrences_tokens`

#### What it does

Lists individual **occurrences** of a crash as ULID tokens, so you can pick specific ones to inspect.

#### Use this when

* You want to inspect or debug specific sessions.
* You want to drill down from a crash group to specific user/device sessions.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` crash number

#### Useful Filters

* `app_status` (foreground / background)
* `devices`
* `os_versions`
* `app_versions`
* `experiments`
* `current_views`
* `date_ms` (date range)

#### Key Fields

* **states\_tokens\[]** — ULIDs for occurrences
* **total\_occurrences** — Count of matches

#### Usage Examples

* “List all occurrences for crash #28.”
* “Show only foreground occurrences.”
* “Which iOS 17 devices experienced crash 5?”
* “List occurrences from Pixel devices.”

### `3.2 get_occurrence_details`

#### What it does

Shows the **exact context** of one crash occurrence: device, OS, memory, storage, app status, user, and log URLs.

#### Use this when

You need to reproduce or understand a single session.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` crash number
* `ulid` state/occurrence ULID token (obtained from `list_occurrences_tokens`)

#### Key Fields

**state.fields:**

* **app\_version** — Version at crash moment
* **device**, **os** — Device info
* **current\_view** — Active screen
* **app\_status** — Foreground/background
* **memory**, **storage** — Resource usage
* **country**, **city** — Location
* **screen\_size**, **density** — Display metrics
* **reported\_at** — Timestamp
* **email**, **user\_name** — User identity

**logs:**

* Downloadable compressed logs
* Experiment logs

**user:**

* Email, UUID, name

**exception\_message:**

* Exception for this specific occurrence

#### Usage Examples

* “Show occurrence details for token X.”
* “Which device caused this occurrence?”
* “Show logs for the earliest occurrence of crash #8.”
* “What view was active during this crash?”

### **4. Stability Beyond Crashes (App Hangs)**

***

### `4.1 list_app_hangs`

#### What it does

Shows grouped **hang** events (UI freezes) for your application.

The server automatically chooses:

* `FATAL_UI_HANG` for iOS
* `ANDROID_FATAL_HANG` for Android
* Both for cross-platform apps

#### Use this when

You want to find “the app froze for me” issues, not just crashes.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `date_ms`, `status_id` (`1` open, `2` closed, `3` in progress)
* `app_versions`, `devices`, `os_versions`
* `platform` — `IOS`, `ANDROID`, `DART`, `JAVASCRIPT`
* `current_views`, `teams`
* `sort_by` — `last_occurred_at` (default), `occurrences_counter`, `affected_users_counter`, `max_app_version`, `min_app_version`, `severity`, `first_occurred_at`; `direction` — `asc`/`desc` (default `desc`)

The hang type (`FATAL_UI_HANG` / `ANDROID_FATAL_HANG`) is chosen automatically by platform, you don't pass it. Unlike `list_crashes`, hangs don't take `type`, `subtype`, or `feature_flags` filters.

#### Key Fields

* **number** — Hang ID
* **crash\_type** — Hang classification
* **exception** — Hang summary
* **crash\_cause** — Where it froze
* **occurrences\_counter** — Total hangs
* **affected\_users\_counter** — Unique impacted users
* **platform**, **app\_version**
* **last\_occurred\_at** — Recent hang timestamp

#### Usage Examples

* “Show hangs in production for the last 14 days.”
* “List iOS hangs only.”
* “Which hangs are still open?”
* “What views cause most UI hangs?”

### **5. Performance (APM)**

***

The APM tools cover the full Application Performance Monitoring surface. Every APM tool takes a required `metric` parameter that selects the performance domain:

* `network` — network requests
* `launch` — app launches (cold/warm)
* `flows` — custom traces / flows
* `screen_loading` — screen load times
* `frame_drop` — UI frame drops

The three tools form a drill-down: rank groups (`apm_list_groups`) → inspect one group’s panels (`apm_group_view`) → inspect individual occurrences (`apm_occurrence`). Filters and sort keys are scoped per metric, the server rejects a key that doesn't apply to the chosen metric (e.g. failure-rate filters are network-only). Your AI assistant picks valid combinations from the schema, so you can describe what you want in plain language.

### `5.1 apm_list_groups`

#### What it does

Ranks APM groups worst-first for an app (e.g. slowest endpoints, slowest launches, slowest screens), paginated and filtered.

#### Use this when

* You want to know “what’s our worst-performing endpoint / screen / launch?”
* You’re scanning for performance regressions in a release.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `metric` `network`, `launch`, `flows`, `screen_loading`, `frame_drop`

#### Useful Filters

* `date_ms`, `app_version`, `platform` (`ios`, `android`)
* `apdex`, `apdex_change`, `count`, `dissat_count` (numeric ranges; not applicable to `launch`)
* `95th_percentile_ms`, `50th_percentile_ms` (not applicable to `launch` or `frame_drop`)
* `total_failure_rate`, `client_failure_rate`, `server_failure_rate` (network only)
* `view_type` (screen\_loading only), `teams` (screen\_loading / frame\_drop), `key_metric`, `group_name`, `user_attributes`

#### Sorting & Pagination

* `sort` by one key, `direction` `asc`/`desc`. Valid keys: `apdex`, `apdex_change`, `occurrences`, `dissat_count` (all metrics); `p95`, `p50` (all except frame\_drop); `failure_rate` (network only); `frozen_frames_percent`, `slow_frames_percent` (frame\_drop only)
* `limit` (default 5, max 100), `offset`

#### Usage Examples

* “List my worst app launches.”
* “Show the slowest network endpoints this week.”
* “Which screens have the lowest Apdex?”

### `5.2 apm_group_view`

#### What it does

Fetches the panels for a single APM group (charts, tables, and summary) in one call.

#### Use this when

You’ve identified a problem group and want the full breakdown (trends, distributions, summary metrics).

#### Required

* `slug`, `mode`, `metric`
* `views` — which panels to return. Available panels (which apply depends on the metric): `summary`, `apdex_chart`, `throughput_chart`, `spans_table`, `dimensions` (all metrics); `outliers` (all except frame\_drop); `failure_rate` (network only); `stages_breakdown` (launch, screen\_loading); `web_vitals` (screen\_loading only); `frames_distribution`, `delayed_frames` (frame\_drop only). Panels not valid for the metric are dropped and reported back in `ignored_views`.
* A group identifier: either `group_uuid` (preferred, from `apm_list_groups`) or `group_url` (with optional `method` for network endpoints)

#### Usage Examples

* “Show me the breakdown for the slowest endpoint.”
* “Give me the summary panel for this screen-load group.”

### `5.3 apm_occurrence`

#### What it does

Inspects individual occurrences within an APM group: the single worst occurrence, a specific occurrence by token, or a paginated list.

#### Use this when

You want the concrete, individual sample behind an aggregate, e.g. the exact slowest request or launch.

#### Required

* `slug`, `mode`, `metric`
* `selector` — `worst`, `by_token`, or `list`
* A group identifier: `group_uuid` (preferred) or `group_url` (+ optional `method`)
* `token` when `selector=by_token`

#### Usage Examples

* “Show me the single worst occurrence for this endpoint.”
* “List the slowest launches in this group.”

### **6. User-Reported Issues**

***

### `6.1 list_bugs`

#### What it does

Shows **user-reported bugs** (reported via Luciq’s SDK), with simple filtering.

#### Use this when

* You want to see user-submitted issues.
* You’re scanning for new or high-priority bugs in a release.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `status_id`: `1` New, `2` Closed, `3` In Progress
* `priority_id`: `-1` N/A, `1` Trivial, `2` Minor, `3` Major, `4` Blocker
* `app_version`, `os_versions`, `devices`
* `platform`: `ios`, `android` (cross-platform apps only)
* `device_class`: `high`, `medium`, `low` (Android apps only)
* `category` / `no_category`, `tag` / `no_tag` (include/exclude; each filter is a list of OR-groups that are AND-ed together)
* `type`, `experiments`, `email` (with an `equal` / `not_equal` / `contain` / `not_contain` operator)
* `duplicate_type`: `single`, `manual_master`, `automatic_master`, `manual_duplicate`, `automatic_duplicate`
* `forwarded_to` / `not_forwarded_to` (e.g. `jira`)
* `reported_at` (range, in Unix epoch **seconds**), `title` (free-text search)

#### Sorting & Pagination

* `sort_by` (default `reported_at`), `direction` `asc`/`desc` (default `desc`)
* `limit` (default 20, max 50), `offset`

#### Key Fields

* **number** — Bug ID
* **title** — User-entered title
* **email** — Reporter
* **priority\_id**, **status\_id**
* **reported\_at**, **last\_activity**
* **categories**
* **duplicated\_bugs\_count**

#### Usage Examples

* “Show new bugs for version 3.3.”
* “List all open bugs.”
* “Show bugs reported today.”
* “Which bugs are highest priority?”

### `6.2 bug_details`

#### What it does

Returns detailed bug information including logs, user data, and device metadata.

#### Use this when

You need full context to reproduce the bug.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` bug number

#### Key Fields

**Top-level:**

* **title**, **type** — Bug title & type
* **priority\_id**, **status\_id** — Bug priority & status
* **reported\_at**, **last\_activity** — When it was reported, last update time
* **email**, **tags** — Reporter’s email, tags
* **categories**, **team** — Assigned categories, team

**state.fields (context):**

* os, device, country, city
* app\_version, sdk\_version
* current\_view
* screen\_size, density
* bundle\_id
* user\_attributes
* duration (session length)

**state.logs:**

* user\_steps, network\_log, sessions\_profiler, etc. with url and is\_empty\_array.

#### Usage Examples

* “Show details for bug #468.”
* “What steps did the user take?”
* “Which device was used?”
* “Show the network log for this bug.”

### `6.3 update_bug`

{% hint style="warning" %}
**This is a write tool.** It changes the state of a bug in your workspace, exactly as if you’d edited it in the dashboard. It respects your RBAC permissions and is audit-logged. It’s the only Luciq MCP tool that modifies data.
{% endhint %}

#### What it does

Updates a bug’s **status**, **priority**, or **tags**, or marks/unmarks it as a **duplicate** of another bug, directly from your IDE. This lets you complete bug triage end-to-end without switching to the dashboard.

#### Use this when

You’ve investigated a bug (via `bug_details`) and want to act on it: close it, reopen it, reprioritize it, retag it, fold it into another bug as a duplicate, or detach it from its master.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `number` bug number

#### Optional (provide at least one of `status_id`, `priority_id`, `tags`, or `action`)

* `status_id`: `1` New, `2` Closed, `3` In Progress
* `priority_id`: `-1` N/A, `1` Trivial, `2` Minor, `3` Major, `4` Blocker
* `tags`: the new **full** set of tags for the bug. This **replaces** (does not merge with) the existing tags; any current tag not in the array is removed. To add or remove a single tag, read the current tags via `bug_details` first and send the merged list. Pass `[]` to clear all tags. (Setting `tags` requires an additional `bugs.tags.modify` permission.)
* `action`: `mark_as_duplicate` or `unmark_as_duplicate`.
  * `mark_as_duplicate` merges this bug into a master, requires `original_bug_number`. Side effect: this bug’s occurrences move into the parent group and its status/priority are overwritten by the parent’s.
  * `unmark_as_duplicate` detaches this bug from its master, restoring it to a standalone bug.
  * `action` **cannot** be combined with `status_id` or `priority_id` in the same call.
* `original_bug_number`: the master bug’s `number`. Required when `action` is `mark_as_duplicate`; ignored otherwise.

#### Usage Examples

* “Close bug #468.”
* “Set bug #51 to Major priority and tag it `checkout`, `regression`.”
* “Reopen bug #120.”
* “Mark bug #205 as a duplicate of bug #198.”
* “Unmark bug #205 as a duplicate.”

### **7. User Sentiment & Store Ratings**

***

### `7.1 list_reviews`

#### What it does

Lists app reviews (e.g., from store/native/custom prompts) with filters for rating, version, country, etc.

#### Use this when

* You want to correlate user feedback with app stability.
* You want to see 1–2 star reviews for a release.
* You’re checking if a performance or crash issue shows up in user feedback.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `date_ms.gte` / `lte`
* `app_version`
* `rating` – array of star ratings `[1–5]`
* `country`
* `prompt_type` – `custom`, `native`, `app_store`
* `os` (for cross-platform)

#### Key Fields

* **title**, **body** — Review content
* **star\_rating** — 1–5 stars
* **username**, **country**
* **app\_version**, **device**
* **date**
* **has\_suspected\_sessions** — Linked to stability issues
* **has\_custom\_suspected\_sessions**

#### Usage Examples

* “Show 1-star reviews for version 3.0.”
* “List negative reviews from the US.”
* “Show native prompt reviews only.”
* “What are the most recent app store reviews?”

### **8. Surveys**

***

### `8.1 list_surveys`

#### What it does

Lists the surveys configured for an app (custom surveys, NPS, and app-store prompts), newest-first, with their status.

#### Use this when

* You want to see which surveys are live, paused, or in draft.
* You’re looking up a survey’s `id` before pulling its responses.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `status`: `0` Draft, `1` Published, `2` Paused
* `type`: `0` Custom, `1` NPS, `2` App Store

#### Usage Examples

* “List my published surveys.”
* “Show all NPS surveys.”
* “Which surveys are currently paused?”

### `8.2 survey_details`

#### What it does

Returns a survey’s questions, response statistics, and a page of individual responses (filterable and paginated, mirroring the dashboard).

#### Use this when

You want to read what users answered, e.g. NPS scores and verbatims for a specific survey.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `id` survey id (from `list_surveys`)

#### Useful Filters

* `nps` (filter by NPS score 0–10)
* `search_words` (free-text search across response values, name, and email)
* `response_status`: `0` Open, `1` Closed
* `app_versions`, `devices`, `os_versions`, `countries`, `platforms`, `locale`
* `date_ms`

#### Notes

* Responses are paginated at **25 responses per page** via the `page` parameter.

#### Usage Examples

* “Show me the responses for survey 312.”
* “What are the NPS detractor comments on my NPS survey?”
* “Show survey responses from the last 30 days.”

### **9. App Health Overview**

***

### `9.1 app_insights`

#### What it does

Returns an **aggregated, cross-product health snapshot** for one app in a single call. Each section is returned under its own key:

* `crashes` — non-fatal crash counts
* `bugs` — bug report totals
* `apm` — APM key metrics (network, launches, screen loads, flows)
* `monitoring` — stability rates (crash-free sessions, ANR, OOM, app hangs)

A section whose product **isn't included in your plan is omitted entirely** (its key is absent). A section that is enabled but temporarily unavailable (e.g. a data-retention limit or a failing service) returns an `error` object instead of data, while the other sections still return.

#### Use this when

You want a fast “how healthy is this app right now?” overview before drilling into a specific area.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Optional

* `filters.date_ms` (time window)
* `filters.app_version`

#### Usage Examples

* “Give me a health overview for my app.”
* “How is the app doing this week, crashes, bugs, and performance?”
* “Show app insights for version 3.4.”

### **10. Issues & Opportunities**

***

These tools cover Luciq's product qualitative surface, mirroring the dashboard. **Issues** is the unified view of everything affecting your app across sources (crashes, APM, AI-detected visual issues and broken functionality, and bugs), ranked by Apdex impact. **Opportunities** group related signals into prioritized, actionable items you can track to closure.

### `10.1 list_issues`

#### What it does

Lists an app's **Issues**, a unified surface that spans crashes, APM, AI-detected visual issues, broken functionality, and bugs in one ranked list. Results are ranked by Apdex impact by default. Which sources appear depends on the app's plan: each source is only included when the plan enables it.

#### Use this when

* You want a single, cross-source view of “what's hurting this app the most?” rather than scanning crashes, APM, and bugs separately.
* You're triaging by user impact and want issues ranked by Apdex.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `date_ms` (time window; the range between `gte` and `lte` must be at least 24 hours)
* `search_tokens` (free-text, e.g. exception text or group name)
* `app_version`
* `teams`
* `platform` — `IOS`, `ANDROID`, `DART` (Flutter), `JAVASCRIPT` (React Native)
* `apm_types` — `networks`, `traces`, `launches`, `screen_loadings`, `frame_drops`
* `crashes_types` — `CRASH`, `ANR`, `OOM`, `NON_FATAL`
* `ai_issues_types` — `visual_issue`, `broken_functionality`
* `bugs_types` — accepted but not currently enforced by the backend
* `apdex_severity` — `high`, `medium`, `low`, `no_impact`

Sorting: `sort_by` (`apdex_impact`, `occurrences_counter`) and `sort_direction` (`asc`, `desc`). Set `top_issues: true` to return a smaller curated list of the most impactful issues.

#### Key Fields

* **source** — Which surface the issue came from (crash, APM, visual issue, broken functionality, bug)
* **apdex\_impact** — Apdex impact used for ranking
* **apdex\_severity** — `high`, `medium`, `low`, `no_impact`
* **occurrences\_counter** — Total occurrences
* **app\_version** — Version where it occurred
* **platform** — Issue platform

#### Notes

* This tool uses **per-source pagination**: the response returns a pagination token for each source (APM, crashes, visual issues, broken functionality, bugs). Pass those tokens back in the `pagination` object to fetch the next page per source.

#### Usage Examples

* “Show me the top issues for my app this week.”
* “List the highest-Apdex-impact issues in production.”
* “Show only crash and APM issues for version 3.4.”
* “What are the most impactful issues right now?”

### `10.2 list_opportunities`

#### What it does

Lists an app's **Opportunities** with their status, ranked by priority (highest first), then by recency. Opportunities group related signals into prioritized, actionable items.

#### Use this when

* You want to see the prioritized, actionable items for an app rather than raw issues.
* You're reviewing what's open, in progress, or already handled.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development

#### Useful Filters

* `status` — `open`, `in_progress`, `closed`, `dismissed`
* `priority` — `1`, `2`, `3`, `4`, `unset`
* `team_id` — Team ULID, or `unassigned`

Pagination via `limit` (default 20, max 50) and `offset`.

#### Key Fields

* **id** — Opportunity ID (use with `opportunity_details`)
* **status** — `open`, `in_progress`, `closed`, `dismissed`
* **priority** — Priority level
* **team** — Assigned team

#### Usage Examples

* “List my open opportunities.”
* “Show the highest-priority opportunities first.”
* “Which opportunities are assigned to my team?”
* “Show unassigned opportunities.”

### `10.3 opportunity_details`

#### What it does

Returns a single opportunity's details: status, priority, source counts, assigned team, and its timeline. Use the `id` from `list_opportunities`.

#### Use this when

You've spotted an opportunity in `list_opportunities` and want the full context: what it groups, who owns it, and how it has progressed.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `id` opportunity id (obtained from `list_opportunities`)

#### Key Fields

* **status** — `open`, `in_progress`, `closed`, `dismissed`
* **priority** — Priority level
* **source\_counts** — Counts of the signals grouped under the opportunity
* **team** — Assigned team
* **timeline** — Status/activity history for the opportunity

#### Usage Examples

* “Show details for opportunity 312.”
* “What signals are grouped under this opportunity?”
* “Who owns opportunity 45 and what's its status?”

### **11. Alerts & Rules**

***

These tools cover Luciq's alerting surface, mirroring the dashboard. An **alert (rule)** is a configured definition that watches a metric and fires when its condition is met; a **triggered alert (incident)** is a single firing that a rule produced. `read_alerts` and `read_incidents` are read-only; `write_alerts` and `write_incidents` change data and are confirmed before running. For the alerting concepts and dashboard configuration, see the [Alerts & Rules](/product-guides-and-integrations/product-guides/automation-and-workflows/alerts-and-rules.md) product guide.

Authoring a rule is a two-step flow: call `read_alerts` with `action: init` to get the per-app catalog of valid types, triggers, conditions, actions, and lookup IDs, then build the `write_alerts` payload strictly from what `init` exposes. `write_alerts` rejects any type, trigger, condition, action, or operator that `init` doesn't list for the app.

### `11.1 read_alerts`

#### What it does

Reads your alert **rules** (the configured definitions and thresholds). Pick the operation with `action`:

* `list` — all rules for an app, with their status and how often each has fired.
* `details` — the full payload of a single rule, by `ulid`.
* `init` — the per-app catalog of valid rule types, triggers, conditions, actions, operators, and lookup tables (developers, teams, statuses, priorities, integrations, tags). Call this before `write_alerts`.

#### Use this when

* You want to see which alerts are configured, or inspect one rule's conditions.
* You're about to create or edit a rule and need the app's valid types and IDs (call `init`).

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `action` — `list`, `details`, or `init`
* `ulid` — required for `details` (full prefixed id, e.g. `crashes_01HX…`, `apm_01HX…`)

#### Sorting (list)

* `sort_by` — `latest_creation_date` (default), `last_edit_date`, `highest_triggered_count`
* `sort_direction` — `asc` or `desc` (default `desc`)

#### Key Fields

* **ulid** — Full prefixed rule id (used by `write_alerts` and `read_alerts details`)
* **type / trigger / conditions / actions** — How the rule is defined
* **status** — Whether the rule is enabled
* **highest\_triggered\_count** — Rolling trigger count, used to sort noisiest-first

#### Usage Examples

* “Show me my alerts.”
* “Which alert rules fire the most?”
* “Show the details for the crash-free-sessions alert.”
* “What alert types can I set up for this app?”

### `11.2 write_alerts`

{% hint style="warning" %}
**This is a write tool.** It creates, updates, or deletes an alert rule in your workspace, exactly as if you'd edited it in the dashboard. It respects your RBAC permissions and is audit-logged.
{% endhint %}

#### What it does

Creates, updates, or deletes an alert **rule**. Choose the operation with `action`: `create`, `update`, or `delete`. Author the payload from `read_alerts` `init` first, following the two-step flow described in the section intro above.

#### Use this when

You've decided on an alert to add or change: a new rule, a threshold or scope edit, or removing a redundant rule.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `action` — `create`, `update`, or `delete`
* `ulid` — required for `update` and `delete` (full prefixed id from `read_alerts`)

#### Rule Fields (create / update)

* `title` — Human-readable rule title
* `type` — Rule type from `init` (e.g. `Crashes`, `Bugs`, `Overall app`, `App launches`, `Network`, `Flows`, `Screen loading`, `Screen rendering`)
* `trigger` / `trigger_options` — The trigger key and its threshold/time options, from `init`
* `conditions` — Each with a `key`, `operator`, and `value`/`values`, combined via `operation` (`0` = AND, `1` = OR)
* `actions` — What fires on trigger (email, forward, set assignee/status/priority/team, add tag, reply), with an optional notification `frequency` throttle
* `rule_owner` — Team id that owns the rule, or empty for unassigned

#### Notes

* If a required detail is missing (a threshold, a time window, which metric, or where to send the alert), the agent proposes a sensible value and waits for your confirmation rather than guessing.

#### Usage Examples

* “Alert me when any crash affects more than 5% of users.”
* “Raise the threshold on my launch-time alert to 4 seconds.”
* “Delete the duplicate ANR alert.”

### `11.3 read_incidents`

#### What it does

Reads **triggered alerts (incidents)**, the actual firings your rules produced. Pick the operation with `action`: `list` or `details`.

#### Use this when

* You want to know what fired, or review recent or open incidents.
* You want to investigate a specific firing, or judge whether a rule is noisy by how often it fires.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `action` — `list` or `details`
* `ulid` — required for `details`

#### Useful Filters (list)

* `filters.date_ms` (`gte` / `lte`, in milliseconds)
* `filters.status` — `open`, `manual_resolve`, `automatic_resolve`
* `filters.type` — `overall_app`, `launch`, `screen_loading`, `network`, `trace`, `frame_drop`, `crash`, `anr`, `oom`, `non_fatal`, `fatal_ui_hang`, `feature_experiment`
* `filters.title` — title tokens (case-insensitive substring; all tokens must match)

#### Sorting & Pagination

* `sort_by` — `last_triggered` (default), `first_triggered`, `count`; `sort_direction` — `asc` / `desc` (default `desc`)
* `limit` (default 50, max 100), `offset`

#### Usage Examples

* “What alerts fired this week?”
* “Show open incidents.”
* “Which alert fired the most times?”

### `11.4 write_incidents`

{% hint style="warning" %}
**This is a write tool.** It changes the status of a triggered alert in your workspace. It respects your RBAC permissions and is audit-logged.
{% endhint %}

#### What it does

Updates the status of a **triggered alert (incident)**. Choose the operation with `action`:

* `resolve` — mark an open triggered alert as manually resolved.
* `reopen` — mark a previously resolved triggered alert as open again.

#### Use this when

You want to clear a stale firing that's already handled, or reopen one that was resolved prematurely.

#### Required

* `slug` application slug
* `mode` beta, production, staging, alpha, qa, development
* `ulid` triggered-alert id (from `read_incidents` `list`)
* `action` — `resolve` or `reopen`

#### Usage Examples

* “Resolve this incident.”
* “Reopen that alert firing.”

***

## Common Parameters

Most tools share these parameters:

| Parameter             | Type    | Description                                                                |
| --------------------- | ------- | -------------------------------------------------------------------------- |
| `slug`                | string  | Application slug (from `list_applications`)                                |
| `mode`                | string  | Environment: `production`, `beta`, `staging`, `alpha`, `qa`, `development` |
| `limit`               | integer | Results per page (varies by tool; commonly default 20, max 50)             |
| `offset`              | integer | Pagination offset                                                          |
| `filters.date_ms.gte` | integer | Start timestamp in milliseconds                                            |
| `filters.date_ms.lte` | integer | End timestamp in milliseconds                                              |

***

## Pagination

List tools support `limit` and `offset` parameters for pagination:

* **Default page size:** 20 results (10 for `list_applications` and `list_reviews`; 50 for `read_incidents`)
* **Maximum page size:** 50 results for most list tools (100 for `read_incidents`)
* Use `offset` to fetch subsequent pages (e.g., `offset: 20` for the second page)
* Some occurrence/APM tools use cursor-based pagination (`current_token` + `direction`) instead of `offset`

Your AI assistant handles pagination automatically when you ask for more results. For example:

> “Show me the next 20 crashes”

***

## Error Handling

The server returns standard HTTP statuses with a JSON-RPC error envelope. The main cases:

| HTTP  | JSON-RPC code | Meaning                 | Common cause                                                                                                     |
| ----- | ------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `401` | `-32600`      | Authentication required | No credentials sent (no Bearer token and no `Email`/`Token` headers)                                             |
| `401` | `-32701`      | Invalid credentials     | Token expired, revoked, or wrong; OAuth session no longer valid                                                  |
| `403` | `-32702`      | Unauthorized role       | Your role lacks MCP access, or lacks the specific permission a tool needs (message names the missing permission) |
| `403` | `-32703`      | Plan restricted         | The tool's product isn't included in your plan (e.g. APM, Surveys, Crash Reporting)                              |
| `429` | —             | Rate limited            | Too many requests, wait and retry                                                                                |

Some failures come back as a **tool result** marked as an error rather than a protocol error, for example `Application with slug '<slug>' and mode '<mode>' not found or not accessible` (wrong slug/mode or no access to that app), or `Failed to fetch data: <detail>` when an upstream request is rejected (the message describes what to fix). Transient server-side issues return a generic "please try again later" message.

***

## Rate Limits

* Requests are rate-limited per client (by IP). The default limit is **100 requests per 60 seconds**.
* If you hit the limit you get a `429` with `Rate limit exceeded`, wait briefly and retry.

For more details, see [Authentication & Security](/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/authentication-and-security.md#rate-limits).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.luciq.ai/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/mcp-tools-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.