# Issues

The triage queue over MCP. An issue clusters the observed occurrences of one underlying gap, detected from real conversations and failing evals. It is the same queue the web app's review page shows.

## list\_issues

The prioritized queue: impact first, then recurrence.

| Name | Type | Notes |
| --- | --- | --- |
| `project_id` | UUID, required | The project whose issues to list |
| `status` | enum | `open` (the default, and the triage queue), `resolved`, `dismissed`, or `all` |

Each entry carries `{id, title, description, cause, impact, status, occurrence_count, first_seen_at, last_seen_at, fix_proposal}`.

| Field | Values | Meaning |
| --- | --- | --- |
| `cause` | `ontology_gap`, `missing_data` | How to fix it: edit the ontology, or expose data the ontology does not carry yet |
| `impact` | `wrong_answer`, `unreliable_answer`, `no_answer`, `inefficient` | The observed consequence, in severity order |
| `fix_proposal` | `{kind, summary}` | The derived recommendation, or null when not computed. `get_issue` returns it in full |

## get\_issue

One issue in full: its clustered occurrences and the derived fix proposal. Parameters: `project_id`, `issue_id`. Returns the `list_issues` fields plus `suggested_action`, `occurrences`, and the full `fix_proposal`.

Each occurrence is one evidence point, a conversation or a failing eval: the user’s question, the observed symptom, the extractor’s diagnosis, an evidence excerpt, categorical signals (user rating, judge verdict, status), the ontology objects involved, and the resolution the user gave in-thread when they gave one.

Read the occurrences before deciding. Triage quality drives ontology quality.

### The three kinds of fix proposal

| Kind | What it means |
| --- | --- |
| `apply_resolution` | `mutations` are concrete ontology operations implementing the fix, each a bare `{tool, input}` pair (`create_metric`, `update_column`, and so on), with `fix_preview` describing them. They are a structured description of the fix, not an edit: make the equivalent change in the ontology repository |
| `reference_tables` | `tables` are unmapped warehouse tables that likely supply the missing data. Inspect them with [`get_source_schema`](/reference/mcp/source-schema/) before modeling them |
| `manual` | No automatic fix. `triage_reason` explains why |

## get\_issue\_evidence

The full evidence behind one occurrence, joined back from its source. Use it when the extracted fields are not enough to judge an issue. Parameters: `project_id`, `issue_id`, `occurrence_id`.

Which fields come back depends on `source_type`. A `chat_message` occurrence carries the generated SQL, the result rows, the assistant’s answer, and the user’s rating with comment. An `eval_run_result` occurrence carries the generated SQL, the judge verdict with its reasoning, and expected versus actual output. Both carry the agent’s process log. Every payload is truncated server-side.

## update\_issue\_status

Sets an issue’s triage disposition. This is the server’s only write tool, and it requires the editor or admin role.

| Name | Type | Notes |
| --- | --- | --- |
| `project_id` | UUID, required | The project the issue belongs to |
| `issue_id` | UUID, required | The issue to update |
| `status` | enum, required | `resolved` (the underlying gap has been fixed), `dismissed` (deliberately not acting on it), or `open` (reopens a resolved or dismissed issue) |

**Resolving records an outcome, it does not change the ontology.** Resolve only once the gap is actually addressed: the ontology edited through the project’s edit surface, or the missing data wired up. Dismiss issues you deliberately will not act on (noise, duplicate, obsolete), and when unsure leave the issue open. Editing an issue’s title or description is web-app only.

The loop a person or agent runs around these four tools is in [Curate a git-managed project](/curate/agent/).