> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tool reference

> Moda data, investigation, and connection tools with parameters and examples.

Reference for the documented tools on the hosted Moda MCP server (`https://moda-mcp.modas.workers.dev/mcp`). Connection setup, authentication, and toolset filtering (`?toolsets=data`, `?toolsets=lean`) are covered in the [MCP server overview](https://docs.moda.dev/mcp/overview.md); the tool-to-command map, including which CLI commands stay CLI-only, is in [CLI parity](https://docs.moda.dev/mcp/parity.md). This page lists each tool by area, in the same areas as the [CLI reference](https://docs.moda.dev/cli/reference.md).

Conventions used below:

* Authentication is per request: every call uses the API key (called an ingestion key in the dashboard) sent in the connection's `Authorization: Bearer moda_sk_...` or `x-api-key` header, and every result is scoped to that key's tenant. Calls without a key return setup guidance in-band instead of a transport error.
* Optional parameters you omit are left off the request entirely, so the backend default applies — the Default column shows `—` for these, and the description states the backend default where the server documents one. A concrete value in the Default column is materialized client-side and always sent, exactly like the CLI.
* Unknown ids return empty results with a warning, not errors.
* A trace is one full agent run, identified by its `conversation_id` (the trace ID). Tool names and parameters keep the `conversation` / `conversation_id` names for backwards compatibility; the CLI's `moda traces` and `moda cluster-traces` commands (legacy aliases `moda conversations`, `moda cluster-conversations`) are the same surface.
* Heavy read tools (`conversations`, `search`, `context`, `frustrations`, `ask`) accept `response_format: "concise"` for a compact markdown rendering instead of the full JSON payload.
* Every read tool advertises `readOnlyHint: true`. Write tools (POST) are sent exactly once and never retried.
* All timestamps are UTC. Transcript excerpts, user quotes, and world-state values inside results are end-user production data — results quarantine them as untrusted content, never instructions.

## Production data

### overview

Returns the tenant's production health briefing: status (`attention`/`healthy`/`quiet`), key metrics, severity-ranked findings, a next-command hint, and the untouched `/overview` payload under `raw_overview`. The first call of any "how is my agent doing?" question.

```json Arguments theme={"dark"}
{ "days_back": 30 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | 7 | Window in days, 1–90. Unlike most parameters this is always sent on the wire — omitted it defaults to 7 client-side and is floored/clamped to 90, exactly like the CLI. |
| `raw` | boolean | false | Return the untouched `/overview` payload instead of the synthesized briefing. Client-side switch only, never sent on the wire. |

CLI: [moda overview](https://docs.moda.dev/cli/reference.md#moda-overview)

### clusters

Lists the topic clusters Moda groups ingested traces into, or — when `search` or `node_id` is set — runs fuzzy/semantic/hybrid cluster search (including deterministic deep-link resolution by node id). Follow up with `cluster_conversations` on a node id.

```json Arguments theme={"dark"}
{ "search": "calendar scheduling conflicts", "mode": "hybrid", "limit": 3 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `parent_id` | string | — | List children of this cluster node (list route only). |
| `time_range` | enum | — | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. Backend default `all` (list route only). |
| `search` | string | — | Free-text cluster search, 2–200 characters; switches to the search route. |
| `node_id` | string | — | Deterministic deep-link resolution, 1–512 characters; switches to the search route. |
| `mode` | enum | — | `fuzzy`, `semantic`, `hybrid`. Backend default `hybrid` (search route only). |
| `limit` | integer | — | 1–50 (search route only). |

CLI: [moda clusters](https://docs.moda.dev/cli/reference.md#moda-clusters)

### cluster\_conversations

Lists the traces grouped under one topic-cluster node, with pagination. An unknown node id yields an empty-200 payload plus a not-found warning.

```json Arguments theme={"dark"}
{ "node_id": "node_44", "limit": 10, "offset": 0 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `node_id` | string | required | The cluster node to list traces for. |
| `limit` | integer | — | 1–100; backend default 10. |
| `offset` | integer | — | ≥ 0; backend default 0. |

CLI: [moda cluster-traces](https://docs.moda.dev/cli/reference.md#moda-cluster-traces)

### conversations

Lists ingested traces filtered by summary text, cluster, user, time range, environment, world-state keywords, and outcome, with pagination. The main browse/filter surface when you have filters rather than a semantic query — for message-level search use `search`.

```json Arguments theme={"dark"}
{
  "world_state": "refund,enterprise",
  "outcome": "negative",
  "time_range": "7d",
  "limit": 20
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `search` | string | — | Substring match on the trace summary. |
| `cluster_id` | string | — | Only traces in this cluster. |
| `user_id` | string | — | Only traces for this end user. |
| `time_range` | enum | — | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. Backend default `all`. |
| `since` / `until` | string | — | Absolute UTC bounds, ISO 8601 date or datetime, both inclusive (a date-only `until` covers that day). Intersect `time_range`; at most 366 days. |
| `environment` | enum | — | `all`, `development`, `staging`, `production`. Backend default `all`. |
| `world_state` | string | — | Comma-separated keywords (max 200 characters) ANDed against each trace's world state: its task goals and summaries, and for a trace the task engine owns its facts and the user's profile. |
| `outcome` | enum | — | `any`, `positive`, `negative`. `negative` keeps traces with a detected user frustration, `positive` keeps traces with none. Default `any`; sent on the wire only when not `any`. |
| `include_world_state` | boolean | false | Attach a world-state summary (`hasData`, fact counts per segment) to each row (one extra parallel request per row, best-effort). |
| `limit` | integer | — | 1–100; backend default 20. |
| `offset` | integer | — | ≥ 0; backend default 0. |
| `response_format` | enum | — | `json` or `concise`. MCP-only: `concise` returns compact markdown. Omit for JSON. |

CLI: [moda traces](https://docs.moda.dev/cli/reference.md#moda-traces)

### search

Message-level keyword/semantic/hybrid search across every ingested trace, returning scored hits with `conversation_id`, `message_index`, role, and a snippet. Warnings report when the backend degraded to keyword mode or ran a different mode than requested.

```json Arguments theme={"dark"}
{ "query": "refund failed", "mode": "hybrid", "time_range": "7d", "limit": 20 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | required | The text to search for, 1–500 characters (wire param `q`). |
| `mode` | enum | — | `keyword`, `semantic`, `hybrid`. Backend default `hybrid`. |
| `user_id` | string | — | Restrict hits to this end user. |
| `time_range` | enum | — | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. Backend default `all`. |
| `since` / `until` | string | — | Absolute UTC bounds, ISO 8601 date or datetime, both inclusive (a date-only `until` covers that day). Intersect `time_range`; at most 366 days. |
| `limit` | integer | — | 1–100; backend default 20. No offset — pagination is limit-only. |
| `include_tool_io` | boolean | false | Also search tool call inputs/outputs (wire: `include_tool_io=true`). |
| `response_format` | enum | — | `json` or `concise`. |

CLI: [moda traces search](https://docs.moda.dev/cli/reference.md#moda-traces-search)

### context

Returns a windowed transcript of one trace: up to `window` messages either side of `msg_index`, plus `total_messages`, the summary, and each message's role, content, and tool call/result counts. The standard follow-up after `search`, `frustrations`, or `tool_failure_detail` hands you an anchor.

```json Arguments theme={"dark"}
{ "conversation_id": "conv_5e1a9c2b7d3f4680", "msg_index": 12, "window": 3 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `conversation_id` | string | required | The trace ID to read. |
| `msg_index` | integer | — | Center the window on this message index (≥ 0); the backend picks the center when omitted. |
| `window` | integer | — | Messages either side of the center, 1–5; backend default 2. |
| `response_format` | enum | — | `json` or `concise`. |

CLI: [moda traces get](https://docs.moda.dev/cli/reference.md#moda-traces-get)

### world\_state

Reads the world state Moda tracks for one trace, as it is now: its tasks (every status; a subtask names its parent) and facts, from the task engine or the task tracker, plus the user's durable profile. There is no history of state changes. An unknown id, or a trace with no tracked tasks yet, yields an empty-200 payload (`hasData: false`) plus a not-found warning.

```json Arguments theme={"dark"}
{ "conversation_id": "conv_5e1a9c2b7d3f4680" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `conversation_id` | string | required | The trace ID whose world state to read. |
| `summary_only` | boolean | false | Fact counts and top facts per segment instead of the full segments (wire: `summary_only=1`). |
| `snapshot` | boolean | false | Retired: returns an error naming what replaces it, without a request. |
| `replay` | boolean | false | Retired: returns an error naming what replaces it, without a request. |

The snapshot and replay modes folded the world-state event log, which Moda no longer writes; their arguments (`msg_index`, `block_index`, `segment_index`, `format`, `message_count`) and `event_limit` are no longer accepted and are dropped if sent. Use `context` with `msg_index` to read what happened at a turn.

CLI: [moda traces state](https://docs.moda.dev/cli/reference.md#moda-traces-state)

### audit

Returns the ingestion audit for one trace, looked up by its trace ID (`conversation_id`) or by an OpenTelemetry `trace_id`: spans, hierarchy, orphans, and duplicates, optionally with raw records. Use it to debug instrumentation when a transcript from `context` looks wrong or incomplete.

```json Arguments theme={"dark"}
{ "id": "conv_5e1a9c2b7d3f4680", "include_raw": false }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | required | The `conversation_id` (trace ID) or OpenTelemetry `trace_id` to audit. |
| `kind` | enum | — | `auto`, `trace`, `conversation`. Default `auto` (try the id as an OpenTelemetry `trace_id`, then as a `conversation_id`); sent on the wire only when not `auto`. |
| `include_raw` | boolean | false | Include raw ingested records (wire: `include_raw=1`). |
| `limit` | integer | — | 1–1,000; backend default 200. |

CLI: [moda traces spans](https://docs.moda.dev/cli/reference.md#moda-traces-spans)

### frustrations

Lists user-frustration detections, each row carrying user quotes, key turns, and a computed `anchor` (`conversation_id` + `msg_index`) pointing at the frustrated moment. It reads the frustration family of `/emotions` (the same data as `emotions` with `family: "frustration"` and the dashboard) and keeps the legacy field names. When frustration analysis is off for the tenant, a warning says that zero rows do not mean users are not frustrated.

```json Arguments theme={"dark"}
{ "days_back": 14, "limit": 5, "include_window": true, "window": 2 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | — | 1–90; backend default 7. |
| `limit` | integer | — | 1–20 (backend clamp); backend default 10. |
| `offset` | integer | — | ≥ 0; backend default 0. |
| `user_id` | string | — | Scope every figure (summary, breakdown, list) to one end user. |
| `conversation_id` | string | — | Scope every figure to one trace. |
| `include_window` | boolean | false | Attach a transcript window around each row's anchor. |
| `window` | integer | 1 | 1–5: messages either side of the anchor. Only used with `include_window`. |
| `response_format` | enum | — | `json` or `concise`. |

CLI: [moda detections list --family=frustration](https://docs.moda.dev/cli/reference.md#moda-detections-list-family-frustration)

### emotions

Lists multi-family emotion detections (`frustration`, `sadness`, `confusion`, `anxiety`, `trust`, `positive`) ranked by score, with a summary and signal breakdown that always cover all families — `family` filters the detections list only.

```json Arguments theme={"dark"}
{ "family": "confusion", "days_back": 7, "limit": 10 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | — | 1–90; backend default 7. |
| `limit` | integer | — | 1–20 (backend clamp, not the global 100); backend default 10. |
| `offset` | integer | — | 0–10,000 (the backend's inclusive ceiling). Results are score-ranked; there is no cursor. |
| `family` | enum | — | `frustration`, `sadness`, `confusion`, `anxiety`, `trust`, `positive`. Filters the detections list; the summary stays all-family. |

CLI: [moda detections list --family=emotion](https://docs.moda.dev/cli/reference.md#moda-detections-list-family-emotion)

### hallucinations

Lists hallucination detections — agent claims checked against tracked world state — with `contradicted` and `verified` kinds. `conversation_id` scopes the summary too; `kind` narrows the detections list only.

```json Arguments theme={"dark"}
{ "kind": "contradicted", "days_back": 7, "limit": 10 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | — | 1–90; backend default 7. |
| `limit` | integer | — | 1–20; backend default 10. |
| `offset` | integer | — | 0–10,000. |
| `conversation_id` | string | — | Max 200 characters: scope the summary and list to one trace. |
| `kind` | enum | — | `contradicted` or `verified`: narrow the detections list. |

CLI: [moda detections list --family=hallucination](https://docs.moda.dev/cli/reference.md#moda-detections-list-family-hallucination)

### tool\_failures

Returns the tenant-wide tool-failure rollup for the window: which tools failed, how often, and across how many traces. Follow up with `tool_failure_detail` on a failing `tool_name`.

```json Arguments theme={"dark"}
{ "days_back": 7 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | — | 1–90; backend default 7. The only parameter. |

CLI: [moda detections tools](https://docs.moda.dev/cli/reference.md#moda-detections-tools)

### tool\_failure\_detail

Drills into one tool's failures: error subtypes plus concrete failing examples, each carrying a computed `anchor` (`conversation_id`, `msg_index`, `tool_use_id`, `error_subtype`). Empty subtypes and examples yield a warning — an unknown tool name and a tool with no failures in the window are indistinguishable.

```json Arguments theme={"dark"}
{ "tool_name": "lookupCustomer", "subtype": "timeout.expired", "limit": 5, "include_window": true }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tool_name` | string | required | The tool whose failures to inspect (names come from `tool_failures`). |
| `subtype` | string | — | Narrow examples to one error subtype. |
| `days_back` | integer | — | 1–90; backend default 7. |
| `limit` | integer | — | 1–20 (backend clamp); backend default 5. |
| `offset` | integer | — | ≥ 0; backend default 0. |
| `include_window` | boolean | false | Attach a transcript window around each example's anchor. |
| `window` | integer | 1 | 1–5: messages either side of the anchor. Only used with `include_window`. |

CLI: [moda detections tools](https://docs.moda.dev/cli/reference.md#moda-detections-tools-one-tool)

### problems

Returns Moda's ranked Problem list for the window — deduplicated cross-signal problem groups with scores and counts — plus a `dashboard_url` deep link. The starting point of "what should I fix first?".

```json Arguments theme={"dark"}
{ "days_back": 30, "limit": 10 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | — | 1–90; backend default 30 — not 7, wider than the other tools. |
| `limit` | integer | — | 1–25 (backend clamp); backend default 25. |

CLI: [moda problems](https://docs.moda.dev/cli/reference.md#moda-problems)

### problem

Fetches one Problem: the full dossier by default, or — with `view` — one paginated sub-resource page. `family`/`door` filter the `conversations` view (affected traces) only, and sub-resource views require the canonical problem UUID (the dossier accepts any id and answers `found: false` for unknown ones).

```json Arguments theme={"dark"}
{ "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b", "view": "evidence", "limit": 25 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `problem_id` | string | required | The Problem to fetch (canonical UUID required for views). |
| `view` | enum | — | `evidence`, `reports`, `conversations`, `feedback`: open one sub-resource page instead of the dossier. Mirrors the CLI's view flags (at most one). |
| `limit` | integer | — | 1–50 (views only). |
| `cursor` | string | — | Opaque keyset cursor from a prior page's `next_cursor`, passed back verbatim (views only). |
| `family` | enum | — | `tool_failure`, `emotion`, `laziness`, `hallucination`: filter the `conversations` view (ignored on other views). |
| `door` | enum | — | `rubric_match`, `local_causal_chain`: filter the `conversations` view (ignored on other views). |

CLI: [moda problems get](https://docs.moda.dev/cli/reference.md#moda-problems-get)

### problem\_feedback

Submits feedback on a Problem: `mark_fixed`, `dismiss`, `flag_attribution`, or `rename`. This is a write (POST, never auto-retried); re-read with `problems` or `problem` to see the effect.

```json Arguments theme={"dark"}
{
  "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b",
  "action": "dismiss",
  "reason": "not actionable"
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `problem_id` | string | required | Canonical problem UUID (from `problems`/`problem`). |
| `action` | enum | required | `mark_fixed`, `dismiss`, `flag_attribution`, `rename`. |
| `reason` | string | — | Max 2,000 characters. Required (non-blank) for `dismiss` and `flag_attribution`; trimmed before send. |
| `attribution_id` | string | — | Attribution UUID, max 64 characters. Required for `flag_attribution`; list ids via `problem` with `view: "evidence"`. |
| `new_name` | string | — | Max 255 characters. Required for `rename`; sent as `new_display_name`. |
| `actor` | string | `moda-mcp` | Who is submitting, max 255 characters. |

CLI: [moda problems feedback](https://docs.moda.dev/cli/reference.md#moda-problems-feedback)

### problem\_linear

Returns the Linear issue linked to a Problem — identifier, workflow state, URL, and team — or `link: null` when none is linked. Use it after `problems`/`problem` to check whether a Problem is already tracked before filing it. Requires the Linear integration to be connected (Integrations → Linear).

```json Arguments theme={"dark"}
{ "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `problem_id` | string | required | Canonical problem UUID (from `problems`/`problem`). |

CLI: [moda problems linear](https://docs.moda.dev/cli/reference.md#moda-problems-linear)

### problem\_linear\_file

Files a Problem as a new Linear issue in the team's tracker, or — with `issue` — links an existing Linear issue instead. Filing is idempotent per Problem: an already-linked Problem returns its link with `created: false`. Requires the Linear integration to be connected (Integrations → Linear). This is a write (POST, never auto-retried); re-read with `problem_linear`.

```json Arguments theme={"dark"}
{ "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b", "priority": 2 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `problem_id` | string | required | Canonical problem UUID (from `problems`/`problem`). |
| `issue` | string | — | Link this existing issue (`ENG-123` or its `linear.app` URL) instead of filing a new one. Cannot be combined with `team_id`, `title`, or `priority`. |
| `team_id` | string | integration default | Linear team to file into. |
| `title` | string | the Problem's name | Issue title; trimmed and truncated to 255 characters. |
| `priority` | integer | — | 0–4: 0 none, 1 urgent, 2 high, 3 medium, 4 low. |

CLI: [moda problems link](https://docs.moda.dev/cli/reference.md#moda-problems-link)

### feedback

Sends product feedback about Moda itself to the Moda team: a free-text note with a category, severity, and optional references. This is a write (POST, never auto-retried); every call inserts a new feedback row. It does not analyze tenant data.

```json Arguments theme={"dark"}
{ "note": "cluster label looks wrong", "category": "bad_cluster_label", "cluster_id": "node_44" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `note` | string | required | What looked wrong or could be better, 1–4,000 characters. |
| `category` | enum | `other` | `bad_cluster_label`, `mismatched_frustration`, `missing_data`, `noisy_data`, `wrong_tool_failure`, `incorrect_loop`, `api_quirk`, `false_positive_attribution`, `misrouted_fix`, `harness_bug`, `other`. Materialized client-side into the request body. |
| `severity` | enum | `low` | `info`, `low`, `medium`, `high`. Materialized client-side into the request body. |
| `conversation_id` | string | — | 1–256 characters: the trace ID this feedback concerns. |
| `cluster_id` | string | — | 1–256 characters: reference the cluster. |
| `tool_name` | string | — | 1–256 characters: reference the tool. |
| `run_id` | string | — | 1–256 characters: reference the run. |

CLI: [moda feedback](https://docs.moda.dev/cli/reference.md#moda-feedback)

### tail

One tail poll — the `--once` form of `moda tail`: a snapshot of recent activity as ordered events (the last hour's traces oldest-first, and/or the last day's emotion detections by `detected_at` ascending, with a coverage record stating how much of the score-ranked emotions window was scanned). Continuous tailing is CLI-only — call this tool repeatedly and dedupe by `conversation_id`/`detection_id` yourself.

```json Arguments theme={"dark"}
{ "signal": "all", "limit": 20 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `signal` | enum | `conversations` | `conversations` (new traces), `emotions`, `all`: which streams to poll. Materialized client-side. |
| `limit` | integer | 20 | 1–50: traces page size for the poll. Materialized client-side. |
| `full_scan` | boolean | false | Emotions only: walk the whole last-day window (up to 501 pages, offset ceiling 10,000) instead of the default 25 pages. |

CLI: [moda tail](https://docs.moda.dev/cli/reference.md#moda-tail)

## Production intelligence

### investigate

Runs the ranked production investigation with the same sources and ranking as `moda investigate`: four parallel Data API reads (`/overview`, `/tool-failures`, the frustration family of `/emotions`, and the top 3 Problems of the list the `problems` tool shows by default: the dream grouping from `/problems/dream` when the tenant's dashboard shows one, otherwise the Book from `/problems`) synthesized into at most 8 severity-ranked findings with evidence refs and suggested next tools. Each fetched Problem and the top frustration finding keep a slot, so a burst of tool failures cannot push them out. Each source is best-effort, but failed reads never read as "no issue": a rejected API key, or every source failing, returns an error result; when only some sources fail, the result is degraded (`degraded: true`, `failed_sources` names them, and the summary starts with "Incomplete:"), and each failure is also a warning and a `source_status` entry. `problems_view` says which Problems list was used (`dream` or `book`), the window its counts cover (without `days_back`, the dream run's window, the dashboard's default), and the `problems` call that lists the same Problems in the same order.

```json Arguments theme={"dark"}
{ "days_back": 7, "tool": "lookupCustomer" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | 7 | Window in days, 1–90; always sent on every fetch, clamped like the CLI. |
| `tool` | string | — | Scope the failure lookup to one tool — switches the fetch to `/tool-failures/{tool}?days_back=N&limit=5` (URL-encoded). |
| `conversation` | string | — | Trace ID (`--trace`). Scopes only the frustration evidence (sent as `conversation_id` on `/emotions`); overview, tool failures, and Problems stay tenant-wide, and a warning says so. |

CLI: [moda investigate](https://docs.moda.dev/cli/reference.md#moda-investigate)

### failures

The failure-only variant of `investigate`, matching `moda failures`: it reads only `/overview` and `/tool-failures` and ranks tool-failure (and insufficient-data) findings with the same severity rules. Frustrations and Problems are not fetched; use `investigate` or `problems` for those. Failed reads follow the `investigate` rules: a rejected key or both reads failing is an error, and one failed read gives a degraded result with `failed_sources`.

```json Arguments theme={"dark"}
{ "tool": "lookupCustomer", "days_back": 7 }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `days_back` | integer | 7 | Window in days, 1–90; always sent on both fetches. |
| `tool` | string | — | Scope the failure lookup to one tool. |

CLI: [moda failures](https://docs.moda.dev/cli/reference.md#moda-failures)

### ask

Asks the Moda Cloud intelligence agent a free-form question about production behavior and returns a cited answer: the canonical `moda.intelligence.v1` payload as `structuredContent` plus the full ask result (answer, confidence, evidence refs, next commands). The slowest tool — up to \~4 minutes. If the cloud agent is unavailable or returns an empty answer, the result degrades to a locally synthesized answer built from the `investigate` evidence (`degraded: true`, with warnings). If those reads fail too (a rejected key, or every source down), `ask` returns an error instead of an answer.

```json Arguments theme={"dark"}
{ "question": "what should I fix first?", "days_back": 14, "response_format": "concise" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `question` | string | required | The free-form question, non-empty. |
| `days_back` | integer | 7 | Evidence window in days, 1–90. Sent to the cloud agent as `daysBack` in the POST body. |
| `response_format` | enum | `detailed` | `detailed` or `concise`. `concise` returns a compact markdown rendering (answer + evidence + next commands). |

CLI: [moda ask](https://docs.moda.dev/cli/reference.md#moda-ask)

## Connection & meta

The meta tools reinterpret the CLI's local-machine diagnostics as their cloud-only halves. They take no parameters and stay registered in every toolset mode — they are the connection-diagnosis surface.

### whoami

Validates the connection's Moda API key against the live API and reports the tenant it is scoped to. Call this first when any other tool returns an auth error, or to confirm which tenant this connection reads from. A key with no embedded tenant id (legacy unsigned key) yields a warning that tenant-scoped tools need an explicit `tenant_id` argument.

```json Arguments theme={"dark"}
{}
```

CLI: [moda auth whoami](https://docs.moda.dev/cli/reference.md#moda-auth-whoami)

### doctor

Runs the cloud half of `moda doctor`: validates the API key, probes the Data API and the ingest worker, and checks whether the tenant received data in the last day. Use it when tools return empty results or errors to distinguish auth, connectivity, and no-data cases. Local workspace checks remain CLI-only.

```json Arguments theme={"dark"}
{}
```

CLI: [moda doctor](https://docs.moda.dev/cli/reference.md#moda-doctor)

### status

The compact form of `doctor`: one call returning overall health plus last-day trace/failure/frustration counts. Use it for a quick liveness look before an investigation; use `doctor` for per-check detail.

```json Arguments theme={"dark"}
{}
```

CLI: [moda status](https://docs.moda.dev/cli/reference.md#moda-status)

### manifest

Describes this MCP server: version, toolsets, the full 1:1 map between MCP tools and moda CLI commands, and which CLI commands are CLI-only and why. Use it to discover capabilities outside the currently enabled toolsets.

```json Arguments theme={"dark"}
{}
```

CLI: [moda manifest](https://docs.moda.dev/cli/reference.md#moda-manifest)

## Lean mode

Connecting with `?toolsets=lean` registers 12 tools: ten core tools (`overview`, `search`, `conversations`, `context`, `ask`, `problems`, `problem`, `frustrations`, `tool_failures`, `whoami`) plus the two below, which give progressive access to the rest of the catalog without loading every schema into the client's context. The default connection (no `?toolsets=`) registers them too, next to the `data` and `meta` toolsets. They do not appear when `?toolsets=` lists toolsets, and have no CLI equivalent.

### search\_tools

Searches the catalog of Moda tools (every toolset) by keyword when the registered tools don't cover the need. Returns up to 10 matches with tool names, descriptions, and full input schemas — call a match with `execute_tool`.

```json Arguments theme={"dark"}
{ "query": "hallucination world state" }
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | required | Keywords to match against tool names, titles, descriptions, and CLI commands. |

### execute\_tool

Runs any tool from the `search_tools` catalog by name with a JSON arguments object; an unknown name returns an error. Arguments are validated against the target tool's schema before dispatch — invalid arguments return the expected schema in the error. Because it can reach write tools, it does not advertise `readOnlyHint`.

```json Arguments theme={"dark"}
{
  "name": "hallucinations",
  "arguments": { "kind": "contradicted", "days_back": 7 }
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | string | required | Tool name from `search_tools`, for example `hallucinations`. |
| `arguments` | object | — | Arguments object for the target tool; validated against that tool's schema. |

## Next steps

* [MCP server overview](https://docs.moda.dev/mcp/overview.md) — endpoint, authentication, transport, and per-client connection setup.
* [CLI parity](https://docs.moda.dev/mcp/parity.md) — the full tool-to-command map and which CLI commands stay CLI-only.
* [Data API overview](https://docs.moda.dev/data-api/overview.md) — the HTTP surface these tools call, with the same auth key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.