: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 why-did-it-change questions to explain-chart (#126372)
Sam Penningtoncde78e4ba4bb
diff --git a/products/product_analytics/skills/investigate-metric/SKILL.md b/products/product_analytics/skills/investigate-metric/SKILL.mdindex 82c35dd928e6..869266ff74aa 100644--- a/products/product_analytics/skills/investigate-metric/SKILL.md+++ b/products/product_analytics/skills/investigate-metric/SKILL.md@@ -59,7 +59,12 @@ Read `query.kind` from the source the user pointed at:- Saved insight (URL, `short_id`): `posthog:insight-get` → `query.kind`. Use`posthog:insight-query` if you also need the numbers.- A query you already ran or the user pasted: read `kind` directly.-- Nothing pointed at: ask for the URL or short_id. Don't guess.+- A metric the user only names, such as "signups", or shows in a screenshot: find its event+ with `posthog:read-data-schema` and run it as one series over time with+ `posthog:query-trends`. That query is your `TrendsQuery`.+ When `query-trends` cannot express the metric, such as a warehouse-only metric or a custom+ SQL join, run it with `posthog:execute-sql` and treat it as a `HogQLQuery`.+- Nothing pointed at, or several events could be the metric: ask which one. Don't guess.| kind | Playbook || ----------------- | ------------------------------------------------------------- |@@ -86,12 +91,12 @@ 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.-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`.+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), or named a metric you ran as one, 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.+For anything else, such as a metric that only SQL can express, the findings go in a written report.When it is a chart explanation:@@ -145,7 +150,7 @@ in the control = strong hypothesis; moved too = expand the investigation. Skip w## Step 5 — Write findings-**Before you write your answer, call `posthog:explain-chart` when the user gave you a trends insight over time.**+**Before you write your answer, call `posthog:explain-chart` when the investigation has a `TrendsQuery` over time.**Do this after a long investigation too, and when most of your evidence is SQL.For anything else, use the written report.diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 0628d297492f..5abcdfdff55d 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -6401,10 +6401,10 @@"feature_flag": "experiment-behavior-comparison"},"explain-chart": {- "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.",+ "description": "Show the person why a trends chart changed: the chart with each moment that stands out highlighted, such as a drop, a spike or a rise, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nUse it to answer \"why did this metric drop, spike or change?\" about one value over time, when the person gives you a saved insight, a dashboard tile or a screenshot of a chart, or only names the metric. Read this schema when the investigation starts, and call the tool before your final reply, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`. When there is no saved insight, run the metric with `query-trends` and pass that TrendsQuery as `query`, also when you investigated with SQL. Add 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.",+ "summary": "Explain why a trends chart dropped, spiked or changed, one highlighted moment at a time.","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/"],diff --git a/services/mcp/schema/tool-definitions.json b/services/mcp/schema/tool-definitions.jsonindex e50ae3352652..a830ec887eea 100644--- a/services/mcp/schema/tool-definitions.json+++ b/services/mcp/schema/tool-definitions.json@@ -303,10 +303,10 @@"feature_flag": "insight-data-checks"},"explain-chart": {- "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.",+ "description": "Show the person why a trends chart changed: the chart with each moment that stands out highlighted, such as a drop, a spike or a rise, and a panel that steps through them one chapter at a time, with what happened, the likely cause and the evidence.\n\nUse it to answer \"why did this metric drop, spike or change?\" about one value over time, when the person gives you a saved insight, a dashboard tile or a screenshot of a chart, or only names the metric. Read this schema when the investigation starts, and call the tool before your final reply, after you have looked into the chart yourself (the investigate-metric skill describes how). Pass the saved insight's `insightId`. When there is no saved insight, run the metric with `query-trends` and pass that TrendsQuery as `query`, also when you investigated with SQL. Add 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.",+ "summary": "Explain why a trends chart dropped, spiked or changed, one highlighted moment at a time.","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/"],diff --git a/services/mcp/src/templates/sections/explain-chart.md b/services/mcp/src/templates/sections/explain-chart.mdindex f4a6c6ec917f..27466c7f2c6f 100644--- a/services/mcp/src/templates/sections/explain-chart.md+++ b/services/mcp/src/templates/sections/explain-chart.md@@ -1,5 +1,11 @@### 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.+When the person asks why a metric changed over time, for example why it dropped, spiked or rose, load the `posthog:investigate-metric` skill and follow it.+This applies to a saved insight or a dashboard tile by link or ID, to a screenshot of a chart, and to a metric the person only names, such as "why did signups drop last week?".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.++- Read the schema of `explain-chart` when you start, and make the chart explanation the last step of your plan. Call it before you write your final reply.+- When there is no saved trends insight, run the metric as one series over time with `query-trends` and pass that TrendsQuery as `query`. Do this also when you investigate with `execute-sql`: give each SQL finding as `evidence` with its `HogQLQuery`.+- When `query-trends` cannot express the metric, such as a warehouse-only metric or a custom SQL join, write the explanation in the chat.+- For a change in a funnel, retention or paths insight, write the explanation in the chat.