Skip to content

: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.

feat(mcp): end trends insight investigations with a chart explanation (#124620)

Sam Pennington89226871c10d
diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
index 1177d0b4935f..35a16d1bd60f 100644
--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx
@@ -136,7 +136,7 @@ const width =
</div>
)
-// Opts the subtree into Quill's tokens, which the walkthrough reads directly as `var(--card)` and the like.
+// Opts the subtree into Quill's tokens, which the explanation reads directly as `var(--card)` and the like.
const quillTokens = (Story: StoryFn): ReactElement => (
<div data-quill data-mcp-storybook>
<Story />
diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
index c0ec8815c985..f68a0e61e8af 100644
--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx
@@ -72,7 +72,7 @@ export function ExplainChartView({
evidenceCharts,
}: ExplainChartViewProps): ReactElement {
const pages = useMemo(() => buildStoryPages(data, formatValue), [data, formatValue])
- // With one chapter, a summary page and steps add nothing, so the walkthrough is that chapter alone.
+ // With one chapter, a summary page and steps add nothing, so the explanation is that chapter alone.
const singleChapter = pages.length === 2
const [activeIndex, setActiveIndex] = useState(singleChapter ? 1 : 0)
const [previewIndex, setPreviewIndex] = useState<number | null>(null)
@@ -138,7 +138,7 @@ export function ExplainChartView({
data-attr="explain-chart-evidence-back"
>
<ArrowLeft className="size-3" />
- Back to the walkthrough
+ Back to the explanation
</Button>
</div>
{evidenceCharts.render(evidenceView)}
@@ -156,7 +156,7 @@ export function ExplainChartView({
</div>
<aside
className="relative shrink-0 border-t border-border @3xl/story:w-80 @3xl/story:border-t-0 @3xl/story:border-l"
- aria-label="Walkthrough of this chart"
+ aria-label="Explanation of this chart"
>
{/* Beside the chart, the panel takes the chart's height and the page scrolls inside it. */}
<div className="flex flex-col @3xl/story:absolute @3xl/story:inset-0">
diff --git a/products/product_analytics/mcp/tools.yaml b/products/product_analytics/mcp/tools.yaml
index a0ecc253f7ea..6dc9718956b7 100644
--- a/products/product_analytics/mcp/tools.yaml
+++ b/products/product_analytics/mcp/tools.yaml
@@ -12,7 +12,7 @@ ui_apps:
link_prop: openLink
explain-chart:
type: custom
- app_name: PostHog Chart Walkthrough
+ app_name: PostHog Chart Explanation
description: A trends chart with the moments that stand out highlighted, explained one chapter at a time.
render_ui:
component_import: ../components/ExplainChart
diff --git a/products/product_analytics/skills/investigate-metric/SKILL.md b/products/product_analytics/skills/investigate-metric/SKILL.md
index baf626c173c1..124b64bb968c 100644
--- a/products/product_analytics/skills/investigate-metric/SKILL.md
+++ b/products/product_analytics/skills/investigate-metric/SKILL.md
@@ -86,17 +86,18 @@ If the user's question spans multiple kinds, run the playbooks in sequence.
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 the user gave you a saved insight or a query that is a `TrendsQuery` over time (not a box plot, 2D heatmap or scatter plot), the investigation ends with a chart explanation from `posthog:explain-chart`.
+`posthog:explain-chart` exists only where chart explanations are enabled, so check for it now and read its schema.
+Where PostHog tools run through `exec`, it is not in your own tool list: run `info explain-chart` before you decide it is missing.
+When it does not exist, the findings go in a written report.
+The chart explanation is the answer, in place of a notebook or a long reply. Write a notebook as well only when the user asks for one.
+For anything else, such as a metric you queried on your own, the findings go in a written report.
-When it is a walkthrough:
+When it is a chart explanation:
-- Read the `explain-chart` schema now.
-- Add "Show the walkthrough (Step 5)" as the last item of your plan or to-do list.
+- Add "Show the chart explanation (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.
+ The chart explanation 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, and pass its numbers as the evidence's `chart` so they draw too.
## Step 2 — Common opening moves
@@ -145,9 +146,11 @@ in the control = strong hypothesis; moved too = expand the investigation. Skip w
## Step 5 — Write findings
-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.
+**Before you write your answer, call `posthog:explain-chart` when the user gave you a trends insight over time.**
+Do this after a long investigation too, and when most of your evidence is SQL.
+For anything else, use the written report.
-### The walkthrough
+### The chart explanation
It draws the chart with each moment highlighted and lets the user step through them.
Map the investigation onto it:
@@ -158,26 +161,26 @@ Map the investigation onto it:
- **Likely cause** and **Confidence** → `cause`, `confidence` and `confidence_reason`.
- **Evidence** → `evidence`, each finding with the `query` that produced it, or a `url`
for a commit or a deploy. Pass the `TrendsQuery` you ran where you have one: the
- walkthrough draws it as a chart, while any other query only becomes a link.
+ chart explanation draws it as a chart, while any other query only becomes a link.
For a finding from SQL, also pass `chart` with the numbers from its result: `line` over time or `bar` per label, the `labels`, and one `series` per line.
- A **headline** of one sentence with no numbers sums up the whole chart.
- Wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in `**double asterisks**` so the walkthrough highlights it.
+ Wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in `**double asterisks**` so the chart explanation highlights 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.
-When its response says the user already sees the result, the walkthrough is on screen, and you are done.
+When its response says the user already sees the result, the chart explanation 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.
+When the call fails because the tool does not exist, or `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 caveat
-about the data if the walkthrough cannot show it, and one offer from below. The walkthrough
-already holds the chart, the chapters, their causes and their evidence, so the reply has no
-bullet points, no description of the chart and no list of the moments.
+Then reply briefly.
+Say which chapter to look at first, then add only what the chart explanation cannot hold, such as a caveat about the data, a linked fix or a decision that is still open.
+End with one offer from below.
+The chart explanation already holds the chart, the chapters, their causes and their evidence, so do not describe the chart or list the moments again.
### The written report
-Without the walkthrough, use the format below. Offer to save key charts via `posthog:insight-create`.
+Without the chart explanation, use the format below. Offer to save key charts via `posthog:insight-create`.
If a cause is found and no annotation marks it, offer `posthog:annotation-create`.
See [common-causes.md](./references/common-causes.md) for the cause taxonomy.
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 01a3d764bc7d..38674dbb8acf 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -6369,11 +6369,11 @@
"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. 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.",
+ "description": "Show the person an explanation 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 explanation and the response says so. Otherwise it returns only a short summary: show the explanation 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.",
- "title": "Show chart walkthrough",
+ "title": "Explain this chart",
"required_scopes": ["insight:read", "query:read"],
"api_operations": ["GET /api/projects/{project_id}/insights/{id}/", "POST /api/projects/{project_id}/query/"],
"feature_flag": "investigate-insight",
diff --git a/services/mcp/schema/tool-definitions.json b/services/mcp/schema/tool-definitions.json
index e350b2ca9f46..e50ae3352652 100644
--- a/services/mcp/schema/tool-definitions.json
+++ b/services/mcp/schema/tool-definitions.json
@@ -303,11 +303,11 @@
"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. 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.",
+ "description": "Show the person an explanation 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 explanation and the response says so. Otherwise it returns only a short summary: show the explanation 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.",
- "title": "Show chart walkthrough",
+ "title": "Explain this chart",
"required_scopes": ["insight:read", "query:read"],
"api_operations": ["GET /api/projects/{project_id}/insights/{id}/", "POST /api/projects/{project_id}/query/"],
"feature_flag": "investigate-insight",
diff --git a/services/mcp/schema/tool-inputs.json b/services/mcp/schema/tool-inputs.json
index cca13e562b43..da8ff1b2b7ec 100644
--- a/services/mcp/schema/tool-inputs.json
+++ b/services/mcp/schema/tool-inputs.json
@@ -772,7 +772,7 @@
"description": "One finding in one sentence, with the numbers from the query that found it. Mark the name that matters with **double asterisks**."
},
"query": {
- "description": "The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the walkthrough.",
+ "description": "The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the explanation.",
"type": "object",
"propertyNames": {
"type": "string"
diff --git a/services/mcp/src/hono/instructions.ts b/services/mcp/src/hono/instructions.ts
index 11265c0eef21..c9bb7ffb4ba5 100644
--- a/services/mcp/src/hono/instructions.ts
+++ b/services/mcp/src/hono/instructions.ts
@@ -19,9 +19,9 @@ import { ExecLearnCatalog } from '@/tools/exec-learn'
import {
getRenderableToolNames,
makeRenderUiSchema,
- RENDER_UI_TOOL_DESCRIPTION,
RENDER_UI_TOOL_NAME,
RENDER_UI_TOOL_TITLE,
+ renderUiDescription,
} from '@/tools/render-ui'
import { getToolDefinition } from '@/tools/toolDefinitions'
@@ -118,7 +118,7 @@ export class InstructionsBuilder {
return {
name: RENDER_UI_TOOL_NAME,
title: RENDER_UI_TOOL_TITLE,
- description: RENDER_UI_TOOL_DESCRIPTION,
+ description: renderUiDescription(toolNames),
// Derived from the same zod schema the executor validates with, so the
// advertised contract (enum, descriptions, required) cannot drift from it.
inputSchema: toMcpInputSchema(makeRenderUiSchema(toolNames as [string, ...string[]])),
diff --git a/services/mcp/src/lib/instructions-formatter.ts b/services/mcp/src/lib/instructions-formatter.ts
index da7437027d26..aa4b1495efce 100644
--- a/services/mcp/src/lib/instructions-formatter.ts
+++ b/services/mcp/src/lib/instructions-formatter.ts
@@ -31,6 +31,7 @@ import EXAMPLES from '@/templates/sections/examples.md'
import EXEC_LEARN from '@/templates/sections/exec-learn.md'
import EXEC_TOOL_BLURB_COMPACT from '@/templates/sections/exec-tool-blurb-compact.md'
import EXEC_TOOL_BLURB from '@/templates/sections/exec-tool-blurb.md'
+import EXPLAIN_CHART from '@/templates/sections/explain-chart.md'
import METRIC_DISCOVERY_COMPACT from '@/templates/sections/metric-discovery-compact.md'
import METRIC_DISCOVERY from '@/templates/sections/metric-discovery.md'
import NOTEBOOK_PYTHON from '@/templates/sections/notebook-python.md'
@@ -186,6 +187,7 @@ export class InstructionsFormatter {
private artifactSections(ctx: InstructionsContext): string[] {
return [
ANALYSIS_ARTIFACTS,
+ ...(ctx.tools?.some(({ name }) => name === 'explain-chart') ? [EXPLAIN_CHART] : []),
...(ctx.notebookCellsEnabled ? [formatPrompt(NOTEBOOK_SQL, notebookSqlVars(ctx)), NOTEBOOK_PYTHON] : []),
...(ctx.notebookRunEnabled ? [NOTEBOOK_RUN] : []),
]
diff --git a/services/mcp/src/resources/ui-apps.generated.ts b/services/mcp/src/resources/ui-apps.generated.ts
index 990203bd81cd..197c79ee46db 100644
--- a/services/mcp/src/resources/ui-apps.generated.ts
+++ b/services/mcp/src/resources/ui-apps.generated.ts
@@ -229,7 +229,7 @@ export const UI_APPS: Array<{
appDir: 'generated/experiment-results',
},
{
- name: 'PostHog Chart Walkthrough',
+ name: 'PostHog Chart Explanation',
uri: EXPLAIN_CHART_RESOURCE_URI,
description: 'A trends chart with the moments that stand out highlighted, explained one chapter at a time.',
appDir: 'explain-chart',
diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.ts
index 26c555a9d5da..5c9c9e42721e 100644
--- a/services/mcp/src/schema/tool-inputs.ts
+++ b/services/mcp/src/schema/tool-inputs.ts
@@ -585,7 +585,7 @@ const ExplainChartEvidenceSchema = z.object({
.record(z.string(), z.unknown())
.optional()
.describe(
- 'The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the walkthrough.'
+ 'The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the explanation.'
),
chart: z
.object({
diff --git a/services/mcp/src/templates/render-ui-explain-chart.md b/services/mcp/src/templates/render-ui-explain-chart.md
new file mode 100644
index 000000000000..42f420fc35fd
--- /dev/null
+++ b/services/mcp/src/templates/render-ui-explain-chart.md
@@ -0,0 +1,2 @@
+When you explain why a trends insight the user gave you changed, as the `posthog:investigate-metric` skill does, end by rendering `explain-chart` with your chapters, not `query-trends`.
+The chart explanation carries the whole answer, so do not write a separate summary of it.
diff --git a/services/mcp/src/templates/sections/explain-chart.md b/services/mcp/src/templates/sections/explain-chart.md
new file mode 100644
index 000000000000..f4a6c6ec917f
--- /dev/null
+++ b/services/mcp/src/templates/sections/explain-chart.md
@@ -0,0 +1,5 @@
+### Explaining a chart
+
+When the person gives you a saved trends insight, by link or short ID, and asks why it changed or asks you to explain it, load the `posthog:investigate-metric` skill and follow it.
+Its answer is the chart explanation from `explain-chart` in the conversation, not a notebook: for that question, this replaces the notebook default above.
+Write a notebook as well only when the person asks for one to keep.
diff --git a/services/mcp/src/tools/insights/explainChart.ts b/services/mcp/src/tools/insights/explainChart.ts
index 949db60079f4..74b26c771339 100644
--- a/services/mcp/src/tools/insights/explainChart.ts
+++ b/services/mcp/src/tools/insights/explainChart.ts
@@ -24,7 +24,7 @@ type Params = z.infer<typeof schema>
type Result = ExplainChartData & { [POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]: string }
const RENDERED_NOTE =
- 'The person sees the walkthrough rendered inline: the chart, every chapter, each cause and each piece of evidence. Do not write any of that again in any form, not as a recap, a bullet list or a summary of the moments. Your whole reply is at most three short sentences: which chapter to start with, one caveat the walkthrough cannot show if there is one, and one next step you offer. If the person says the walkthrough did not load, give the findings in text.'
+ 'The person sees the chart explanation rendered inline: the chart, every chapter, each cause and each piece of evidence. Do not write any of that again in any form, not as a recap, a bullet list or a summary of the moments. Keep your reply short: which chapter to start with, only what the chart explanation cannot hold (a caveat about the data, a linked fix, a decision that is still open), and one next step you offer. If the person says the explanation did not load, give the findings in text.'
// The markers sit on one value over time. These displays draw that as they are.
const TIME_SERIES_DISPLAYS = new Set([
@@ -36,7 +36,7 @@ const TIME_SERIES_DISPLAYS = new Set([
'ActionsStackedBar',
])
-// These show a total over the range, so the walkthrough draws the line behind it. Any other display is refused.
+// These show a total over the range, so the explanation draws the line behind it. Any other display is refused.
const TOTAL_DISPLAYS = new Set([
'Auto',
'BoldNumber',
@@ -55,7 +55,7 @@ const NOT_TRENDS = 'This tool only explains trends charts. For other kinds, writ
const NOT_OVER_TIME =
'This tool explains a trends chart that shows one value over time, and this chart does not. Write the explanation in the chat instead.'
-// The walkthrough redraws evidence through `query-trends`, whose schema is narrower than a TrendsQuery's, so evidence
+// The explanation redraws evidence through `query-trends`, whose schema is narrower than a TrendsQuery's, so evidence
// it would refuse keeps its link and no chart.
const redrawSchema = GENERATED_TOOLS['query-trends']!().schema
@@ -124,7 +124,7 @@ function describeResult(
warnings: unknown[]
): string {
const name = chart.insightName ?? series.label ?? 'the chart'
- const lines = [`The walkthrough of "${name}" has ${chapters.length} chapters.`]
+ const lines = [`The explanation of "${name}" has ${chapters.length} chapters.`]
if (warnings.length) {
lines.push(`The query came with warnings the person should hear about: ${warningMessages(warnings).join(' ')}`)
}
diff --git a/services/mcp/src/tools/render-ui.ts b/services/mcp/src/tools/render-ui.ts
index e8fa8c435ff3..dc04f6c8d33e 100644
--- a/services/mcp/src/tools/render-ui.ts
+++ b/services/mcp/src/tools/render-ui.ts
@@ -3,6 +3,7 @@ import { z } from 'zod'
import { markExecPayload, type ToolResultPayload } from '@/lib/build-tool-result'
import { DISPATCHABLE_APP_KEYS, RENDER_UI_RESOURCE_URI, URI_MAP, type UiAppKey } from '@/resources/ui-apps.generated'
+import RENDER_UI_EXPLAIN_CHART from '@/templates/render-ui-explain-chart.md'
import RENDER_UI_PROMPT from '@/templates/render-ui-prompt.md'
import { type Context, type Tool, type ZodObjectAny } from './types'
@@ -11,6 +12,12 @@ export const RENDER_UI_TOOL_NAME = 'render-ui'
export const RENDER_UI_TOOL_TITLE = 'Render a PostHog visualization'
export const RENDER_UI_TOOL_DESCRIPTION = RENDER_UI_PROMPT.trim()
+export function renderUiDescription(renderableNames: string[]): string {
+ return renderableNames.includes('explain-chart')
+ ? `${RENDER_UI_TOOL_DESCRIPTION}\n\n${RENDER_UI_EXPLAIN_CHART.trim()}`
+ : RENDER_UI_TOOL_DESCRIPTION
+}
+
// Reverse of URI_MAP so a tool's `_meta.ui.resourceUri` resolves back to its app key.
const URI_TO_APP_KEY = new Map<string, UiAppKey>(
Object.entries(URI_MAP).map(([appKey, uri]) => [uri, appKey as UiAppKey])
@@ -79,7 +86,7 @@ export function createRenderUiTool(
return {
name: RENDER_UI_TOOL_NAME,
title: RENDER_UI_TOOL_TITLE,
- description: RENDER_UI_TOOL_DESCRIPTION,
+ description: renderUiDescription(renderableNames),
schema,
scopes: [],
annotations: {
diff --git a/services/mcp/src/ui-apps/apps/explain-chart.tsx b/services/mcp/src/ui-apps/apps/explain-chart.tsx
index abd8f81cb59c..77cdc2222b53 100644
--- a/services/mcp/src/ui-apps/apps/explain-chart.tsx
+++ b/services/mcp/src/ui-apps/apps/explain-chart.tsx
@@ -7,7 +7,7 @@ import { ExplainChart, type ExplainChartData } from '../components/ExplainChart'
function ExplainChartApp(): JSX.Element {
return (
- <AppWrapper<ExplainChartData> appName="PostHog Chart Walkthrough">
+ <AppWrapper<ExplainChartData> appName="PostHog Chart Explanation">
{({ data, openLink, app }) => <ExplainChart data={data!} openLink={openLink} app={app} />}
</AppWrapper>
)
diff --git a/services/mcp/src/ui-apps/components/ExplainChart.tsx b/services/mcp/src/ui-apps/components/ExplainChart.tsx
index ddc7f17cd212..1dce062e1fcb 100644
--- a/services/mcp/src/ui-apps/components/ExplainChart.tsx
+++ b/services/mcp/src/ui-apps/components/ExplainChart.tsx
@@ -21,7 +21,7 @@ const CHART_CLASS_NAME = 'h-[260px] @3xl/story:h-[400px]'
export interface ExplainChartProps {
data: ExplainChartData
openLink: (url: string) => void
- /** The host app, which runs each piece of evidence's query so the walkthrough can draw it. */
+ /** The host app, which runs each piece of evidence's query so the explanation can draw it. */
app?: App | null
}
diff --git a/services/mcp/tests/unit/explain-chart-walkthrough.test.ts b/services/mcp/tests/unit/explain-chart-walkthrough.test.ts
index cacf31f344e9..506d56b169e6 100644
--- a/services/mcp/tests/unit/explain-chart-walkthrough.test.ts
+++ b/services/mcp/tests/unit/explain-chart-walkthrough.test.ts
@@ -14,7 +14,7 @@ import { buildStoryPages } from 'products/product_analytics/mcp/apps/explainChar
const DAYS = ['2026-10-01', '2026-10-02', '2026-10-03', '2026-10-04', '2026-10-05']
const MARKER_LAYOUT = { radius: 10, distance: 22, bounds: { left: 0, top: 0, right: 400, bottom: 300 } }
-describe('explain chart walkthrough', () => {
+describe('explain chart', () => {
it('keeps a small rate from rounding to zero', () => {
const facts = chapterFacts([0.02, 0.02, 0.02, 0.02, 0.02], DAYS, [1, 3], {
interval: 'day',
diff --git a/services/mcp/tests/unit/instructions-formatter.test.ts b/services/mcp/tests/unit/instructions-formatter.test.ts
index 77cdeacca51a..61172344e775 100644
--- a/services/mcp/tests/unit/instructions-formatter.test.ts
+++ b/services/mcp/tests/unit/instructions-formatter.test.ts
@@ -521,6 +521,25 @@ describe('InstructionsFormatter', () => {
expect(result).toContain('**Dashboard**')
})
+ it.each(surfaces)(
+ '$name sends chart explanations to explain-chart only when explain-chart exists',
+ ({ render }) => {
+ const formatter = new InstructionsFormatter()
+ const withTool = render(formatter, {
+ ...fullCtx,
+ tools: [...(fullCtx.tools ?? []), { name: 'explain-chart', category: 'Insights' }],
+ })
+ const withoutTool = render(formatter, {
+ ...fullCtx,
+ tools: fullCtx.tools?.filter(({ name }) => name !== 'explain-chart'),
+ })
+
+ expect(withTool).toContain('### Explaining a chart')
+ expect(withTool.indexOf('### Explaining a chart')).toBeGreaterThan(withTool.indexOf('**Notebook**'))
+ expect(withoutTool).not.toContain('explain-chart')
+ }
+ )
+
// The SQL and Python guidance names `notebooks-add-cell`, so it must stay out of prompts
// for clients that aren't advertised the cell tools.
it.each(surfaces)('$name gates the SQL and Python sections on the notebook cell tools', ({ render }) => {
diff --git a/services/mcp/tests/unit/render-ui.test.ts b/services/mcp/tests/unit/render-ui.test.ts
index 84c23d126e6d..6a139d2cba16 100644
--- a/services/mcp/tests/unit/render-ui.test.ts
+++ b/services/mcp/tests/unit/render-ui.test.ts
@@ -60,6 +60,15 @@ describe('render-ui tool', () => {
expect(schema.safeParse({ tool_name: 'debug-tool' }).success).toBe(false)
})
+ it('points trends explanations at explain-chart only when it can render it', () => {
+ const explainChartTool = makeTool('explain-chart', URI_MAP['explain-chart'])
+
+ expect(createRenderUiTool([queryTrendsTool, explainChartTool], mockContext)!.description).toContain(
+ 'end by rendering `explain-chart`'
+ )
+ expect(createRenderUiTool([queryTrendsTool], mockContext)!.description).not.toContain('explain-chart')
+ })
+
it('advertises the render-ui input schema', () => {
const tool = createRenderUiTool([surveyTool, queryTrendsTool, debugTool, plainTool], mockContext)
expect(tool).not.toBeNull()
diff --git a/services/mcp/tests/unit/ui-apps.test.ts b/services/mcp/tests/unit/ui-apps.test.ts
index 64199e1868bb..be0b1d78c074 100644
--- a/services/mcp/tests/unit/ui-apps.test.ts
+++ b/services/mcp/tests/unit/ui-apps.test.ts
@@ -277,8 +277,8 @@ describe('ui-apps', () => {
}
const storyConfig = resolveCustomApp({
type: 'custom',
- app_name: 'Chart Walkthrough',
- description: 'A walkthrough of a chart',
+ app_name: 'Chart Explanation',
+ description: 'An explanation of a chart',
render_ui: {
component_import: '../components/ExplainChart',
view_component: 'ExplainChart',
@@ -289,7 +289,7 @@ describe('ui-apps', () => {
},
})
if (!storyConfig.render_ui) {
- throw new Error('Expected the walkthrough to configure render-ui dispatch')
+ throw new Error('Expected the explanation to configure render-ui dispatch')
}
const code = generateDispatchModule([