--- title: "Sort uncategorized insights" description: "Place the insights of a theme that no subtheme holds yet into the right subtheme or theme, after the user approves." url: "/docs/agents/workflows/sort-uncategorized-insights" --- This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth. # Sort uncategorized insights — agent workflow * **Use it when:** the user asks "which insights are not grouped yet?", "clean up the uncategorized insights" or "sort the new feedback into subthemes", or after a large import. * **Outcome:** each uncategorized insight of the chosen themes is in a subtheme that fits, in a better theme, or left for the next synthesis run with a reason. * **Needs:** Deck MCP and the Starter plan or higher, because subthemes need it. Every member with MCP access can use the subtheme write tools. They spend no credits. ## 1. Probe Deck MCP Call `get_user_context`. This must be a real tool call. * 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop. * No Deck tools: fetch and follow [https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md). Stop this workflow until the tools work. ## 2. Find the themes with uncategorized insights Ask the user which themes to sort. When the user does not say, take the top themes of `explore_themes` in Deck's order. Call `explore_subthemes` with each `theme_id` and `segment_scope: "all_customers"`. Make these calls at the same time. Do not set `segment_ids`. Without `segment_scope: "all_customers"`, an organization with segments gets the subthemes of every segment, but `theme_summary` always counts all customers. With it, the subtheme list, the uncategorized list, the writes and `theme_summary` all use the same all-customer subthemes. * `feature_unavailable`: the plan does not include subthemes. Tell the user that subthemes need the Starter plan or higher. Stop. * `theme_summary.uncategorized_insight_count` is the number of the theme's insights that are not in a subtheme yet. Quote it. * `theme_summary.below_threshold` is `true` when the theme needs 5 or more insights before Deck builds subthemes. Skip that theme: it has no subthemes to place insights into. Start with the themes that have the most uncategorized insights. ## 3. Read the uncategorized insights and the subthemes * Take any `subtheme_id` from the theme's list. Call `explore_subthemes` with that `subtheme_id` and `view` set to `uncategorized`. It returns up to 100 of the theme's uncategorized insights with quotes for each call. Page with `offset`. * Read the name and insight count of each subtheme in the list. When a name is not clear, call `explore_subthemes` with its `subtheme_id` to read its narrative and key quotes. ## 4. Decide where each insight goes Give each insight one of these outcomes: * **Fits a subtheme of this theme:** add it to that subtheme. * **Belongs to another theme:** move it to that theme. Find the theme with `explore_themes` and a `query` word. * **Fits nothing well:** leave it. When several insights share a new topic, the next synthesis run can build a subtheme from them. Do not force a fit. A wrong placement is worse than an uncategorized insight. Show the user a table: insight name, short quote, outcome, target subtheme or theme. Group the rows by target. Ask: "Apply this plan?" Wait for a yes. ## 5. Apply the plan * **Add to a subtheme:** `add_subtheme_insights` with `subtheme_id` and up to 100 `insight_ids`. Read `added` and `not_uncategorized`. An insight in `not_uncategorized` is no longer in the uncategorized list, for example because a teammate or a synthesis run placed it. Skip it. * **Move to another theme:** `move_theme_insights` with `source_theme_id`, `target_theme_id` and up to 100 `insight_ids`. Read `moved` and `not_linked`. The insight shows in the subthemes of the target theme after the next synthesis run. * **Fix a wrong subtheme:** `move_subtheme_insights` with `source_subtheme_id`, `target_subtheme_id` and up to 100 `insight_ids`. Both subthemes must be in the same theme and the same segment scope. Otherwise Deck returns `VALIDATION_ERROR`. Send the subtheme writes (`add_subtheme_insights`, `move_subtheme_insights` and `delete_subtheme`) for one theme one at a time. Wait for the result of each write before you send the next one. When a subtheme write returns `CONFLICT`, another write changed the subthemes of that theme at the same time. Call `explore_subthemes` with the `theme_id` and `segment_scope: "all_customers"` again, make sure that the plan still fits, and then send the write again. One unknown insight ID fails the whole call with `NOT_FOUND`. The missing IDs are in `error.details.details.missing_insight_ids`. Remove them and call again. ## 6. Check the result * Call `explore_subthemes` with the same `theme_id` and `segment_scope: "all_customers"` again. Quote the new `theme_summary.uncategorized_insight_count`. * Call `explore_subthemes` with each target `subtheme_id` and `view` set to `insights` to show the insights it holds now. * Tell the user that Deck rebuilds subthemes on the next synthesis run. That run can change the groups. ## Rules * Quote Deck's numbers. Do not compute your own. * Show the plan and get a yes before you call write tools. * Do not call `delete_subtheme` in this workflow unless the user asks. It is a sensitive write: it removes the subtheme and puts its insights back in the uncategorized list. Get an explicit yes every time. * Moving an insight to another theme changes the theme taxonomy. When many insights belong elsewhere, fetch and follow [https://docs.getdeck.io/docs/agents/workflows/taxonomy-review.md](https://docs.getdeck.io/docs/agents/workflows/taxonomy-review.md). * After each write, check for a top-level `error` key. When `idempotency.replayed` is `true`, Deck did not run the write again. See [Write responses and retries](/docs/integrations/mcp#write-responses-and-retries). * If the user has more than one Deck organization, call `select_organization` first and pass `org_id` on every call. ## Done when * Each uncategorized insight of the chosen themes has an outcome that the user approved. * Each approved write returned success, and `explore_subthemes` shows the new uncategorized count. * The user knows which insights wait for the next synthesis run. --- [View full sitemap](/docs/sitemap)