Recommendations

Recommendations answers one question: is my search set up right?

• Each finding names one problem, shows your own numbers as evidence, and carries the one change that fixes it.
• The first tab in Insights in the console, and the same answer over the API and MCP.
• Built from field profiles we already keep, so reading it costs no searches.
• Worked out fresh on every read. Nothing is stored except what you hide.

What is checked

Check	Fix	When it is raised
Filtering by a field can only ever return one record facet-is-nearly-unique	Remove the facet	A facet whose values are 90% or more unique and read as text — a title or description. Identifiers (id-like names, single-word values) are never raised: filtering by one is how a record is looked up exactly.
Filtering by a field cannot narrow anything facet-has-one-value	Remove the facet	Every record holds the same value, so the filter shows a single option.
People search values that plain search can’t find shadow-rule-awaiting-decision	Turn the rule on	A query rule learned from your real searches is running in shadow, waiting for a yes.

When nothing is raised

• A list with fewer than 50 profiled records — too little data to tell you to change a live schema.
• Facet removals on a list that re-imports from a connected file: the next import would put the facet back.
• A list never profiled is not counted in lists_checked. Nothing found with nothing checked is not a clean bill of health.

In the console

• Insights → Recommendations. Each row has its evidence and a control that opens a confirmation naming what the change breaks.
• Hide a row you disagree with: for 30 days, 90 days or for good. Hidden rows stay readable and can be shown again.
• Hiding is account-wide and needs permission to edit lists.
• Deleting a list clears its hidden rows.

Over the API

GET /list/recommendations/{account-name}

Field	What it holds
findings	One per problem: check_id, list_name, title, evidence (plain sentences) and action.
action.kind	remove-facet or enable-query-rule.
action.target	The facet to remove, or the query rule to set to Enabled. A name, so it passes straight to the facet or query-rule call.
destructive	true when the fix takes something away (removing a facet bumps the list version).
lists_checked	Lists that had evidence to check. Zero means nothing has been profiled yet.
hidden	Rows hidden in the console: the same finding, its window (forever, 30-days, 90-days) and hidden_until.

Needs list:read across the account. Read-only; hiding is console-only for now. Both clients carry it:

var recommendations = await client.Lists.GetRecommendationsAsync("acme");

const recommendations = await client.Lists.getRecommendations("acme");

For agents

• MCP: list_recommendations — read-only, costs nothing, and the right call for “what is wrong with my search?”.
• Act on a finding with facet_remove or query_rule_set_state. Removing a facet is destructive, so confirm with a person first.

Notes

• Not Account Health: that is a live fault that clears when the thing recovers, this is standing advice about your setup.
• Findings reflect the data when the list was last profiled, not the live list.