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 | The project whose issues to list. Optional with an API key scoped to one project, which it defaults to |
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, domains, pr_mention}.
| Field | Values | Meaning |
|---|---|---|
cause | ontology_gap, missing_data | How to fix it: edit the context, or expose data the context 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 |
domains | context domain paths | The domains the issue’s occurrences point at, most-referenced first. Empty when nothing maps to a modeled table |
pr_mention | Resolves <id> | The line to write in the description of the pull request that fixes the issue. Merging that PR resolves it |
get_issue
One issue in full: its clustered occurrences and the derived fix proposal. Parameters: project_id (optional with an API key scoped to one project), issue_id. Returns the list_issues fields plus suggested_action, occurrences, and the full fix_proposal.
An open issue also carries next_step, what to do with it from here. A closed one carries resolved_via (manual, fix_proposal, fix_chat_merge, pr_mention) and resolved_ref, the pull request URL when it came through one.
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 context objects involved, and the resolution the user gave in-thread when they gave one.
Read the occurrences before deciding. Triage quality drives context quality.
The three kinds of fix proposal
| Kind | What it means |
|---|---|
apply_resolution | mutations are concrete context 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 context 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 (optional with an API key scoped to one project), 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.
Closing an issue from a pull request
When the fix ships as a pull request, do not call update_issue_status after publication. Write the issue’s pr_mention line, Resolves <id>, in the pull request description instead: Cassis resolves the issue when the PR merges, on any branch of the connected repository. Closes and Fixes work the same way, and the id’s first 13 characters are enough. One description can carry a mention per issue the change fixes.
The issue then records resolved_via: pr_mention and the pull request in resolved_ref, so the trail from issue to change survives.
update_issue_status
Sets an issue’s triage disposition, for the outcomes that do not go through a pull request. This is the server’s only write tool, and it requires the editor or admin role.
| Name | Type | Notes |
|---|---|---|
project_id | UUID | The project the issue belongs to. Optional with an API key scoped to one project, which it defaults 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) |
reason | enum | Required when dismissing: invalid, irrelevant, duplicate, or declined |
detail | string | Optional context for a dismissal |
confirm_published | boolean | Required as true for manual resolution; confirms the fix is in a published context |
Resolving records an outcome, it does not change the context. Resolve only once the gap is actually addressed and published. Dismiss issues you deliberately will not act on, preserve why with reason, 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.