Manage discoveries

Managing Discoveries

Quick Start

To manage discoveries:

1. Call initialize before inspecting organization data
2. Find discovery entities with search_entities and read the selected entity resource for details
3. Assess factual accuracy, novelty, actionability, and timing
4. Recommend approve/reject, or perform the review in the Altertable app if your harness exposes that action
5. When feedback arrives, extract the user's intent and act on it

Finding Discoveries

Use the MCP entity tools to retrieve discoveries:

• search_entities with discovery-related query terms or node_types when available
• altertable://ontology/entities/{slug} to read the full entity content after finding a slug
• take_screenshot when you need to verify how the discovery renders

Available statuses for filtering: pending, approved, rejected.

The public MCP tool surface may not expose an approval mutation. If no review tool is available in your harness, provide a clear recommendation and direct the user to review the discovery in Altertable.

Reviewing a Discovery

When you need to review a discovery, follow these steps in order:

1. Check factual accuracy -- Does the title match the underlying data? Are the numbers correct?
2. Verify it is not a duplicate -- Search existing discoveries for overlapping findings before approving.
3. Assess actionability -- Can the reader do something with this information? If not, reject.
4. Evaluate timing -- Is this finding still current, or has the data gone stale?
5. Decide: approve if steps 1-4 all pass; reject if the analysis is wrong, duplicated, stale, or not actionable.

For batch reviews, sort by priority first, then group by topic, and apply the same five-step check to each.

Discovery Lifecycle

Discoveries flow through these states:

pending  -->  approved | rejected

State	Description	Transitions
pending	Awaiting review	approve → approved; reject → rejected
approved	Approved	reject → rejected
rejected	Rejected	approve → approved

Both approve and reject are reversible: an approved discovery can later be rejected, and a rejected one can later be approved.

Processing User Feedback

Feedback on a discovery has two fields: a reaction (approved or rejected) and an optional reason (free-text, max 1000 chars).

When processing feedback:

1. Note the reaction -- approved or rejected.
2. Parse the reason text -- free-text comments often contain the actionable signal.
3. Detect implicit preferences -- does the feedback signal a topic the user cares more or less about?
4. Take action immediately on anything concrete in the reason.

When feedback includes free-text comments, parse them for:

• Direct requests ("show me this by region")
• Threshold adjustments ("only alert me if the change is over 10%")
• Topic preferences ("I don't care about this metric")
• Accuracy challenges ("the number is wrong because...")

Common Pitfalls

• Approving without checking for duplicates. Always search existing discoveries before approving a new one.
• Ignoring the free-text reason. The approved/rejected reaction alone carries little information; the reason text is where the actionable signal usually lives.
• Over-alerting. If a user has rejected several discoveries on the same topic, stop surfacing similar findings until new data changes the picture.

Reference Files

• Review patterns - Read when batch-reviewing multiple discoveries or designing a review strategy
• Intent detection - Read when processing free-text feedback to extract actionable instructions