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