MCP tool reference

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; the tool-to-command map, including which CLI commands stay CLI-only, is in CLI parity. This page lists each tool by area, in the same areas as the CLI reference. 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.

Arguments

{ "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

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.

Arguments

{ "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

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.

Arguments

{ "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

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.

Arguments

{
  "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`.
`environment`	enum	—	`all`, `development`, `staging`, `production`. Backend default `all`.
`world_state`	string	—	Comma-separated keywords (max 200 characters) ANDed against world-state segment slots and the durable profile.
`outcome`	enum	—	`any`, `positive`, `negative`. Default `any`; sent on the wire only when not `any`.
`include_world_state`	boolean	false	Attach a world-state summary 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

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.

Arguments

{ "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`.
`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 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.

Arguments

{ "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 context

world_state

Reads the world state Moda tracked for one trace, in three modes: the default event/summary view, a point-in-time snapshot at a message index, or a frame-by-frame replay. snapshot and replay are mutually exclusive; unknown ids yield an empty-200 payload plus a not-found warning.

Arguments

{ "conversation_id": "conv_5e1a9c2b7d3f4680", "snapshot": true, "msg_index": 42 }

Parameter	Type	Default	Description
`conversation_id`	string	required	The trace ID whose world state to read.
`summary_only`	boolean	false	Omit the per-message event stream (default route only; wire: `summary_only=1`).
`event_limit`	integer	—	1–5,000; backend default 2,000 (default route only).
`snapshot`	boolean	false	Point-in-time snapshot mode.
`msg_index`	integer	0	0–100,000. Snapshot mode; always sent there, defaulting to 0.
`block_index`	integer	—	0–100,000 (snapshot mode only).
`segment_index`	integer	—	0–65,535: scope the fold to one segment (snapshot mode only).
`replay`	boolean	false	Frame replay mode.
`format`	enum	—	`frames` or `fold-inputs` (replay mode; default `frames`). `fold-inputs` travels as `fold_inputs` on the wire.
`message_count`	integer	—	1–1,000,000. Required with `replay` in `frames` mode.

CLI: moda world-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.

Arguments

{ "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 audit

step_scores

Returns Moda’s per-step quality scores for one trace: scored steps and segment rollups. A trace that exists but has not been scored yet returns empty arrays with a warning.

Arguments

{ "conversation_id": "conv_5e1a9c2b7d3f4680" }

Parameter	Type	Default	Description
`conversation_id`	string	required	The trace ID whose step scores to fetch.

CLI: moda step-scores

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. The emotions tool is the multi-family superset of this legacy single-family view.

Arguments

{ "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.
`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 frustrations

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.

Arguments

{ "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 emotions

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.

Arguments

{ "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 hallucinations

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.

Arguments

{ "days_back": 7 }

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

CLI: moda tool-failures

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.

Arguments

{ "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 tool-failure-detail

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?”.

Arguments

{ "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

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

Arguments

{ "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`, `prm_dip`: 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 problem

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.

Arguments

{
  "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 problem-feedback

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.

Arguments

{ "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`, `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

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.

Arguments

{ "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

Production intelligence

investigate

Runs the ranked production investigation: three parallel Data API reads (/overview, /tool-failures, /frustrations) synthesized into severity-ranked findings with evidence refs and suggested next tools. Each source is best-effort — an unavailable endpoint becomes a warning and a source_status entry, never an error.

Arguments

{ "days_back": 7, "tool": "lookupCustomer" }

Parameter	Type	Default	Description
`days_back`	integer	7	Window in days, 1–90; always sent on all three fetches, 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 under investigation; recorded in the output scope only — never sent to the API.

CLI: moda investigate

failures

The failure-only variant of investigate: identical three-source fetch and severity ranking, but frustration findings are excluded so only tool-failure (and insufficient-data) findings remain. The /frustrations fetch still runs and reports its availability in source_status/warnings.

Arguments

{ "tool": "lookupCustomer", "days_back": 7 }

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

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

Arguments

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

search_tools

Searches the complete catalog of Moda tools by keyword when the tools listed in lean mode don’t cover the need. Returns up to 10 matches with tool names, descriptions, and full input schemas — call a match with execute_tool.

Arguments

{ "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 full Moda catalog by name with a JSON arguments object. 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.

Arguments

{
  "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 — endpoint, authentication, transport, and per-client connection setup.
CLI parity — the full tool-to-command map and which CLI commands stay CLI-only.
Data API overview — the HTTP surface these tools call, with the same auth key.

​Production data

​overview

​clusters

​cluster_conversations

​conversations

​search

​context

​world_state

​audit

​step_scores

​frustrations

​emotions

​hallucinations

​tool_failures

​tool_failure_detail

​problems

​problem

​problem_feedback

​feedback

​tail

​Production intelligence

​investigate

​failures

​ask

​Connection & meta

​whoami

​doctor

​status

​manifest

​Lean mode

​search_tools

​execute_tool

​Next steps

Production data

overview

clusters

cluster_conversations

conversations

search

context

world_state

audit

step_scores

frustrations

emotions

hallucinations

tool_failures

tool_failure_detail

problems

problem

problem_feedback

feedback

tail

Production intelligence

investigate

failures

ask

Connection & meta

whoami

doctor

status

manifest

Lean mode

search_tools

execute_tool

Next steps