Built-in prompts

In addition to the tools, the Single Origin MCP server ships with seven pre-written prompts. They're invoked from your client's prompt palette (in Claude Code, as /singleorigin:<prompt-name>) and orchestrate the right sequence of tool calls for the most common workflows — so your agent doesn't have to figure them out from scratch.

list_recommendations

Surveys the workspace's current optimization opportunities and prints them, sorted by estimated daily savings, in a consistent block format with full IDs and query signatures — then offers to page further or review a specific one.

When to use: a weekly optimization review, a kickoff "what should we work on this sprint?" conversation, or anyone asking "where are we wasting compute?"

Sample invocation

/singleorigin:list_recommendations

What the agent does

1. Calls list_recommendations (page 0).
2. Renders each recommendation as a block — ID, title, type, status, processing time, estimated daily savings, and query signatures.
3. Offers two next steps: view the next page, or review one with /singleorigin:review_recommendation {ID}.

review_recommendation

Walks through a single recommendation end-to-end: its details, the SQL change it implies, the top target queries by cost, and a confidence assessment of whether the recommendation actually applies.

When to use: before acting on a recommendation — get a structured second opinion that pulls together the underlying queries and DDL.

Sample invocation

/singleorigin:review_recommendation 9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6

What the agent does

1. Calls get_recommendation for the full payload and get_recommendation_items for per-query impact (already sorted by cost).
2. Displays the recommendation — background, target inefficiency, proposed change, and the top items by cost.
3. Uses query_detail on the top example queries to check whether the described inefficiency actually appears in them and flags possible false positives.
4. Closes with a High / Medium / Low confidence rating, reasoning, and caveats.

similar_query_search

Starts from a single query and finds historical queries with similar operator-tree fragments — so you can tell whether a slow query is a one-off or part of a recurring pattern worth fixing once.

When to use: an engineer flags one slow query and you want to know how widespread its shape is.

Sample invocation

/singleorigin:similar_query_search 01HXY8F3A4B5C6D7E8F9

What the agent does

1. Calls query_detail and query_fragments_for_query for the anchor query, and maps each fragment's operator tree back to the SQL region it came from.
2. Passes each fragment's operator-tree text to search_similar_queries, then dedupes by signature and keeps the top 10 by similarity score.
3. Calls query_detail on each candidate to locate the matching SQL region.
4. Presents results grouped by input SQL region, listing each match's query_id, signature, processing time, and similarity score.

table_scan_analysis

Analyzes a table's scan-cost profile over a date range, detects table→view migrations, and summarizes scan cost and pruning efficiency per query signature.

When to use: "why did scan cost on this table change?", investigating a clustering/migration's effect, or a routine scan-cost health check on a hot table.

Sample invocation

/singleorigin:table_scan_analysis analytics_db.analytics.orders_fact

Optional start_date / end_date arguments narrow the window (it defaults to the last two weeks).

What the agent does

1. Calls resolve_table_reference to determine whether the FQN is a base table or a view (and, for a view, its physical sources and structure).
2. Calls table_scan_cost for the table (and each physical source), using one broad date range.
3. Detects a table→view migration when a now-view FQN still has historical scan cost, and reports the approximate migration date.
4. Renders a pivot table ($scan_cost / pruning% / exec_count per cell) for the top signature + filter-column groups, a per-table breakdown, and each physical table's row count, size, and cluster key.

table_insights

Produces a layered, actionable report on a single table: what to do about it first, the consolidation candidates and why, the stored cluster-key/MV recommendation, and a terse summary of query and column usage.

When to use: the broadest starting point for one table — "tell me everything about analytics.orders_fact", a table-level health check, or a consolidation review before a migration.

Sample invocation

/singleorigin:table_insights analytics_db.analytics.orders_fact

Optional start_date / end_date arguments narrow the window (it defaults to the last two weeks).

What the agent does

1. Calls get_table_insights once — one round trip for metadata, stored recommendations, every similarity axis, readers, producers, and scan cost. It does not re-run the heavy per-table analyses.
2. Derives the action for each consolidation candidate from the build-logic relation — duplicate → drop one and repoint consumers, rollup → build the finer grain once and derive from it, filtered_variant → make it a filtered view off the parent, and so on. On a Spark/Databricks tenant, where the evidence is a plan embedding rather than parsed SQL, there is no verdict: candidates are presented for adjudication instead, with a pointer to the plans.
3. De-duplicates related tables across the axes so a table appearing on several is one row.
4. Adds one call to column_usage_list for used/unused columns, falling back to the scan summary's filter columns when the gRPC backend is unavailable.
5. Layers the report so the two or three things that matter come before any detail — routing to already-generated recommendations rather than deriving its own, and labelling anything heuristic as such.

cluster_key_analysis

Assesses whether a table's existing cluster key is actually earning its keep, from scan cost and pruning efficiency per query signature, and confirms the finding against real query profiles.

When to use: "is our cluster key on this table doing anything?", before changing a cluster key, or when scan cost on a hot table has drifted.

Sample invocation

/singleorigin:cluster_key_analysis analytics_db.analytics.orders_fact

Optional start_date / end_date arguments narrow the window (it defaults to the last two weeks).

What the agent does

1. Calls table_scan_cost with a single broad date range per FQN, paginating rather than making per-date or per-signature calls, and states the range plus how many distinct processing days the data actually covers.
2. Groups scan cost and pruning efficiency by query signature and filter columns to show which workloads the current key does and does not prune for.
3. Confirms the reading against individual query profiles rather than resting on the aggregate.
4. Never infers that a table is deprecated from its name — a _OLD / _TMP / _DO_NOT_USE__ prefix is noted as a possibility at most and never allowed to drive a conclusion.

parse_dag_task_from_signature

Explains how to pull the dag_id and task_id out of a query_signature so queries can be grouped or filtered by their originating Airflow DAG/task.

When to use: the user wants to view, filter, or group queries by DAG or task — e.g. a slow query whose owner is a service account and you need the DAG/task behind it.

Sample invocation

/singleorigin:parse_dag_task_from_signature

What the agent does

Applies the signature format directly — a query_signature is one of "<dag_id> &&& <task_id>||<rel_hash>", "<dag_id> &&& <task_id>", or "<rel_hash>". Whenever &&& is present, the dag_id and task_id are the parts before and after it.