Work with recommendations
Ask your agent what to fix first, read a recommendation, record what you decided, and check whether it saved money.
Questions you can ask your agent:
- "What are the top Single Origin recommendations right now?"
- "Walk me through recommendation 9c2b1f7e. Is it worth doing?"
- "We shipped the orders_fact fix on May 1. Did it save anything?"
Single Origin analyses your query history every day and stores what it finds as recommendations: query rewrites, cluster keys, materialized views, resource tuning and more. The tools below list them, read one in full, record a person's decision, and read the measured saving.
All sample responses use synthetic data and are shortened.
Statuses
| Status | Meaning |
|---|---|
ACTIVE | Open: nobody has picked it up. |
IN_REVIEW | Someone is looking at it. |
APPLIED | Shipped as proposed. |
APPLIED_VARIANT | Shipped as a different change that serves the same end. |
PARTIALLY_APPLIED | Part of it shipped. |
APPLIED_UNCONFIRMED | Single Origin saw the change and the cost fell, and is waiting for a person to confirm it was this recommendation. Set by Single Origin, not by you. |
IGNORED | Set aside by a person. |
INVALIDATED | Found not to apply. |
PENDING_REFRESH | Waiting to be re-analysed. |
STALE | Nobody moved it for a month. Hidden from the default list but recoverable. Set by Single Origin. |
ARCHIVED | Stale for another month. Set by Single Origin. |
Types
SINGLE_QUERY (one query or job to fix), SIMILAR_QUERY_GROUP (a group of queries with the same shape, fixed together), CLUSTER_KEY_RECOMMENDATION, MV_REWRITE_RECOMMENDATION and RESOURCE_TUNING.
list_recommendations
list_recommendationsLists recommendations, highest estimated daily savings first, 10 per page.
When to use: "What should we work on?", a weekly review, or any time you need recommendation ids.
Parameters
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
page | integer | No | 0 | Zero-based page number. |
statuses | list of strings | No | ["ACTIVE", "IN_REVIEW", "APPLIED_UNCONFIRMED"] | Statuses to include, case-insensitive. Any status from the table above. An unknown name or an empty list is an error. |
types | list of strings | No | all types | Recommendation types to include. |
Returns each recommendation's id, title, type, status, processing_time, estimated_daily_savings and query_signatures, at its latest version. Deleted recommendations are left out. STALE and ARCHIVED are returned only when you name them.
APPLIED_UNCONFIRMED sorts first: it is a question for a person, not work to do. Ask whether the change was theirs, then set APPLIED (or APPLIED_VARIANT / PARTIALLY_APPLIED) or INVALIDATED with update_recommendation.
Results are valid for one hour. After that, call the tool again rather than reusing an old list.
Example
"Show me the top open recommendations."
[
{
"id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6",
"title": "Read only the last 3 days of analytics.orders_fact",
"type": "SINGLE_QUERY",
"status": "ACTIVE",
"processing_time": "2026-05-08T00:00:00Z",
"estimated_daily_savings": 48.2,
"query_signatures": "[\"nightly_revenue &&& load_orders\"]"
}
]get_recommendation
get_recommendationReturns one recommendation in full.
When to use: before acting on a recommendation, or to read what was measured for an APPLIED_UNCONFIRMED one.
Parameters
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
recommendation_id | string (UUID) | Yes | The recommendation's id. |
Returns processing_time, type, id, title, background, status, status_change_reason, is_dismissed, target_inefficiency, target_inefficiency_query_snippet, recommendation, recommendation_query_snippet, estimated_savings_summary, estimated_daily_savings and query_signatures. A deleted recommendation returns an error.
For an APPLIED_UNCONFIRMED recommendation it also returns realized_daily_saving (on the same scale as the estimate) and saving_measured_on. Both are null for other statuses. page is the recommendation's web page, when the server knows the web address.
Example
"Walk me through recommendation 9c2b1f7e."
{
"id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6",
"type": "SINGLE_QUERY",
"status": "ACTIVE",
"title": "Read only the last 3 days of analytics.orders_fact",
"target_inefficiency": "Each run rebuilds the table from all of orders_fact ...",
"recommendation": "Delete and reinsert only the last 3 days ...",
"estimated_daily_savings": 48.2,
"realized_daily_saving": null
}update_recommendation
update_recommendationSets a recommendation's status and the reason for it. Write tool.
When to use: after a person decides what to do with a recommendation: picked up, shipped, rejected or set aside.
Parameters
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
recommendation_id | string (UUID) | Yes | The recommendation's id. | |
processing_time | string (ISO-8601) | Yes | Must match the recommendation's current processing_time. Get it from get_recommendation. | |
status | string | No, but a call without it is an error | none | One of ACTIVE, PENDING_REFRESH, INVALIDATED, IGNORED, IN_REVIEW, APPLIED, APPLIED_VARIANT, PARTIALLY_APPLIED. |
status_change_reason | string | Required for INVALIDATED and IGNORED | none | Why it moved, in the person's own words. Needs status. |
Only the status and reason change. A recommendation's content and savings can't be changed. APPLIED_UNCONFIRMED, STALE and ARCHIVED are set by Single Origin and can't be set here.
The reason travels with the recommendation: when the workload is analysed again, the reason a person gave for turning down the last proposal is carried into the next one. A status set without a reason records no reason; it doesn't keep the previous one.
APPLIED_VARIANT and PARTIALLY_APPLIED count as applied: the recommendation is closed, and a new proposal for the workload gets a new id. Setting any status also shows a recommendation the pipeline had dismissed (is_dismissed: true). Marking a recommendation applied is refused when it has nothing to apply; the error says why.
Example
"Ignore 9c2b1f7e. The table is being retired next month."
{"updated": true, "recommendation_id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6"}recommendation_outcome
recommendation_outcomeReturns the stored measurement of an applied recommendation: the same one the web app's Did this work? tab shows.
When to use: "Did recommendation X work?" Read this before judging a saving yourself.
Parameters
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
recommendation_id | string (UUID) | Yes | The recommendation's id. |
Returns:
recommendation:id,title,status,claimed_daily_savings.measurement: the latest one, or null when none is stored yet. It hasverdictand its meaning (SEEN,NONE,WORSE,WAITING,FELL_BEFORE,STOPPED,STOPPED_OTHER,RESHAPED,NO_COST_DATA,UNMEASURABLE,CONFOUNDED);change_dateandchange_source(DETECTED,MARKED,CONFIRMEDorSEEN);method(JOB_COSTorTABLE_READS);before,after,expected_after,savingandsaving_margin, all per day; the control; days used on each side;caveats; andunmeasured_reason/unmeasured_notewhen nothing is measured yet.checkpoints: the measurements frozen at 7, 30 and 90 days, those reached so far.stop_cause, when a person said why the covered jobs stopped.no_estimate, when there is no estimated saving.disagreement, when a person reported a saving that is 2 times or more away from the estimate, with the checks that may explain the gap.page: the recommendation's web page, when the server knows the web address.ask_userandend_state: questions to put to the person (withour_readingas the suggested answer), and where the session can stop (fixed_and_verified,cant_tell_yetwithknown_on, ornothing_to_fix).
Say a saving with its margin ("saved 45.10 ± 4.30 a day"). WAITING and CONFOUNDED are not savings yet. With no measurement, call job_run_comparison with this recommendation_id to compare the job's runs instead. A person confirms what shipped on the web app's Did this work? tab; see Did this work?.
Example
"Did recommendation 9c2b1f7e save anything?"
{
"recommendation": {"id": "9c2b1f7e-...", "status": "APPLIED", "claimed_daily_savings": 48.2},
"measurement": {
"verdict": "SEEN",
"change_date": "2026-05-01",
"change_source": "CONFIRMED",
"method": "JOB_COST",
"before": 61.0,
"after": 14.2,
"saving": 45.1,
"saving_margin": 4.3
},
"checkpoints": [{"checkpoint_days": 7, "verdict": "SEEN"}],
"end_state": {"state": "fixed_and_verified"}
}Related
Updated 17 days ago