User Guide

Built-in Prompts

Built-in prompts

In addition to the 30 tools, the Single Origin MCP server ships with five 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.

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.