:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp): steer agents to explain-chart and show one chapter alone (#124455)
Sam Pennington77a58b8dfedb
diff --git a/frontend/snapshots.yml b/frontend/snapshots.ymlindex badd1fa11e8b..cd0551a15b8e 100644--- a/frontend/snapshots.yml+++ b/frontend/snapshots.yml@@ -6434,6 +6434,8 @@ snapshots:hash: v1.k794b7964.59974ba8a33be7e981f575614bb77b3fe73dc905c9f6cb5db54e61591c7484ae.Qzl-nCRtGQHeYMHKmGsneXCagaDtWsjsyZlavdRVmmUmcp-apps-explain-chart--evidence-chart--light:hash: v1.k794b7964.c25bffca27dae4d96ed3a8a534297c79fc55e9f5a332472bedfeb46f4cb79bd8.DQxHAg-l47utDGyaTLdaaAMkkaLBaeHnxF-YTKFnmh0+ mcp-apps-explain-chart--single-chapter--light:+ hash: v1.k794b7964.8d0d4e81255c25acbe114b45d698a66d4b3ff5be122c97eea1f5cc2066711a72.jx6b5OO_YEIBQZHEUccM0lJ6vaRZBUUWxs3dJgxxwKwmcp-apps-explain-chart--summary--light:hash: v1.k794b7964.8e544f3f6c9e2e43bf03efd6bf30e402e2f24a41ec060922b5e3068643ce4c86.BQcCbMIGeBusavfXWYInYZD6jMZfnN4zr-HV9oOAFHgmcp-apps-feature-flags--boolean-flag--light:diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsxindex f3600472be3c..f2c3770425f1 100644--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx@@ -112,9 +112,15 @@ const evidenceCharts: StoryEvidenceCharts = {),}-const renderStory = (): ReactElement => (+const singleChapterStory: ExplainChartData = {+ ...story,+ headline: 'One article on **news.example.com** caused the spike.',+ chapters: story.chapters.slice(0, 1),+}++const renderStory = (data: ExplainChartData = story): ReactElement => (<ExplainChartView- data={story}+ data={data}renderChart={(overlay) => <StoryChart series={SIGN_UPS} overlay={overlay} />}openLink={() => {}}evidenceCharts={evidenceCharts}@@ -154,12 +160,12 @@ type Story = StoryObj<{}>export const Summary: Story = {decorators: [width('w-[680px]')],- render: renderStory,+ render: () => renderStory(),}export const ChapterBesideTheChart: Story = {decorators: [width('w-[1100px]')],- render: renderStory,+ render: () => renderStory(),play: async ({ canvasElement }) => {// The step and the marker on the chart share this name, and either one opens the chapter.const [button] = await within(canvasElement).findAllByRole('button', {@@ -171,7 +177,7 @@ export const ChapterBesideTheChart: Story = {export const EvidenceChart: Story = {decorators: [width('w-[1100px]')],- render: renderStory,+ render: () => renderStory(),play: async ({ canvasElement }) => {const canvas = within(canvasElement)const [chapter] = await canvas.findAllByRole('button', { name: 'Chapter 1: A spike on October 2' })@@ -179,3 +185,8 @@ export const EvidenceChart: Story = {await userEvent.click(await canvas.findByRole('button', { name: 'Show chart' }))},}++export const SingleChapter: Story = {+ decorators: [width('w-[680px]')],+ render: () => renderStory(singleChapterStory),+}diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsxindex e0b604dae25b..17847f70f28b 100644--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx@@ -7,6 +7,7 @@ import type { ExplainChartData, StoryChapter, StoryEvidence } from './explainChaimport { StoryChapterView } from './StoryChapterView'import { StoryChartOverlay } from './StoryChartOverlay'import { buildStoryPages, type StoryPage } from './storyPages'+import { StorySingleChapterView } from './StorySingleChapterView'import { StorySteps } from './StorySteps'import { StorySummaryView } from './StorySummaryView'@@ -71,7 +72,9 @@ export function ExplainChartView({evidenceCharts,}: ExplainChartViewProps): ReactElement {const pages = useMemo(() => buildStoryPages(data, formatValue), [data, formatValue])- const [activeIndex, setActiveIndex] = useState(0)+ // With one chapter, a summary page and steps add nothing, so the walkthrough is that chapter alone.+ const singleChapter = pages.length === 2+ const [activeIndex, setActiveIndex] = useState(singleChapter ? 1 : 0)const [previewIndex, setPreviewIndex] = useState<number | null>(null)const [shownEvidenceIndex, setShownEvidenceIndex] = useState<number | null>(null)const active = pages[activeIndex] ?? pages[0]!@@ -89,6 +92,8 @@ export function ExplainChartView({}}, [active, prefetch])+ const canShowChart = (item: StoryEvidence): boolean => !!item.query && !!evidenceCharts?.canShow(item.query)+const toggleEvidenceChart = (index: number): void => {const query = active.chapter?.evidence[index]?.queryif (index === shownEvidenceIndex || !query) {@@ -115,6 +120,7 @@ export function ExplainChartView({pages={pages}highlightedIndex={previewIndex ?? activeIndex}activeIndex={activeIndex}+ showMarkers={!singleChapter}onSelect={(index) => select(index, 'marker')}/>)@@ -158,11 +164,22 @@ export function ExplainChartView({<div className="flex flex-col @3xl/story:absolute @3xl/story:inset-0">{/* Keyed on the page, so each chapter opens at its top and an evidence chart keeps the scroll. */}<div key={activeIndex} className="min-h-0 flex-1 p-4 @3xl/story:overflow-y-auto">- {hasChapter(active) ? (+ {singleChapter && hasChapter(active) ? (+ <StorySingleChapterView+ headline={data.headline}+ seriesNote={seriesNoteOf(data)}+ warnings={warningMessages(data.warnings)}+ page={active}+ openLink={openLink}+ canShowChart={canShowChart}+ shownEvidenceIndex={shownEvidenceIndex}+ onToggleChart={toggleEvidenceChart}+ />+ ) : hasChapter(active) ? (<StoryChapterViewpage={active}openLink={openLink}- canShowChart={(item) => !!item.query && !!evidenceCharts?.canShow(item.query)}+ canShowChart={canShowChart}shownEvidenceIndex={shownEvidenceIndex}onToggleChart={toggleEvidenceChart}/>@@ -177,36 +194,38 @@ export function ExplainChartView({/>)}</div>- <div className="flex items-center justify-between gap-3 border-t border-border py-2 ps-4 pe-3">- <StorySteps- pages={pages}- activeIndex={activeIndex}- onSelect={(index) => select(index, 'step')}- onPreview={setPreviewIndex}- />- <div className="flex shrink-0 gap-1">- {activeIndex > 0 && (- <Button- variant="outline"- size="sm"- onClick={() => select(activeIndex - 1, 'back')}- data-attr="explain-chart-back"- >- Back- </Button>- )}- {hasNext && (- <Button- variant="primary"- size="sm"- onClick={() => select(activeIndex + 1, 'next')}- data-attr="explain-chart-next"- >- Next- </Button>- )}+ {!singleChapter && (+ <div className="flex items-center justify-between gap-3 border-t border-border py-2 ps-4 pe-3">+ <StorySteps+ pages={pages}+ activeIndex={activeIndex}+ onSelect={(index) => select(index, 'step')}+ onPreview={setPreviewIndex}+ />+ <div className="flex shrink-0 gap-1">+ {activeIndex > 0 && (+ <Button+ variant="outline"+ size="sm"+ onClick={() => select(activeIndex - 1, 'back')}+ data-attr="explain-chart-back"+ >+ Back+ </Button>+ )}+ {hasNext && (+ <Button+ variant="primary"+ size="sm"+ onClick={() => select(activeIndex + 1, 'next')}+ data-attr="explain-chart-next"+ >+ Next+ </Button>+ )}+ </div></div>- </div>+ )}</div></aside></div>diff --git a/products/product_analytics/mcp/apps/explainChart/StoryChartOverlay.tsx b/products/product_analytics/mcp/apps/explainChart/StoryChartOverlay.tsxindex ec75083fcc6d..70c403175571 100644--- a/products/product_analytics/mcp/apps/explainChart/StoryChartOverlay.tsx+++ b/products/product_analytics/mcp/apps/explainChart/StoryChartOverlay.tsx@@ -14,6 +14,7 @@ export interface StoryChartOverlayProps {/** The page whose stretch is lit: the one on show, or the one the pointer is over. */highlightedIndex: numberactiveIndex: number+ showMarkers: booleanonSelect: (index: number) => void}@@ -22,6 +23,7 @@ export function StoryChartOverlay({pages,highlightedIndex,activeIndex,+ showMarkers,onSelect,}: StoryChartOverlayProps): ReactElement | null {const layout = useChartLayout()@@ -32,7 +34,7 @@ export function StoryChartOverlay({}const band = chapterBand(layout, series, highlighted.range)- const markers = storyMarkers(layout, series, pages)+ const markers = showMarkers ? storyMarkers(layout, series, pages) : []return (<div data-attr="explain-chart-overlay">{band && (diff --git a/products/product_analytics/mcp/apps/explainChart/StorySingleChapterView.tsx b/products/product_analytics/mcp/apps/explainChart/StorySingleChapterView.tsxnew file mode 100644index 000000000000..2c957db989e7--- /dev/null+++ b/products/product_analytics/mcp/apps/explainChart/StorySingleChapterView.tsx@@ -0,0 +1,41 @@+import { type ReactElement } from 'react'++import { Text } from '@posthog/quill'++import { StoryChapterView, type StoryChapterViewProps } from './StoryChapterView'+import { StoryMarkedText } from './StoryMarkedText'++export interface StorySingleChapterViewProps extends StoryChapterViewProps {+ headline: string+ /** Which series the story follows, when the chart has more than one. */+ seriesNote: string | null+ warnings?: string[]+}++export function StorySingleChapterView({+ headline,+ seriesNote,+ warnings = [],+ ...chapterProps+}: StorySingleChapterViewProps): ReactElement {+ return (+ <div className="flex flex-col gap-4" data-attr="explain-chart-single-chapter">+ <div className="flex flex-col gap-2 border-b border-border pb-4">+ <Text size="base" weight="medium">+ <StoryMarkedText text={headline} />+ </Text>+ {seriesNote && (+ <Text size="xs" variant="muted">+ {seriesNote}+ </Text>+ )}+ {warnings.map((warning, index) => (+ <Text key={index} size="xs" variant="muted" data-attr="explain-chart-warning">+ {warning}+ </Text>+ ))}+ </div>+ <StoryChapterView {...chapterProps} />+ </div>+ )+}diff --git a/products/product_analytics/skills/investigate-metric/SKILL.md b/products/product_analytics/skills/investigate-metric/SKILL.mdindex 9efd08ecd301..3550d0df2603 100644--- a/products/product_analytics/skills/investigate-metric/SKILL.md+++ b/products/product_analytics/skills/investigate-metric/SKILL.md@@ -82,6 +82,23 @@ playbook's steps. See **HogQL insights** in shared-patterns.md.If the user's question spans multiple kinds, run the playbooks in sequence.+### Choose how you will show the findings++Decide this now, before the investigation, because it changes which queries you keep.++The findings go in a walkthrough when the chart is a `TrendsQuery` over time (not a box plot, 2D heatmap or scatter plot) and `posthog:explain-chart` exists in this session.+It exists when `posthog:render-ui` lists `explain-chart` in its `tool_name`, or when `info explain-chart` works through `exec`.+Without `render-ui`, only some hosts draw the walkthrough from `exec`, so Step 5 checks that it appeared and falls back to the written report when it did not.+Otherwise the findings go in a written report.++When it is a walkthrough:++- Read the `explain-chart` schema now.+- Add "Show the walkthrough (Step 5)" as the last item of your plan or to-do list.+- Keep the `TrendsQuery` behind each finding, such as an event count with a breakdown or a property filter.+ The walkthrough draws a `TrendsQuery` as a chart beside the finding, and any other query only as a link.+ Use SQL for the findings that a `TrendsQuery` cannot express.+## Step 2 — Common opening moves### 2.1 Confirm the anomaly@@ -128,13 +145,12 @@ in the control = strong hypothesis; moved too = expand the investigation. Skip w## Step 5 — Write findings-Show the findings as a walkthrough when the session can display one, and as a written report otherwise.+Use the format you chose in Step 1: the walkthrough when `explain-chart` exists and the chart is a `TrendsQuery` over time, and the written report otherwise.### The walkthrough-Use it for a `TrendsQuery` over time, not a box plot, 2D heatmap or scatter plot, when the-`posthog:render-ui` tool is available and its `tool_name` list includes `explain-chart`. It draws the chart with each moment highlighted and lets the-user step through them. Map the investigation onto it:+It draws the chart with each moment highlighted and lets the user step through them.+Map the investigation onto it:- **Anomaly** → one chapter per moment, with `start` and `end` copied exactly from thechart's `days`. The app works out each chapter's numbers from the chart, so leave them out@@ -148,8 +164,10 @@ user step through them. Map the investigation onto it:Do the same in each `cause`.Call `posthog:explain-chart` first. It reports any chapter whose dates match no point on the-chart, so fix those dates and call it again. Then call `posthog:render-ui` with `tool_name`-`explain-chart` and the same input as `tool_input`.+chart, so fix those dates and call it again.+When its response says the user already sees the result, the walkthrough is on screen, and you are done.+Otherwise call `posthog:render-ui` with `tool_name` `explain-chart` and the same input as `tool_input`.+When `render-ui` does not exist either, the user sees nothing, so write the written report instead.Then reply in at most three short sentences: which chapter to look at first, one caveatabout the data if the walkthrough cannot show it, and one offer from below. The walkthroughdiff --git a/products/product_analytics/skills/investigate-metric/references/box-plot-playbook.md b/products/product_analytics/skills/investigate-metric/references/box-plot-playbook.mdindex 33a936829c42..7bfc9194b458 100644--- a/products/product_analytics/skills/investigate-metric/references/box-plot-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/box-plot-playbook.md@@ -107,3 +107,7 @@ user overlap.Run `posthog:query-lifecycle` on the same event. A distribution shift often reflects amix change — an influx of new free-tier users can pull p75 order value down whileno existing user changed behavior.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/funnel-playbook.md b/products/product_analytics/skills/investigate-metric/references/funnel-playbook.mdindex f0788539b9eb..e5facf85137e 100644--- a/products/product_analytics/skills/investigate-metric/references/funnel-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/funnel-playbook.md@@ -56,3 +56,7 @@ console warning elsewhere usually can't.`posthog:query-paths` with `endPoint` set to the failing step. Paths that don't reachthat endpoint show where users bail.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/lifecycle-playbook.md b/products/product_analytics/skills/investigate-metric/references/lifecycle-playbook.mdindex 0de446946297..0e1d80cff313 100644--- a/products/product_analytics/skills/investigate-metric/references/lifecycle-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/lifecycle-playbook.md@@ -39,3 +39,7 @@ posthog:query-lifecycleUse interval zoom + actor drilldown if a specific day stands out.- **Resurrecting drop** — usually external. Re-check annotations and re-engagementcampaign / email events.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/paths-playbook.md b/products/product_analytics/skills/investigate-metric/references/paths-playbook.mdindex 7411fa55e935..a54a0ca8d35e 100644--- a/products/product_analytics/skills/investigate-metric/references/paths-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/paths-playbook.md@@ -48,3 +48,7 @@ browsers / countries / plans is evidence the change is segment-specific.Pull session recordings for users on the new dominant edge — usually surfaces the UIchange faster than more queries. Cross-check `query-error-tracking-issues-list` for errors onthe page where users diverge.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/retention-playbook.md b/products/product_analytics/skills/investigate-metric/references/retention-playbook.mdindex 861a08addf9a..a68ed99bee23 100644--- a/products/product_analytics/skills/investigate-metric/references/retention-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/retention-playbook.md@@ -39,3 +39,7 @@ cohort for the affected period (`posthog:cohorts-create` / `-list`), then runRun `posthog:query-lifecycle` scoped to the affected cohort to separate "never retained"(new users who didn't return) from "lost later" (returning users who churned).++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/stickiness-playbook.md b/products/product_analytics/skills/investigate-metric/references/stickiness-playbook.mdindex 6dd6ee4b7b1e..83353b17001a 100644--- a/products/product_analytics/skills/investigate-metric/references/stickiness-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/stickiness-playbook.md@@ -34,3 +34,7 @@ Run `posthog:query-trends` on a key engagement event filtered to that segment, tWith a sticky and a non-sticky cohort, run `posthog:query-trends` on candidate coreevents scoped to each (filter via `properties` cohort filter). Events where the twodiverge are the ones driving stickiness.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/products/product_analytics/skills/investigate-metric/references/trend-playbook.md b/products/product_analytics/skills/investigate-metric/references/trend-playbook.mdindex 7fe21717bec0..84305e911454 100644--- a/products/product_analytics/skills/investigate-metric/references/trend-playbook.md+++ b/products/product_analytics/skills/investigate-metric/references/trend-playbook.md@@ -44,3 +44,7 @@ timing, plausible mechanism, and user overlap before treating as the cause.Run `posthog:query-lifecycle` on the same event. If the drop is concentrated in onestatus (new users didn't arrive, dormant users didn't resurrect), the user mix changedrather than per-user behavior.++## Next++Return to SKILL.md for Step 4 (cross-check) and Step 5 (write findings), in the format you chose in Step 1.diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex e5843fda136e..ea7d0564c86b 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -6355,7 +6355,7 @@"feature_flag": "experiment-behavior-comparison"},"explain-chart": {- "description": "Show the person a walkthrough of a trends chart: the chart with each moment that stands out highlighted, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nCall it at the end of an investigation, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`, or the TrendsQuery you ran as `query`, plus a one-sentence `headline` and the chapters in reading order.\n\nThe app works out each chapter's numbers from the chart itself (the value, and how it compares with a typical point), so leave the chart's numbers out of your text. Numbers from your own follow-up queries belong in `evidence`, with the `query` that found them so the person can open it. Say how sure you are with `confidence`, and word a cause you could not confirm as a guess. Wrap each name that explains a moment (a referrer, a page, a country, a release) in **double asterisks** to highlight it, in the headline as well as in the chapters.\n\nTrends only, one series at a time. A chart that shows a total, such as a number, pie, table or map, is drawn as the line behind it. A box plot, 2D heatmap or scatter plot is refused. The response says which chapters' dates matched no point on the chart.\n\nA direct call checks the chapters against the chart and returns a short summary, and may show the person nothing. Show the walkthrough with `render-ui` where that tool is available.",+ "description": "Show the person a walkthrough of a trends chart: the chart with each moment that stands out highlighted, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nCall it at the end of an investigation, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`, or the TrendsQuery you ran as `query`, plus a one-sentence `headline` and the chapters in reading order.\n\nThe app works out each chapter's numbers from the chart itself (the value, and how it compares with a typical point), so leave the chart's numbers out of your text. Numbers from your own follow-up queries belong in `evidence`, with the `query` that found them so the person can open it. Say how sure you are with `confidence`, and word a cause you could not confirm as a guess. Wrap each name that explains a moment (a referrer, a page, a country, a release) in **double asterisks** to highlight it, in the headline as well as in the chapters.\n\nTrends only, one series at a time. A chart that shows a total, such as a number, pie, table or map, is drawn as the line behind it. A box plot, 2D heatmap or scatter plot is refused. The response says which chapters' dates matched no point on the chart.\n\nA direct call checks the chapters against the chart. Where the host draws apps from `exec`, as Claude Code does, the call also shows the walkthrough and the response says so. Otherwise it returns only a short summary: show the walkthrough with `render-ui` where that tool exists, and write the findings in the chat where it does not.","category": "Insights & analytics","feature": "insights","summary": "Walk the person through a trends chart, one highlighted moment at a time.",diff --git a/services/mcp/schema/tool-definitions.json b/services/mcp/schema/tool-definitions.jsonindex 3acb81152ed4..7499bf74e70f 100644--- a/services/mcp/schema/tool-definitions.json+++ b/services/mcp/schema/tool-definitions.json@@ -303,7 +303,7 @@"feature_flag": "insight-data-checks"},"explain-chart": {- "description": "Show the person a walkthrough of a trends chart: the chart with each moment that stands out highlighted, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nCall it at the end of an investigation, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`, or the TrendsQuery you ran as `query`, plus a one-sentence `headline` and the chapters in reading order.\n\nThe app works out each chapter's numbers from the chart itself (the value, and how it compares with a typical point), so leave the chart's numbers out of your text. Numbers from your own follow-up queries belong in `evidence`, with the `query` that found them so the person can open it. Say how sure you are with `confidence`, and word a cause you could not confirm as a guess. Wrap each name that explains a moment (a referrer, a page, a country, a release) in **double asterisks** to highlight it, in the headline as well as in the chapters.\n\nTrends only, one series at a time. A chart that shows a total, such as a number, pie, table or map, is drawn as the line behind it. A box plot, 2D heatmap or scatter plot is refused. The response says which chapters' dates matched no point on the chart.\n\nA direct call checks the chapters against the chart and returns a short summary, and may show the person nothing. Show the walkthrough with `render-ui` where that tool is available.",+ "description": "Show the person a walkthrough of a trends chart: the chart with each moment that stands out highlighted, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nCall it at the end of an investigation, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`, or the TrendsQuery you ran as `query`, plus a one-sentence `headline` and the chapters in reading order.\n\nThe app works out each chapter's numbers from the chart itself (the value, and how it compares with a typical point), so leave the chart's numbers out of your text. Numbers from your own follow-up queries belong in `evidence`, with the `query` that found them so the person can open it. Say how sure you are with `confidence`, and word a cause you could not confirm as a guess. Wrap each name that explains a moment (a referrer, a page, a country, a release) in **double asterisks** to highlight it, in the headline as well as in the chapters.\n\nTrends only, one series at a time. A chart that shows a total, such as a number, pie, table or map, is drawn as the line behind it. A box plot, 2D heatmap or scatter plot is refused. The response says which chapters' dates matched no point on the chart.\n\nA direct call checks the chapters against the chart. Where the host draws apps from `exec`, as Claude Code does, the call also shows the walkthrough and the response says so. Otherwise it returns only a short summary: show the walkthrough with `render-ui` where that tool exists, and write the findings in the chat where it does not.","category": "Insights & analytics","feature": "insights","summary": "Walk the person through a trends chart, one highlighted moment at a time.",