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.

chore(mcp): suggest browser checks for visual artifacts (#123151)

Paul D'Ambra3333273a8eb3
diff --git a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md b/docs/published/handbook/engineering/ai/implementing-mcp-tools.md
index d7e68d62c493..db440997cc6a 100644
--- a/docs/published/handbook/engineering/ai/implementing-mcp-tools.md
+++ b/docs/published/handbook/engineering/ai/implementing-mcp-tools.md
@@ -48,6 +48,10 @@ pnpm --filter=@posthog/mcp run generate:ui-apps
MCP tools should be **basic capabilities** – atomic CRUD operations and simple actions.
Agents compose these primitives into higher-level workflows.
+For tools that save a visual artifact, briefly suggest checking the rendered result after substantial visual changes
+when browser access is already available. Skip browser checks for small edits. Check the final saved artifact once after
+all edits, rather than after every tool call. The tool can save the artifact, but it cannot give an agent browser access.
+
**Good tools**:
- List feature flags
diff --git a/products/canvas/mcp/tools.yaml b/products/canvas/mcp/tools.yaml
index 225830ac3bba..0f6decff33ed 100644
--- a/products/canvas/mcp/tools.yaml
+++ b/products/canvas/mcp/tools.yaml
@@ -192,7 +192,8 @@ tools:
finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call
canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is
`queued` or `building`. Stage a draft with canvas-draft-create only when the user asked for a draft or a
- review step.
+ review step. After substantial visual changes, check the final canvas once its build is ready if browser
+ access is already available. Skip browser checks for small edits.
param_overrides:
id:
description: ID of the canvas whose source to edit.
@@ -236,7 +237,8 @@ tools:
publish) — a stale base is rejected with 409 version_conflict; re-read the layout, re-apply, and patch
again. To fill a drawn box: update_placement with changes {status: "live", component: <component canvas id>,
config: {...}}. The component must be published (canvas-list kind=component shows component_meta and
- published_build_id) and the config must match its configSchema.
+ published_build_id) and the config must match its configSchema. After substantial visual changes, check the
+ final live canvas once if browser access is already available. Skip browser checks for small edits.
param_overrides:
id:
description: ID of the grid canvas whose layout to patch.
@@ -257,7 +259,8 @@ tools:
component's configSchema); errors reject the publish and leave the canvas untouched. The new version is live
immediately — no build. `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before
the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, rebuild
- the document on the new head, and publish again.
+ the document on the new head, and publish again. After substantial visual changes, check the final live
+ canvas once if browser access is already available. Skip browser checks for small edits.
param_overrides:
id:
description: ID of the grid canvas whose layout to publish.
@@ -360,7 +363,8 @@ tools:
this tool is what saves it. The response's `build` carries the build status: `ready` means the build
finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call
canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is
- `queued` or `building`.
+ `queued` or `building`. After substantial visual changes, check the final canvas once its build is ready if
+ browser access is already available. Skip browser checks for small edits.
param_overrides:
id:
description: ID of the canvas whose source to publish.
diff --git a/products/dashboards/mcp/tools.yaml b/products/dashboards/mcp/tools.yaml
index dbe5ba29baef..45c7289b3ac7 100644
--- a/products/dashboards/mcp/tools.yaml
+++ b/products/dashboards/mcp/tools.yaml
@@ -31,7 +31,9 @@ tools:
weekly or monthly tracking, team overviews, launch and health boards. It is the wrong one for a deep dive:
an investigation with a narrative, intermediate steps, and a conclusion belongs in a notebook (`search
notebooks-`), which interleaves prose with executable SQL and Python cells. When a deep dive turns up a few
- metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard.
+ metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard. After
+ substantial visual changes, check the final saved dashboard once if browser access is already available.
+ Skip browser checks for small edits.
agent_note:
If you have not loaded the building-a-dashboard skill in this conversation, load it now, before you add
tiles. Consider offering the user a recurring delivery of this dashboard as a next step, but only when the
@@ -151,7 +153,8 @@ tools:
or editing guidance. PostHog's Data Catalog is the semantic layer. Before you reference a reusable metric,
call metric-list and metric-describe. If no governed definition exists, use data-catalog-metric-create
instead of writing the definition in `agent_context`. Authenticated dashboard APIs return agent context;
- shared and exported dashboards omit it.
+ shared and exported dashboards omit it. After substantial visual changes, check the final saved dashboard
+ once if browser access is already available. Skip browser checks for small edits.
dashboard-delete:
operation: dashboards_destroy
enabled: true
@@ -338,6 +341,8 @@ tools:
each tile's `layouts` with dashboard-update instead. This tool repacks only the tiles in `tile_order`. To
repack the whole dashboard, include every tile ID. Tiles omitted from `tile_order` keep their positions and
can overlap the repacked tiles. This tool does not set different sizes or positions for individual tiles.
+ After substantial visual changes, check the final saved dashboard once if browser access is already
+ available. Skip browser checks for small edits.
dashboard-templates-list:
operation: dashboard_templates_list
enabled: true
@@ -457,7 +462,8 @@ tools:
`badge`: `winner` shows a crown, for example on the best tile in a group, and `cheeky-hog` shows a hedgehog
on hover. Set `badge` or `group_key` to null to remove it. To add new widget tiles to this dashboard, use
dashboard-widgets-batch-add instead. The returned tiles omit insight results to save context — use
- dashboard-insights-run to fetch the actual data for each insight.
+ dashboard-insights-run to fetch the actual data for each insight. After substantial visual changes, check
+ the final saved dashboard once if browser access is already available. Skip browser checks for small edits.
exclude_params:
- creation_mode
- is_shared
@@ -561,7 +567,8 @@ tools:
Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's
Data Catalog is the semantic layer. Use data-catalog-metric-create or data-catalog-metric-update for
canonical metric definitions instead of writing them in `agent_context`. Only the fields you provide are
- updated; omitted fields are left unchanged.
+ updated; omitted fields are left unchanged. After substantial visual changes, check the final saved
+ dashboard once if browser access is already available. Skip browser checks for small edits.
param_overrides:
id:
cast: string-int
@@ -601,7 +608,9 @@ tools:
is a map of filter id to property filter entries. An invalid config returns a 400 that names each invalid
field. For a single tile, pass a one-element `widgets` array. Tiles stack at the bottom when layouts are
omitted. Returns all created tiles; use dashboard-widgets-run to fetch live data. This only adds new tiles —
- to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed).
+ to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed). After
+ substantial visual changes, check the final saved dashboard once if browser access is already available.
+ Skip browser checks for small edits.
param_overrides:
id:
cast: string-int
@@ -625,7 +634,8 @@ tools:
the tile's widget_type from dashboard-widget-catalog-list, passing `widget_type` to fetch only that type.
All updates succeed or fail together. Tile placement (layout, show_description) is not changed here — use
dashboard-update or dashboard-reorder-tiles for that. To add new widgets, use dashboard-widgets-batch-add;
- to remove one, use dashboard-delete-tile.
+ to remove one, use dashboard-delete-tile. After substantial visual changes, check the final saved dashboard
+ once if browser access is already available. Skip browser checks for small edits.
param_overrides:
id:
cast: string-int
diff --git a/products/notebooks/mcp/tools.yaml b/products/notebooks/mcp/tools.yaml
index e2d8672aaadb..a41089c0707e 100644
--- a/products/notebooks/mcp/tools.yaml
+++ b/products/notebooks/mcp/tools.yaml
@@ -82,7 +82,9 @@ tools:
The server stores the notebook as a markdown notebook: it converts this document, embedded charts included,
into markdown with component tags. When you update the notebook later, notebooks-retrieve shows its content
as one ph-markdown-notebook node, so keep that structure and edit attrs.markdown. For step-by-step data
- analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead.
+ analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead. After substantial visual
+ changes, check the final saved notebook once if browser access is already available. Skip browser checks for
+ small edits.
exclude_params:
- _create_in_folder
feature_flag: revamped-py-notebooks
@@ -231,7 +233,8 @@ tools:
updating the content field, you must provide the current version number for optimistic concurrency control.
Retrieve the notebook first to get the latest version. If the notebook content is a single
ph-markdown-notebook node, preserve that structure and update attrs.markdown with valid markdown instead of
- replacing it with legacy rich-text blocks.
+ replacing it with legacy rich-text blocks. After substantial visual changes, check the final saved notebook
+ once if browser access is already available. Skip browser checks for small edits.
exclude_params:
- _create_in_folder
param_overrides:
@@ -362,7 +365,8 @@ tools:
contract to a dataframe in this notebook with `{source: "dataframe_name"}`. When source columns do not match
the contract, add a pure Hog expression in `hog` that receives `rows`, `columns`, and `frame` and returns a
list of objects with the contract's columns. Omit version_id or pass null to follow the latest shared
- version; pass a version UUID to pin this placement.
+ version; pass a version UUID to pin this placement. After substantial visual changes, check the final saved
+ notebook once if browser access is already available. Skip browser checks for small edits.
response:
exclude:
- artifact_url
diff --git a/products/product_analytics/mcp/tools.yaml b/products/product_analytics/mcp/tools.yaml
index 4780b7d69466..41526cb11f87 100644
--- a/products/product_analytics/mcp/tools.yaml
+++ b/products/product_analytics/mcp/tools.yaml
@@ -129,7 +129,9 @@ tools:
pageview or event-volume counts, and skip high-cardinality breakdowns. Judge the metric, not the request. A
newly created insight, or one the user just asked to see, is not throwaway for that reason. If the user
already declined an alert in this conversation, do not offer again. If alert-create is unavailable, say
- nothing about alerts. Wait for the user to accept before creating an alert.
+ nothing about alerts. Wait for the user to accept before creating an alert. After substantial visual
+ changes, check the final saved insight once if browser access is already available. Skip browser checks for
+ small edits.
exclude_params:
- query
include_params:
@@ -229,7 +231,8 @@ tools:
status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query
tool with the same identifier if you want to see the recomputed results. Query uses the same format as
insight-create. Replacing query replaces the entire definition; include all filters and visualization
- settings you want to retain.
+ settings you want to retain. After substantial visual changes, check the final saved insight once if browser
+ access is already available. Skip browser checks for small edits.
agent_note:
If this update added the insight to a dashboard through the `dashboards` field, consider offering the user a
recurring delivery of that dashboard as a next step. `dashboards` is a full replacement, so only offer when
diff --git a/products/surveys/mcp/tools.yaml b/products/surveys/mcp/tools.yaml
index 730dcd0f23a3..d35bef6368b8 100644
--- a/products/surveys/mcp/tools.yaml
+++ b/products/surveys/mcp/tools.yaml
@@ -41,7 +41,8 @@ tools:
external_survey. Keep surveys short unless the user asks for a longer flow. Survey content is public: anyone
can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and
a hosted survey shows them on its public page. Tell the user before putting a customer name or other private
- detail in a survey.
+ detail in a survey. For substantial visual changes, preview the final draft once before launch if browser
+ access is already available. Skip browser checks for small edits.
include_params:
- name
- description
@@ -215,7 +216,8 @@ tools:
not send null to clear a field unless the user explicitly asked to remove it. Survey content is public:
anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's
browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or
- other private detail in a survey.
+ other private detail in a survey. For substantial visual changes, preview the final survey once if browser
+ access is already available. Skip browser checks for small edits.
include_params:
- id
- name
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 7ad125385513..b005c1edd84d 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -2430,7 +2430,7 @@
}
},
"canvas-edit-create": {
- "description": "Change an existing canvas by sending only the edits, not the whole project. This is the default way to save a change to a canvas that already has source. Operations apply in order and all or nothing: `str_replace` (replace `old_string` with `new_string` in `path`; copy `old_string` from the file with a few surrounding lines so it matches exactly one place, or set `replace_all`), `write` (a file's complete `content`, for new files or full rewrites), `delete`, and `rename` (to `new_path`). When the change needs a capability the canvas does not declare yet (for example a new `ph.state` scope), also send `capabilities` with the complete new capabilities in the same edit; do not switch to canvas-publish-create for that. Example operation: {\"op\": \"str_replace\", \"path\": \"src/canvas.tsx\", \"old_string\": \"<CardTitle>Users</CardTitle>\", \"new_string\": \"<CardTitle>Daily active users</CardTitle>\"}. A 400 lists each failed operation by index: `edit_no_match` shows the closest lines of the file, `edit_ambiguous_match` lists the matching lines. Fix those operations and send the edit again; if a replacement fails twice, `write` the whole file instead. `expected_current_version_id` is REQUIRED (from canvas-source-retrieve, or the `current_version_id` a previous edit returned; null only for a never-published canvas). A stale base is rejected with 409 version_conflict: re-read the source and edit again. The edited project is validated, published, and built like canvas-publish-create. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. Stage a draft with canvas-draft-create only when the user asked for a draft or a review step.",
+ "description": "Change an existing canvas by sending only the edits, not the whole project. This is the default way to save a change to a canvas that already has source. Operations apply in order and all or nothing: `str_replace` (replace `old_string` with `new_string` in `path`; copy `old_string` from the file with a few surrounding lines so it matches exactly one place, or set `replace_all`), `write` (a file's complete `content`, for new files or full rewrites), `delete`, and `rename` (to `new_path`). When the change needs a capability the canvas does not declare yet (for example a new `ph.state` scope), also send `capabilities` with the complete new capabilities in the same edit; do not switch to canvas-publish-create for that. Example operation: {\"op\": \"str_replace\", \"path\": \"src/canvas.tsx\", \"old_string\": \"<CardTitle>Users</CardTitle>\", \"new_string\": \"<CardTitle>Daily active users</CardTitle>\"}. A 400 lists each failed operation by index: `edit_no_match` shows the closest lines of the file, `edit_ambiguous_match` lists the matching lines. Fix those operations and send the edit again; if a replacement fails twice, `write` the whole file instead. `expected_current_version_id` is REQUIRED (from canvas-source-retrieve, or the `current_version_id` a previous edit returned; null only for a never-published canvas). A stale base is rejected with 409 version_conflict: re-read the source and edit again. The edited project is validated, published, and built like canvas-publish-create. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. Stage a draft with canvas-draft-create only when the user asked for a draft or a review step. After substantial visual changes, check the final canvas once its build is ready if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Edit canvas source files",
@@ -2460,7 +2460,7 @@
}
},
"canvas-layout-patch": {
- "description": "Apply surgical operations to a grid canvas's layout — the DEFAULT way to change one: add_placement (a new widget box), update_placement (fill a box with a component, move/resize it, change its status or config), remove_placement, set_grid. Operations apply in order to the current layout, the result is validated atomically, and the new version is live immediately (layout is data — no build). `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, re-apply, and patch again. To fill a drawn box: update_placement with changes {status: \"live\", component: <component canvas id>, config: {...}}. The component must be published (canvas-list kind=component shows component_meta and published_build_id) and the config must match its configSchema.",
+ "description": "Apply surgical operations to a grid canvas's layout — the DEFAULT way to change one: add_placement (a new widget box), update_placement (fill a box with a component, move/resize it, change its status or config), remove_placement, set_grid. Operations apply in order to the current layout, the result is validated atomically, and the new version is live immediately (layout is data — no build). `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, re-apply, and patch again. To fill a drawn box: update_placement with changes {status: \"live\", component: <component canvas id>, config: {...}}. The component must be published (canvas-list kind=component shows component_meta and published_build_id) and the config must match its configSchema. After substantial visual changes, check the final live canvas once if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Patch grid canvas layout",
@@ -2475,7 +2475,7 @@
}
},
"canvas-layout-publish": {
- "description": "Publish a COMPLETE layout document as a grid canvas's new head version. Prefer canvas-layout-patch for incremental changes — full publish is for creating an initial layout or restructuring the whole grid. The layout is validated first (grid bounds, overlaps, component references, per-placement config against each component's configSchema); errors reject the publish and leave the canvas untouched. The new version is live immediately — no build. `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, rebuild the document on the new head, and publish again.",
+ "description": "Publish a COMPLETE layout document as a grid canvas's new head version. Prefer canvas-layout-patch for incremental changes — full publish is for creating an initial layout or restructuring the whole grid. The layout is validated first (grid bounds, overlaps, component references, per-placement config against each component's configSchema); errors reject the publish and leave the canvas untouched. The new version is live immediately — no build. `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, rebuild the document on the new head, and publish again. After substantial visual changes, check the final live canvas once if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Publish grid canvas layout",
@@ -2535,7 +2535,7 @@
}
},
"canvas-publish-create": {
- "description": "Publish the COMPLETE source project of a canvas as its new head version and queue a server-side build. Use it for a canvas's first version or to replace the whole project; for a change to an existing canvas, send only the edits with canvas-edit-create. Publishing goes live immediately; stage the change with canvas-draft-create only when the user asked for a draft or a review step. The project is validated first — error diagnostics reject the publish (400) and leave the canvas untouched. Pass `expected_current_version_id` (from canvas-source-retrieve) so a concurrent edit is rejected with 409 version_conflict instead of overwritten; on conflict, re-read the source, re-apply your edits, and publish against the new head. A 429 means the team's build capacity is exhausted — wait a moment and retry. Declare the canvas's runtime capabilities (insights, capture events, inline queries) in `project.capabilities`. A project that shows PostHog data must make every figure verifiable before publishing: an insight-backed metric links its saved insight (ph.openExternal with a URL from generate-app-url); an ad-hoc ph.query figure exposes the exact query that ran in a modal or collapsed area. The canvas lives in PostHog, not on disk — this tool is what saves it. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`.",
+ "description": "Publish the COMPLETE source project of a canvas as its new head version and queue a server-side build. Use it for a canvas's first version or to replace the whole project; for a change to an existing canvas, send only the edits with canvas-edit-create. Publishing goes live immediately; stage the change with canvas-draft-create only when the user asked for a draft or a review step. The project is validated first — error diagnostics reject the publish (400) and leave the canvas untouched. Pass `expected_current_version_id` (from canvas-source-retrieve) so a concurrent edit is rejected with 409 version_conflict instead of overwritten; on conflict, re-read the source, re-apply your edits, and publish against the new head. A 429 means the team's build capacity is exhausted — wait a moment and retry. Declare the canvas's runtime capabilities (insights, capture events, inline queries) in `project.capabilities`. A project that shows PostHog data must make every figure verifiable before publishing: an insight-backed metric links its saved insight (ph.openExternal with a URL from generate-app-url); an ad-hoc ph.query figure exposes the exact query that ran in a modal or collapsed area. The canvas lives in PostHog, not on disk — this tool is what saves it. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. After substantial visual changes, check the final canvas once its build is ready if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Publish canvas source project",
@@ -3912,7 +3912,7 @@
"feature_flag": "customer-analytics-customer-tasks"
},
"dashboard-create": {
- "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. To add widget tiles after creation, see dashboard-widget-catalog-list for available widget types and dashboard-widgets-batch-add to add them.\nLoad the building-a-dashboard skill before you create or change a dashboard. It covers when to update an existing dashboard instead, which insights to reuse, and how to lay out the tiles.\nA dashboard is the right artifact for a set of metrics someone will check repeatedly over time — monitoring, weekly or monthly tracking, team overviews, launch and health boards. It is the wrong one for a deep dive: an investigation with a narrative, intermediate steps, and a conclusion belongs in a notebook (`search notebooks-`), which interleaves prose with executable SQL and Python cells. When a deep dive turns up a few metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard.",
+ "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. To add widget tiles after creation, see dashboard-widget-catalog-list for available widget types and dashboard-widgets-batch-add to add them.\nLoad the building-a-dashboard skill before you create or change a dashboard. It covers when to update an existing dashboard instead, which insights to reuse, and how to lay out the tiles.\nA dashboard is the right artifact for a set of metrics someone will check repeatedly over time — monitoring, weekly or monthly tracking, team overviews, launch and health boards. It is the wrong one for a deep dive: an investigation with a narrative, intermediate steps, and a conclusion belongs in a notebook (`search notebooks-`), which interleaves prose with executable SQL and Python cells. When a deep dive turns up a few metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Create dashboard",
@@ -3927,7 +3927,7 @@
}
},
"dashboard-create-tile": {
- "description": "Add a dashboard tile. Set `type` to text or image. Use Markdown headings, dividers, or notes for a text tile. The desktop grid is 12 columns wide. A typical text heading uses a thin full-width banner (e.g. `layouts.sm = {x: 0, y: 0, w: 12, h: 1}`). If `layouts` is omitted, the dashboard places the tile at the bottom with the default size. Use `layouts` to control the size and placement of this text or image tile. To lay out insight tiles or create a mixed layout, first call dashboard-get to get tile IDs, then use dashboard-update with complete `layouts.sm` boxes. An image tile body must contain exactly one Markdown image, such as `![Accessible description](https://example.com/image.png)`. The image URL must be reachable by dashboard viewers. Put concise, user-facing copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Before you reference a reusable metric, call metric-list and metric-describe. If no governed definition exists, use data-catalog-metric-create instead of writing the definition in `agent_context`. Authenticated dashboard APIs return agent context; shared and exported dashboards omit it.",
+ "description": "Add a dashboard tile. Set `type` to text or image. Use Markdown headings, dividers, or notes for a text tile. The desktop grid is 12 columns wide. A typical text heading uses a thin full-width banner (e.g. `layouts.sm = {x: 0, y: 0, w: 12, h: 1}`). If `layouts` is omitted, the dashboard places the tile at the bottom with the default size. Use `layouts` to control the size and placement of this text or image tile. To lay out insight tiles or create a mixed layout, first call dashboard-get to get tile IDs, then use dashboard-update with complete `layouts.sm` boxes. An image tile body must contain exactly one Markdown image, such as `![Accessible description](https://example.com/image.png)`. The image URL must be reachable by dashboard viewers. Put concise, user-facing copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Before you reference a reusable metric, call metric-list and metric-describe. If no governed definition exists, use data-catalog-metric-create instead of writing the definition in `agent_context`. Authenticated dashboard APIs return agent context; shared and exported dashboards omit it. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Create dashboard tile",
@@ -4003,7 +4003,7 @@
"reads_ingested_data": "events"
},
"dashboard-reorder-tiles": {
- "description": "Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. First, use dashboard-get to see current tile IDs. By default existing tile widths and heights are preserved. Use the layout parameter only when every tile should use the same size: `two_column` makes every tile 6-wide, `three_column` makes every tile 4-wide, and `full_width` makes every tile 12-wide. For a mixed layout, set each tile's `layouts` with dashboard-update instead. This tool repacks only the tiles in `tile_order`. To repack the whole dashboard, include every tile ID. Tiles omitted from `tile_order` keep their positions and can overlap the repacked tiles. This tool does not set different sizes or positions for individual tiles.",
+ "description": "Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. First, use dashboard-get to see current tile IDs. By default existing tile widths and heights are preserved. Use the layout parameter only when every tile should use the same size: `two_column` makes every tile 6-wide, `three_column` makes every tile 4-wide, and `full_width` makes every tile 12-wide. For a mixed layout, set each tile's `layouts` with dashboard-update instead. This tool repacks only the tiles in `tile_order`. To repack the whole dashboard, include every tile ID. Tiles omitted from `tile_order` keep their positions and can overlap the repacked tiles. This tool does not set different sizes or positions for individual tiles. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Reorder dashboard tiles",
@@ -4078,7 +4078,7 @@
}
},
"dashboard-update": {
- "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. After you create or add insight tiles, call dashboard-get to get their tile IDs, then pass `tiles` with each tile's `id` and a `layouts` object holding x, y, w, and h per breakpoint. This works for every tile type, including insight tiles. The desktop grid (`layouts.sm`) is 12 columns wide. Set each tile's width and height for its content and importance. Width can be any whole number from 1 to 12, subject to the tile's minimum size. Mixed rows such as 8-wide and 4-wide tiles can show hierarchy. A write replaces the tile's whole layout, so send a complete box, not just the value you want to change. Boxes are stored as sent and overlaps are not resolved, so plan the whole grid and send every tile you move in one request. Only set `layouts.sm`: the dashboard derives the mobile layout from the sm order and heights. Use dashboard-reorder-tiles only to repack the whole dashboard with preserved or uniform tile sizes. This tool does not change a widget tile's own settings (`config`, `name`, `description`): use dashboard-widgets-batch-update for that. To group tiles, give each tile in the group the same `group_key`. Set each group's settings in `groups`, a map from group key to settings that replaces the stored map: `title`, `collapsed` to start the group closed, and `color` for a colored dot before the heading (blue, purple, green, yellow, orange, red, or null for no dot). Viewers see each group as a band that they can open and close. Viewers who do not have bands yet, and shared dashboards, see only the group title above its tiles. Put tiles that viewers check less often in a group that starts closed. To mark a tile, set its `badge`: `winner` shows a crown, for example on the best tile in a group, and `cheeky-hog` shows a hedgehog on hover. Set `badge` or `group_key` to null to remove it. To add new widget tiles to this dashboard, use dashboard-widgets-batch-add instead. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight.",
+ "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. After you create or add insight tiles, call dashboard-get to get their tile IDs, then pass `tiles` with each tile's `id` and a `layouts` object holding x, y, w, and h per breakpoint. This works for every tile type, including insight tiles. The desktop grid (`layouts.sm`) is 12 columns wide. Set each tile's width and height for its content and importance. Width can be any whole number from 1 to 12, subject to the tile's minimum size. Mixed rows such as 8-wide and 4-wide tiles can show hierarchy. A write replaces the tile's whole layout, so send a complete box, not just the value you want to change. Boxes are stored as sent and overlaps are not resolved, so plan the whole grid and send every tile you move in one request. Only set `layouts.sm`: the dashboard derives the mobile layout from the sm order and heights. Use dashboard-reorder-tiles only to repack the whole dashboard with preserved or uniform tile sizes. This tool does not change a widget tile's own settings (`config`, `name`, `description`): use dashboard-widgets-batch-update for that. To group tiles, give each tile in the group the same `group_key`. Set each group's settings in `groups`, a map from group key to settings that replaces the stored map: `title`, `collapsed` to start the group closed, and `color` for a colored dot before the heading (blue, purple, green, yellow, orange, red, or null for no dot). Viewers see each group as a band that they can open and close. Viewers who do not have bands yet, and shared dashboards, see only the group title above its tiles. Put tiles that viewers check less often in a group that starts closed. To mark a tile, set its `badge`: `winner` shows a crown, for example on the best tile in a group, and `cheeky-hog` shows a hedgehog on hover. Set `badge` or `group_key` to null to remove it. To add new widget tiles to this dashboard, use dashboard-widgets-batch-add instead. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard",
@@ -4093,7 +4093,7 @@
}
},
"dashboard-update-text-tile": {
- "description": "Update the user-facing markdown body, agent context, layout, or color of an existing text tile on a dashboard. Pass the DashboardTile id as `tile_id` (use dashboard-get to look up tile IDs). Keep concise, human-readable copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Use data-catalog-metric-create or data-catalog-metric-update for canonical metric definitions instead of writing them in `agent_context`. Only the fields you provide are updated; omitted fields are left unchanged.",
+ "description": "Update the user-facing markdown body, agent context, layout, or color of an existing text tile on a dashboard. Pass the DashboardTile id as `tile_id` (use dashboard-get to look up tile IDs). Keep concise, human-readable copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Use data-catalog-metric-create or data-catalog-metric-update for canonical metric definitions instead of writing them in `agent_context`. Only the fields you provide are updated; omitted fields are left unchanged. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard text tile",
@@ -4123,7 +4123,7 @@
}
},
"dashboard-widgets-batch-add": {
- "description": "Add widget tiles to a dashboard atomically via POST .../widgets/batch/ (1–10 tiles). Before writing a config, call dashboard-widget-catalog-list with `widget_type` set to the types you will add, to read their config_schema. The valid widget_type values are in this tool's schema. Pass `widgets` as an array of payloads (widget_type, config, optional name, description, layouts). This schema does not list config keys: build each config from the config_schema of its widget_type in the catalog. widgetFilters, when supported, is a map of filter id to property filter entries. An invalid config returns a 400 that names each invalid field. For a single tile, pass a one-element `widgets` array. Tiles stack at the bottom when layouts are omitted. Returns all created tiles; use dashboard-widgets-run to fetch live data. This only adds new tiles — to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed).",
+ "description": "Add widget tiles to a dashboard atomically via POST .../widgets/batch/ (1–10 tiles). Before writing a config, call dashboard-widget-catalog-list with `widget_type` set to the types you will add, to read their config_schema. The valid widget_type values are in this tool's schema. Pass `widgets` as an array of payloads (widget_type, config, optional name, description, layouts). This schema does not list config keys: build each config from the config_schema of its widget_type in the catalog. widgetFilters, when supported, is a map of filter id to property filter entries. An invalid config returns a 400 that names each invalid field. For a single tile, pass a one-element `widgets` array. Tiles stack at the bottom when layouts are omitted. Returns all created tiles; use dashboard-widgets-run to fetch live data. This only adds new tiles — to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed). After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Add dashboard widgets",
@@ -4138,7 +4138,7 @@
}
},
"dashboard-widgets-batch-update": {
- "description": "Update the settings of existing widgets in place atomically (1–10), without delete-and-re-add. Edits widget settings only — `config`, `name`, and `description`. Pass `widgets` as an array of payloads, each identified by its DashboardTile `tile_id` (use dashboard-get to look up widget tile IDs) plus the settings to change. Only the fields you provide per widget are updated; omitted fields are left unchanged. A config update replaces only the top-level keys you send. This schema does not list config keys: read the config_schema of the tile's widget_type from dashboard-widget-catalog-list, passing `widget_type` to fetch only that type. All updates succeed or fail together. Tile placement (layout, show_description) is not changed here — use dashboard-update or dashboard-reorder-tiles for that. To add new widgets, use dashboard-widgets-batch-add; to remove one, use dashboard-delete-tile.",
+ "description": "Update the settings of existing widgets in place atomically (1–10), without delete-and-re-add. Edits widget settings only — `config`, `name`, and `description`. Pass `widgets` as an array of payloads, each identified by its DashboardTile `tile_id` (use dashboard-get to look up widget tile IDs) plus the settings to change. Only the fields you provide per widget are updated; omitted fields are left unchanged. A config update replaces only the top-level keys you send. This schema does not list config keys: read the config_schema of the tile's widget_type from dashboard-widget-catalog-list, passing `widget_type` to fetch only that type. All updates succeed or fail together. Tile placement (layout, show_description) is not changed here — use dashboard-update or dashboard-reorder-tiles for that. To add new widgets, use dashboard-widgets-batch-add; to remove one, use dashboard-delete-tile. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard widget settings",
@@ -8127,7 +8127,7 @@
}
},
"insight-update": {
- "description": "Update a saved insight by numeric `id` or `short_id`. Can update name, description, query, tags, favorited status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query tool with the same identifier if you want to see the recomputed results. Query uses the same format as insight-create. Replacing query replaces the entire definition; include all filters and visualization settings you want to retain.",
+ "description": "Update a saved insight by numeric `id` or `short_id`. Can update name, description, query, tags, favorited status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query tool with the same identifier if you want to see the recomputed results. Query uses the same format as insight-create. Replacing query replaces the entire definition; include all filters and visualization settings you want to retain. After substantial visual changes, check the final saved insight once if browser access is already available. Skip browser checks for small edits.",
"category": "Product analytics",
"feature": "product_analytics",
"summary": "Update insight",
@@ -10773,7 +10773,7 @@
"feature_flag": "revamped-py-notebooks"
},
"notebooks-create": {
- "description": "Create a new notebook. Provide a title and content. Content is a JSON object representing the notebook's rich text document structure (ProseMirror-based). Returns the created notebook with its short_id. Embedded charts use `{type: \"ph-query\", attrs: {nodeId, query}}` nodes. The `query` object must be one of: (a) `{kind: \"DataVisualizationNode\", source: {kind: \"HogQLQuery\", query: \"SELECT ...\"}, display: \"ActionsBar\", chartSettings: {...}}` for SQL charts — do NOT wrap this in an InsightVizNode; (b) `{kind: \"InsightVizNode\", source: <TrendsQuery | FunnelsQuery | RetentionQuery | PathsQuery | StickinessQuery | LifecycleQuery>}` for product-analytics insights; or (c) `{kind: \"SavedInsightNode\", shortId: \"...\"}` to embed a saved insight. The server rejects other shapes and auto-corrects the common `InsightVizNode` wrapping a SQL chart. Give every embedded node a short `attrs.title` saying what it shows — it renders in the node's header and is what a reader skims instead of the query.\nThe server stores the notebook as a markdown notebook: it converts this document, embedded charts included, into markdown with component tags. When you update the notebook later, notebooks-retrieve shows its content as one ph-markdown-notebook node, so keep that structure and edit attrs.markdown. For step-by-step data analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead.",
+ "description": "Create a new notebook. Provide a title and content. Content is a JSON object representing the notebook's rich text document structure (ProseMirror-based). Returns the created notebook with its short_id. Embedded charts use `{type: \"ph-query\", attrs: {nodeId, query}}` nodes. The `query` object must be one of: (a) `{kind: \"DataVisualizationNode\", source: {kind: \"HogQLQuery\", query: \"SELECT ...\"}, display: \"ActionsBar\", chartSettings: {...}}` for SQL charts — do NOT wrap this in an InsightVizNode; (b) `{kind: \"InsightVizNode\", source: <TrendsQuery | FunnelsQuery | RetentionQuery | PathsQuery | StickinessQuery | LifecycleQuery>}` for product-analytics insights; or (c) `{kind: \"SavedInsightNode\", shortId: \"...\"}` to embed a saved insight. The server rejects other shapes and auto-corrects the common `InsightVizNode` wrapping a SQL chart. Give every embedded node a short `attrs.title` saying what it shows — it renders in the node's header and is what a reader skims instead of the query.\nThe server stores the notebook as a markdown notebook: it converts this document, embedded charts included, into markdown with component tags. When you update the notebook later, notebooks-retrieve shows its content as one ph-markdown-notebook node, so keep that structure and edit attrs.markdown. For step-by-step data analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Create notebook",
@@ -10853,7 +10853,7 @@
"feature_flag": "revamped-py-notebooks"
},
"notebooks-partial-update": {
- "description": "Update an existing notebook by short_id. Can update title, content, and deleted status. IMPORTANT: when updating the content field, you must provide the current version number for optimistic concurrency control. Retrieve the notebook first to get the latest version. If the notebook content is a single ph-markdown-notebook node, preserve that structure and update attrs.markdown with valid markdown instead of replacing it with legacy rich-text blocks.",
+ "description": "Update an existing notebook by short_id. Can update title, content, and deleted status. IMPORTANT: when updating the content field, you must provide the current version number for optimistic concurrency control. Retrieve the notebook first to get the latest version. If the notebook content is a single ph-markdown-notebook node, preserve that structure and update attrs.markdown with valid markdown instead of replacing it with legacy rich-text blocks. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Update notebook",
@@ -10921,7 +10921,7 @@
"feature_flag": "revamped-py-notebooks"
},
"notebooks-widget-attach": {
- "description": "Attach a reusable widget to an existing Widget node in a notebook. First save a `<Widget nodeId=\"...\" />` element in the notebook markdown, then pass that node_id here. Map every logical input slot from the widget contract to a dataframe in this notebook with `{source: \"dataframe_name\"}`. When source columns do not match the contract, add a pure Hog expression in `hog` that receives `rows`, `columns`, and `frame` and returns a list of objects with the contract's columns. Omit version_id or pass null to follow the latest shared version; pass a version UUID to pin this placement.",
+ "description": "Attach a reusable widget to an existing Widget node in a notebook. First save a `<Widget nodeId=\"...\" />` element in the notebook markdown, then pass that node_id here. Map every logical input slot from the widget contract to a dataframe in this notebook with `{source: \"dataframe_name\"}`. When source columns do not match the contract, add a pure Hog expression in `hog` that receives `rows`, `columns`, and `frame` and returns a list of objects with the contract's columns. Omit version_id or pass null to follow the latest shared version; pass a version UUID to pin this placement. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Add reusable widget to notebook",
@@ -14067,7 +14067,7 @@
}
},
"survey-create": {
- "description": "Creates a new survey in the project. For the draft, targeting, preview, and launch workflow, load the creating-surveys skill when available. Use this for both in-app surveys and hosted forms. Prefer draft creation by default and do not set start_date unless the user explicitly asks to launch immediately. For in-app surveys, popover is the default unless the user asks for widget or api. For hosted forms, use external_survey. Keep surveys short unless the user asks for a longer flow. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey.",
+ "description": "Creates a new survey in the project. For the draft, targeting, preview, and launch workflow, load the creating-surveys skill when available. Use this for both in-app surveys and hosted forms. Prefer draft creation by default and do not set start_date unless the user explicitly asks to launch immediately. For in-app surveys, popover is the default unless the user asks for widget or api. For hosted forms, use external_survey. Keep surveys short unless the user asks for a longer flow. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey. For substantial visual changes, preview the final draft once before launch if browser access is already available. Skip browser checks for small edits.",
"category": "Surveys",
"feature": "surveys",
"summary": "Creates a new survey in the project.",
@@ -14157,7 +14157,7 @@
}
},
"survey-update": {
- "description": "Update an existing survey by ID. Omitted top-level fields are preserved, but nested objects and arrays you provide may replace existing values. Before changing questions, conditions, appearance, targeting, translations, or hosted-form content, retrieve the survey first and preserve fields that should remain. Do not send null to clear a field unless the user explicitly asked to remove it. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey.",
+ "description": "Update an existing survey by ID. Omitted top-level fields are preserved, but nested objects and arrays you provide may replace existing values. Before changing questions, conditions, appearance, targeting, translations, or hosted-form content, retrieve the survey first and preserve fields that should remain. Do not send null to clear a field unless the user explicitly asked to remove it. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey. For substantial visual changes, preview the final survey once if browser access is already available. Skip browser checks for small edits.",
"category": "Surveys",
"feature": "surveys",
"summary": "Update an existing survey by ID.",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 5da1e88b78d1..c5c2049eafb5 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -2445,7 +2445,7 @@
}
},
"canvas-edit-create": {
- "description": "Change an existing canvas by sending only the edits, not the whole project. This is the default way to save a change to a canvas that already has source. Operations apply in order and all or nothing: `str_replace` (replace `old_string` with `new_string` in `path`; copy `old_string` from the file with a few surrounding lines so it matches exactly one place, or set `replace_all`), `write` (a file's complete `content`, for new files or full rewrites), `delete`, and `rename` (to `new_path`). When the change needs a capability the canvas does not declare yet (for example a new `ph.state` scope), also send `capabilities` with the complete new capabilities in the same edit; do not switch to canvas-publish-create for that. Example operation: {\"op\": \"str_replace\", \"path\": \"src/canvas.tsx\", \"old_string\": \"<CardTitle>Users</CardTitle>\", \"new_string\": \"<CardTitle>Daily active users</CardTitle>\"}. A 400 lists each failed operation by index: `edit_no_match` shows the closest lines of the file, `edit_ambiguous_match` lists the matching lines. Fix those operations and send the edit again; if a replacement fails twice, `write` the whole file instead. `expected_current_version_id` is REQUIRED (from canvas-source-retrieve, or the `current_version_id` a previous edit returned; null only for a never-published canvas). A stale base is rejected with 409 version_conflict: re-read the source and edit again. The edited project is validated, published, and built like canvas-publish-create. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. Stage a draft with canvas-draft-create only when the user asked for a draft or a review step.",
+ "description": "Change an existing canvas by sending only the edits, not the whole project. This is the default way to save a change to a canvas that already has source. Operations apply in order and all or nothing: `str_replace` (replace `old_string` with `new_string` in `path`; copy `old_string` from the file with a few surrounding lines so it matches exactly one place, or set `replace_all`), `write` (a file's complete `content`, for new files or full rewrites), `delete`, and `rename` (to `new_path`). When the change needs a capability the canvas does not declare yet (for example a new `ph.state` scope), also send `capabilities` with the complete new capabilities in the same edit; do not switch to canvas-publish-create for that. Example operation: {\"op\": \"str_replace\", \"path\": \"src/canvas.tsx\", \"old_string\": \"<CardTitle>Users</CardTitle>\", \"new_string\": \"<CardTitle>Daily active users</CardTitle>\"}. A 400 lists each failed operation by index: `edit_no_match` shows the closest lines of the file, `edit_ambiguous_match` lists the matching lines. Fix those operations and send the edit again; if a replacement fails twice, `write` the whole file instead. `expected_current_version_id` is REQUIRED (from canvas-source-retrieve, or the `current_version_id` a previous edit returned; null only for a never-published canvas). A stale base is rejected with 409 version_conflict: re-read the source and edit again. The edited project is validated, published, and built like canvas-publish-create. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. Stage a draft with canvas-draft-create only when the user asked for a draft or a review step. After substantial visual changes, check the final canvas once its build is ready if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Edit canvas source files",
@@ -2475,7 +2475,7 @@
}
},
"canvas-layout-patch": {
- "description": "Apply surgical operations to a grid canvas's layout — the DEFAULT way to change one: add_placement (a new widget box), update_placement (fill a box with a component, move/resize it, change its status or config), remove_placement, set_grid. Operations apply in order to the current layout, the result is validated atomically, and the new version is live immediately (layout is data — no build). `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, re-apply, and patch again. To fill a drawn box: update_placement with changes {status: \"live\", component: <component canvas id>, config: {...}}. The component must be published (canvas-list kind=component shows component_meta and published_build_id) and the config must match its configSchema.",
+ "description": "Apply surgical operations to a grid canvas's layout — the DEFAULT way to change one: add_placement (a new widget box), update_placement (fill a box with a component, move/resize it, change its status or config), remove_placement, set_grid. Operations apply in order to the current layout, the result is validated atomically, and the new version is live immediately (layout is data — no build). `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, re-apply, and patch again. To fill a drawn box: update_placement with changes {status: \"live\", component: <component canvas id>, config: {...}}. The component must be published (canvas-list kind=component shows component_meta and published_build_id) and the config must match its configSchema. After substantial visual changes, check the final live canvas once if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Patch grid canvas layout",
@@ -2490,7 +2490,7 @@
}
},
"canvas-layout-publish": {
- "description": "Publish a COMPLETE layout document as a grid canvas's new head version. Prefer canvas-layout-patch for incremental changes — full publish is for creating an initial layout or restructuring the whole grid. The layout is validated first (grid bounds, overlaps, component references, per-placement config against each component's configSchema); errors reject the publish and leave the canvas untouched. The new version is live immediately — no build. `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, rebuild the document on the new head, and publish again.",
+ "description": "Publish a COMPLETE layout document as a grid canvas's new head version. Prefer canvas-layout-patch for incremental changes — full publish is for creating an initial layout or restructuring the whole grid. The layout is validated first (grid bounds, overlaps, component references, per-placement config against each component's configSchema); errors reject the publish and leave the canvas untouched. The new version is live immediately — no build. `expected_current_version_id` is REQUIRED (from canvas-layout-get; null only before the first layout publish) — a stale base is rejected with 409 version_conflict; re-read the layout, rebuild the document on the new head, and publish again. After substantial visual changes, check the final live canvas once if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Publish grid canvas layout",
@@ -2550,7 +2550,7 @@
}
},
"canvas-publish-create": {
- "description": "Publish the COMPLETE source project of a canvas as its new head version and queue a server-side build. Use it for a canvas's first version or to replace the whole project; for a change to an existing canvas, send only the edits with canvas-edit-create. Publishing goes live immediately; stage the change with canvas-draft-create only when the user asked for a draft or a review step. The project is validated first — error diagnostics reject the publish (400) and leave the canvas untouched. Pass `expected_current_version_id` (from canvas-source-retrieve) so a concurrent edit is rejected with 409 version_conflict instead of overwritten; on conflict, re-read the source, re-apply your edits, and publish against the new head. A 429 means the team's build capacity is exhausted — wait a moment and retry. Declare the canvas's runtime capabilities (insights, capture events, inline queries) in `project.capabilities`. A project that shows PostHog data must make every figure verifiable before publishing: an insight-backed metric links its saved insight (ph.openExternal with a URL from generate-app-url); an ad-hoc ph.query figure exposes the exact query that ran in a modal or collapsed area. The canvas lives in PostHog, not on disk — this tool is what saves it. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`.",
+ "description": "Publish the COMPLETE source project of a canvas as its new head version and queue a server-side build. Use it for a canvas's first version or to replace the whole project; for a change to an existing canvas, send only the edits with canvas-edit-create. Publishing goes live immediately; stage the change with canvas-draft-create only when the user asked for a draft or a review step. The project is validated first — error diagnostics reject the publish (400) and leave the canvas untouched. Pass `expected_current_version_id` (from canvas-source-retrieve) so a concurrent edit is rejected with 409 version_conflict instead of overwritten; on conflict, re-read the source, re-apply your edits, and publish against the new head. A 429 means the team's build capacity is exhausted — wait a moment and retry. Declare the canvas's runtime capabilities (insights, capture events, inline queries) in `project.capabilities`. A project that shows PostHog data must make every figure verifiable before publishing: an insight-backed metric links its saved insight (ph.openExternal with a URL from generate-app-url); an ad-hoc ph.query figure exposes the exact query that ran in a modal or collapsed area. The canvas lives in PostHog, not on disk — this tool is what saves it. The response's `build` carries the build status: `ready` means the build finished, and the canvas shows it when `canvas.published_build_id` is its id, so do not call canvas-builds-retrieve; `failed` lists the build errors to fix; poll canvas-builds-retrieve only while it is `queued` or `building`. After substantial visual changes, check the final canvas once its build is ready if browser access is already available. Skip browser checks for small edits.",
"category": "Canvas",
"feature": "canvas",
"summary": "Publish canvas source project",
@@ -3927,7 +3927,7 @@
"feature_flag": "customer-analytics-customer-tasks"
},
"dashboard-create": {
- "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. To add widget tiles after creation, see dashboard-widget-catalog-list for available widget types and dashboard-widgets-batch-add to add them.\nLoad the building-a-dashboard skill before you create or change a dashboard. It covers when to update an existing dashboard instead, which insights to reuse, and how to lay out the tiles.\nA dashboard is the right artifact for a set of metrics someone will check repeatedly over time — monitoring, weekly or monthly tracking, team overviews, launch and health boards. It is the wrong one for a deep dive: an investigation with a narrative, intermediate steps, and a conclusion belongs in a notebook (`search notebooks-`), which interleaves prose with executable SQL and Python cells. When a deep dive turns up a few metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard.",
+ "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. To add widget tiles after creation, see dashboard-widget-catalog-list for available widget types and dashboard-widgets-batch-add to add them.\nLoad the building-a-dashboard skill before you create or change a dashboard. It covers when to update an existing dashboard instead, which insights to reuse, and how to lay out the tiles.\nA dashboard is the right artifact for a set of metrics someone will check repeatedly over time — monitoring, weekly or monthly tracking, team overviews, launch and health boards. It is the wrong one for a deep dive: an investigation with a narrative, intermediate steps, and a conclusion belongs in a notebook (`search notebooks-`), which interleaves prose with executable SQL and Python cells. When a deep dive turns up a few metrics worth tracking, save those as insights rather than reshaping the analysis into a dashboard. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Create dashboard",
@@ -3942,7 +3942,7 @@
}
},
"dashboard-create-tile": {
- "description": "Add a dashboard tile. Set `type` to text or image. Use Markdown headings, dividers, or notes for a text tile. The desktop grid is 12 columns wide. A typical text heading uses a thin full-width banner (e.g. `layouts.sm = {x: 0, y: 0, w: 12, h: 1}`). If `layouts` is omitted, the dashboard places the tile at the bottom with the default size. Use `layouts` to control the size and placement of this text or image tile. To lay out insight tiles or create a mixed layout, first call dashboard-get to get tile IDs, then use dashboard-update with complete `layouts.sm` boxes. An image tile body must contain exactly one Markdown image, such as `![Accessible description](https://example.com/image.png)`. The image URL must be reachable by dashboard viewers. Put concise, user-facing copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Before you reference a reusable metric, call metric-list and metric-describe. If no governed definition exists, use data-catalog-metric-create instead of writing the definition in `agent_context`. Authenticated dashboard APIs return agent context; shared and exported dashboards omit it.",
+ "description": "Add a dashboard tile. Set `type` to text or image. Use Markdown headings, dividers, or notes for a text tile. The desktop grid is 12 columns wide. A typical text heading uses a thin full-width banner (e.g. `layouts.sm = {x: 0, y: 0, w: 12, h: 1}`). If `layouts` is omitted, the dashboard places the tile at the bottom with the default size. Use `layouts` to control the size and placement of this text or image tile. To lay out insight tiles or create a mixed layout, first call dashboard-get to get tile IDs, then use dashboard-update with complete `layouts.sm` boxes. An image tile body must contain exactly one Markdown image, such as `![Accessible description](https://example.com/image.png)`. The image URL must be reachable by dashboard viewers. Put concise, user-facing copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Before you reference a reusable metric, call metric-list and metric-describe. If no governed definition exists, use data-catalog-metric-create instead of writing the definition in `agent_context`. Authenticated dashboard APIs return agent context; shared and exported dashboards omit it. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Create dashboard tile",
@@ -4018,7 +4018,7 @@
"reads_ingested_data": "events"
},
"dashboard-reorder-tiles": {
- "description": "Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. First, use dashboard-get to see current tile IDs. By default existing tile widths and heights are preserved. Use the layout parameter only when every tile should use the same size: `two_column` makes every tile 6-wide, `three_column` makes every tile 4-wide, and `full_width` makes every tile 12-wide. For a mixed layout, set each tile's `layouts` with dashboard-update instead. This tool repacks only the tiles in `tile_order`. To repack the whole dashboard, include every tile ID. Tiles omitted from `tile_order` keep their positions and can overlap the repacked tiles. This tool does not set different sizes or positions for individual tiles.",
+ "description": "Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. First, use dashboard-get to see current tile IDs. By default existing tile widths and heights are preserved. Use the layout parameter only when every tile should use the same size: `two_column` makes every tile 6-wide, `three_column` makes every tile 4-wide, and `full_width` makes every tile 12-wide. For a mixed layout, set each tile's `layouts` with dashboard-update instead. This tool repacks only the tiles in `tile_order`. To repack the whole dashboard, include every tile ID. Tiles omitted from `tile_order` keep their positions and can overlap the repacked tiles. This tool does not set different sizes or positions for individual tiles. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Reorder dashboard tiles",
@@ -4093,7 +4093,7 @@
}
},
"dashboard-update": {
- "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. After you create or add insight tiles, call dashboard-get to get their tile IDs, then pass `tiles` with each tile's `id` and a `layouts` object holding x, y, w, and h per breakpoint. This works for every tile type, including insight tiles. The desktop grid (`layouts.sm`) is 12 columns wide. Set each tile's width and height for its content and importance. Width can be any whole number from 1 to 12, subject to the tile's minimum size. Mixed rows such as 8-wide and 4-wide tiles can show hierarchy. A write replaces the tile's whole layout, so send a complete box, not just the value you want to change. Boxes are stored as sent and overlaps are not resolved, so plan the whole grid and send every tile you move in one request. Only set `layouts.sm`: the dashboard derives the mobile layout from the sm order and heights. Use dashboard-reorder-tiles only to repack the whole dashboard with preserved or uniform tile sizes. This tool does not change a widget tile's own settings (`config`, `name`, `description`): use dashboard-widgets-batch-update for that. To group tiles, give each tile in the group the same `group_key`. Set each group's settings in `groups`, a map from group key to settings that replaces the stored map: `title`, `collapsed` to start the group closed, and `color` for a colored dot before the heading (blue, purple, green, yellow, orange, red, or null for no dot). Viewers see each group as a band that they can open and close. Viewers who do not have bands yet, and shared dashboards, see only the group title above its tiles. Put tiles that viewers check less often in a group that starts closed. To mark a tile, set its `badge`: `winner` shows a crown, for example on the best tile in a group, and `cheeky-hog` shows a hedgehog on hover. Set `badge` or `group_key` to null to remove it. To add new widget tiles to this dashboard, use dashboard-widgets-batch-add instead. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight.",
+ "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. After you create or add insight tiles, call dashboard-get to get their tile IDs, then pass `tiles` with each tile's `id` and a `layouts` object holding x, y, w, and h per breakpoint. This works for every tile type, including insight tiles. The desktop grid (`layouts.sm`) is 12 columns wide. Set each tile's width and height for its content and importance. Width can be any whole number from 1 to 12, subject to the tile's minimum size. Mixed rows such as 8-wide and 4-wide tiles can show hierarchy. A write replaces the tile's whole layout, so send a complete box, not just the value you want to change. Boxes are stored as sent and overlaps are not resolved, so plan the whole grid and send every tile you move in one request. Only set `layouts.sm`: the dashboard derives the mobile layout from the sm order and heights. Use dashboard-reorder-tiles only to repack the whole dashboard with preserved or uniform tile sizes. This tool does not change a widget tile's own settings (`config`, `name`, `description`): use dashboard-widgets-batch-update for that. To group tiles, give each tile in the group the same `group_key`. Set each group's settings in `groups`, a map from group key to settings that replaces the stored map: `title`, `collapsed` to start the group closed, and `color` for a colored dot before the heading (blue, purple, green, yellow, orange, red, or null for no dot). Viewers see each group as a band that they can open and close. Viewers who do not have bands yet, and shared dashboards, see only the group title above its tiles. Put tiles that viewers check less often in a group that starts closed. To mark a tile, set its `badge`: `winner` shows a crown, for example on the best tile in a group, and `cheeky-hog` shows a hedgehog on hover. Set `badge` or `group_key` to null to remove it. To add new widget tiles to this dashboard, use dashboard-widgets-batch-add instead. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard",
@@ -4108,7 +4108,7 @@
}
},
"dashboard-update-text-tile": {
- "description": "Update the user-facing markdown body, agent context, layout, or color of an existing text tile on a dashboard. Pass the DashboardTile id as `tile_id` (use dashboard-get to look up tile IDs). Keep concise, human-readable copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Use data-catalog-metric-create or data-catalog-metric-update for canonical metric definitions instead of writing them in `agent_context`. Only the fields you provide are updated; omitted fields are left unchanged.",
+ "description": "Update the user-facing markdown body, agent context, layout, or color of an existing text tile on a dashboard. Pass the DashboardTile id as `tile_id` (use dashboard-get to look up tile IDs). Keep concise, human-readable copy in `body`. Put context for consistent future updates in `agent_context`, such as Data Catalog metric names, data sources, tile-specific query assumptions, caveats, or editing guidance. PostHog's Data Catalog is the semantic layer. Use data-catalog-metric-create or data-catalog-metric-update for canonical metric definitions instead of writing them in `agent_context`. Only the fields you provide are updated; omitted fields are left unchanged. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard text tile",
@@ -4138,7 +4138,7 @@
}
},
"dashboard-widgets-batch-add": {
- "description": "Add widget tiles to a dashboard atomically via POST .../widgets/batch/ (1–10 tiles). Before writing a config, call dashboard-widget-catalog-list with `widget_type` set to the types you will add, to read their config_schema. The valid widget_type values are in this tool's schema. Pass `widgets` as an array of payloads (widget_type, config, optional name, description, layouts). This schema does not list config keys: build each config from the config_schema of its widget_type in the catalog. widgetFilters, when supported, is a map of filter id to property filter entries. An invalid config returns a 400 that names each invalid field. For a single tile, pass a one-element `widgets` array. Tiles stack at the bottom when layouts are omitted. Returns all created tiles; use dashboard-widgets-run to fetch live data. This only adds new tiles — to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed).",
+ "description": "Add widget tiles to a dashboard atomically via POST .../widgets/batch/ (1–10 tiles). Before writing a config, call dashboard-widget-catalog-list with `widget_type` set to the types you will add, to read their config_schema. The valid widget_type values are in this tool's schema. Pass `widgets` as an array of payloads (widget_type, config, optional name, description, layouts). This schema does not list config keys: build each config from the config_schema of its widget_type in the catalog. widgetFilters, when supported, is a map of filter id to property filter entries. An invalid config returns a 400 that names each invalid field. For a single tile, pass a one-element `widgets` array. Tiles stack at the bottom when layouts are omitted. Returns all created tiles; use dashboard-widgets-run to fetch live data. This only adds new tiles — to edit existing widget tiles, use dashboard-widgets-batch-update (no delete-and-re-add needed). After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Add dashboard widgets",
@@ -4153,7 +4153,7 @@
}
},
"dashboard-widgets-batch-update": {
- "description": "Update the settings of existing widgets in place atomically (1–10), without delete-and-re-add. Edits widget settings only — `config`, `name`, and `description`. Pass `widgets` as an array of payloads, each identified by its DashboardTile `tile_id` (use dashboard-get to look up widget tile IDs) plus the settings to change. Only the fields you provide per widget are updated; omitted fields are left unchanged. A config update replaces only the top-level keys you send. This schema does not list config keys: read the config_schema of the tile's widget_type from dashboard-widget-catalog-list, passing `widget_type` to fetch only that type. All updates succeed or fail together. Tile placement (layout, show_description) is not changed here — use dashboard-update or dashboard-reorder-tiles for that. To add new widgets, use dashboard-widgets-batch-add; to remove one, use dashboard-delete-tile.",
+ "description": "Update the settings of existing widgets in place atomically (1–10), without delete-and-re-add. Edits widget settings only — `config`, `name`, and `description`. Pass `widgets` as an array of payloads, each identified by its DashboardTile `tile_id` (use dashboard-get to look up widget tile IDs) plus the settings to change. Only the fields you provide per widget are updated; omitted fields are left unchanged. A config update replaces only the top-level keys you send. This schema does not list config keys: read the config_schema of the tile's widget_type from dashboard-widget-catalog-list, passing `widget_type` to fetch only that type. All updates succeed or fail together. Tile placement (layout, show_description) is not changed here — use dashboard-update or dashboard-reorder-tiles for that. To add new widgets, use dashboard-widgets-batch-add; to remove one, use dashboard-delete-tile. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",
"category": "Dashboards",
"feature": "dashboards",
"summary": "Update dashboard widget settings",
@@ -8364,7 +8364,7 @@
"feature_flag": "insight-data-checks"
},
"insight-update": {
- "description": "Update a saved insight by numeric `id` or `short_id`. Can update name, description, query, tags, favorited status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query tool with the same identifier if you want to see the recomputed results. Query uses the same format as insight-create. Replacing query replaces the entire definition; include all filters and visualization settings you want to retain.",
+ "description": "Update a saved insight by numeric `id` or `short_id`. Can update name, description, query, tags, favorited status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query tool with the same identifier if you want to see the recomputed results. Query uses the same format as insight-create. Replacing query replaces the entire definition; include all filters and visualization settings you want to retain. After substantial visual changes, check the final saved insight once if browser access is already available. Skip browser checks for small edits.",
"category": "Product analytics",
"feature": "product_analytics",
"summary": "Update insight",
@@ -11156,7 +11156,7 @@
"feature_flag": "metrics-dashboard-import"
},
"notebook-edit": {
- "description": "Edit part of a notebook's content by short_id.\n\nFor markdown notebooks, use `execute-sql` to read the current markdown from `system.notebooks.markdown`, then edit with `old_markdown` / `new_markdown`. These are plain markdown strings; do not copy or construct the nested `ph-markdown-notebook` JSON wrapper.\n\nFor legacy rich-text notebooks, inspect the JSON content from `system.notebooks.content`, then edit with `old_value` / `new_value` JSON subtree replacement. Matching is by content: the tool finds `old_value` anywhere in the notebook and swaps it for `new_value` in place.\n\nOn success, returns the updated notebook with the new content and bumped version. On a 409 or 410 error, the notebook has changed since you loaded it; reload the latest markdown or JSON content and re-apply your edit.",
+ "description": "Edit part of a notebook's content by short_id.\n\nFor markdown notebooks, use `execute-sql` to read the current markdown from `system.notebooks.markdown`, then edit with `old_markdown` / `new_markdown`. These are plain markdown strings; do not copy or construct the nested `ph-markdown-notebook` JSON wrapper.\n\nFor legacy rich-text notebooks, inspect the JSON content from `system.notebooks.content`, then edit with `old_value` / `new_value` JSON subtree replacement. Matching is by content: the tool finds `old_value` anywhere in the notebook and swaps it for `new_value` in place.\n\nOn success, returns the updated notebook with the new content and bumped version. On a 409 or 410 error, the notebook has changed since you loaded it; reload the latest markdown or JSON content and re-apply your edit.\nIf you have browser access, check how the edited notebook renders.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Edit part of a notebook's content.",
@@ -11178,7 +11178,7 @@
}
},
"notebooks-add-cell": {
- "description": "Add a cell to a markdown notebook. SQL and Python cells run as soon as they are added: the call waits up to ~45s and returns the result — columns, a capped row preview, stdout/stderr (a Python cell's logs and tracebacks), and error — so you can look at the output and decide the next step (fix, or proceed). If the status comes back 'running', poll notebooks-run-cell-result with the run_id. A cell that reads other cells' dataframes references them by dataframe_name; those cells must have completed a run first, so add cells in dependency order. Pass run: false to add a cell without running it, for example to lay out dependent cells first. Run it later with notebooks-run-cell, or run the whole notebook with notebooks-run. SQL cells are always HogQL: queries against PostHog or data warehouse tables run on ClickHouse, and a SQL cell that references a Python-created dataframe runs on the notebook's local engine automatically — any local dataframe is queryable by name, same syntax. To chart a SQL cell, set visualization: a display type plus optional chartSettings axes. The cell then opens on the chart instead of the table. Inside a notebook, chart a SQL result this way instead of saving a separate SQL insight. The response lists visualization_warnings when an axis names a column the query does not return, when a Y column is not numeric, or when the chart cannot plot every row. The first Python cell can take longer while the notebook's sandbox kernel starts. Run analysis Python here rather than in a runtime the user can't see — dataframe work, statistics, clustering, forecasting, plotting — so the code and its output stay visible and re-runnable beside the result; the sandbox has pandas, numpy, scipy, scikit-learn, and matplotlib. component cells add other node types: Query, Image, Embed, Latex, FeatureFlag, Survey, Experiment, Person, Cohort, Recording, RecordingPlaylist. Pass a short title on every cell you add, describing what that cell shows — it renders in the cell header and is what a reader skims instead of the code. Cells can read the notebook's variables (see notebooks-get, set with notebooks-set-variables): a SQL cell as a bare `{name}` placeholder, a Python cell as a plain global. A SQL cell reading an undeclared `{name}` fails to run, so declare the variable first. A notebook holds at most 50 cells; past that the call fails, so start a new notebook rather than retrying. A Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one. notebooks-list-frames reports that rate, and notebooks-compute-options lists the presets.",
+ "description": "Add a cell to a markdown notebook. SQL and Python cells run as soon as they are added: the call waits up to ~45s and returns the result — columns, a capped row preview, stdout/stderr (a Python cell's logs and tracebacks), and error — so you can look at the output and decide the next step (fix, or proceed). If the status comes back 'running', poll notebooks-run-cell-result with the run_id. A cell that reads other cells' dataframes references them by dataframe_name; those cells must have completed a run first, so add cells in dependency order. Pass run: false to add a cell without running it, for example to lay out dependent cells first. Run it later with notebooks-run-cell, or run the whole notebook with notebooks-run. SQL cells are always HogQL: queries against PostHog or data warehouse tables run on ClickHouse, and a SQL cell that references a Python-created dataframe runs on the notebook's local engine automatically — any local dataframe is queryable by name, same syntax. To chart a SQL cell, set visualization: a display type plus optional chartSettings axes. The cell then opens on the chart instead of the table. Inside a notebook, chart a SQL result this way instead of saving a separate SQL insight. The response lists visualization_warnings when an axis names a column the query does not return, when a Y column is not numeric, or when the chart cannot plot every row. The first Python cell can take longer while the notebook's sandbox kernel starts. Run analysis Python here rather than in a runtime the user can't see — dataframe work, statistics, clustering, forecasting, plotting — so the code and its output stay visible and re-runnable beside the result; the sandbox has pandas, numpy, scipy, scikit-learn, and matplotlib. component cells add other node types: Query, Image, Embed, Latex, FeatureFlag, Survey, Experiment, Person, Cohort, Recording, RecordingPlaylist. Pass a short title on every cell you add, describing what that cell shows — it renders in the cell header and is what a reader skims instead of the code. Cells can read the notebook's variables (see notebooks-get, set with notebooks-set-variables): a SQL cell as a bare `{name}` placeholder, a Python cell as a plain global. A SQL cell reading an undeclared `{name}` fails to run, so declare the variable first. A notebook holds at most 50 cells; past that the call fails, so start a new notebook rather than retrying. A Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one. notebooks-list-frames reports that rate, and notebooks-compute-options lists the presets.\nIf you have browser access, check how the cell renders in the notebook.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Add a cell to a notebook; SQL/Python cells run immediately.",
@@ -11230,7 +11230,7 @@
"feature_flag": "revamped-py-notebooks"
},
"notebooks-create": {
- "description": "Create a new notebook. Provide a title and content. Content is a JSON object representing the notebook's rich text document structure (ProseMirror-based). Returns the created notebook with its short_id. Embedded charts use `{type: \"ph-query\", attrs: {nodeId, query}}` nodes. The `query` object must be one of: (a) `{kind: \"DataVisualizationNode\", source: {kind: \"HogQLQuery\", query: \"SELECT ...\"}, display: \"ActionsBar\", chartSettings: {...}}` for SQL charts — do NOT wrap this in an InsightVizNode; (b) `{kind: \"InsightVizNode\", source: <TrendsQuery | FunnelsQuery | RetentionQuery | PathsQuery | StickinessQuery | LifecycleQuery>}` for product-analytics insights; or (c) `{kind: \"SavedInsightNode\", shortId: \"...\"}` to embed a saved insight. The server rejects other shapes and auto-corrects the common `InsightVizNode` wrapping a SQL chart. Give every embedded node a short `attrs.title` saying what it shows — it renders in the node's header and is what a reader skims instead of the query.\nThe server stores the notebook as a markdown notebook: it converts this document, embedded charts included, into markdown with component tags. When you update the notebook later, notebooks-retrieve shows its content as one ph-markdown-notebook node, so keep that structure and edit attrs.markdown. For step-by-step data analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead.",
+ "description": "Create a new notebook. Provide a title and content. Content is a JSON object representing the notebook's rich text document structure (ProseMirror-based). Returns the created notebook with its short_id. Embedded charts use `{type: \"ph-query\", attrs: {nodeId, query}}` nodes. The `query` object must be one of: (a) `{kind: \"DataVisualizationNode\", source: {kind: \"HogQLQuery\", query: \"SELECT ...\"}, display: \"ActionsBar\", chartSettings: {...}}` for SQL charts — do NOT wrap this in an InsightVizNode; (b) `{kind: \"InsightVizNode\", source: <TrendsQuery | FunnelsQuery | RetentionQuery | PathsQuery | StickinessQuery | LifecycleQuery>}` for product-analytics insights; or (c) `{kind: \"SavedInsightNode\", shortId: \"...\"}` to embed a saved insight. The server rejects other shapes and auto-corrects the common `InsightVizNode` wrapping a SQL chart. Give every embedded node a short `attrs.title` saying what it shows — it renders in the node's header and is what a reader skims instead of the query.\nThe server stores the notebook as a markdown notebook: it converts this document, embedded charts included, into markdown with component tags. When you update the notebook later, notebooks-retrieve shows its content as one ph-markdown-notebook node, so keep that structure and edit attrs.markdown. For step-by-step data analysis with executable SQL/Python cells, use `notebooks-create-markdown` instead. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Create notebook",
@@ -11248,7 +11248,7 @@
"superseded_by": ["notebooks-create-markdown"]
},
"notebooks-create-markdown": {
- "description": "Create a notebook for deep, step-by-step data analysis: query PostHog and connected data warehouse data with SQL (HogQL), or analyze with Python code. SQL and Python cells can also read and query dataframes fetched or created by upstream cells in the notebook. Run a cell, read its result, decide the next step; add markdown cells to explain and summarize findings, and embed saved insights. Give it a title and optionally an initial markdown body that states the question and the plan, not results computed elsewhere. Returns the notebook_id to use with notebooks-add-cell. This is the default artifact for an analysis with a narrative — a deep dive, a one-off investigation, a 'why did X change' — where the reader needs the reasoning and caveats, not just a number; a dashboard is for metrics tracked repeatedly over time. Reach for a notebook without being asked whenever the work needs Python, so the code, its output, and its errors are visible to the user next to the result instead of running where they can't see them.",
+ "description": "Create a notebook for deep, step-by-step data analysis: query PostHog and connected data warehouse data with SQL (HogQL), or analyze with Python code. SQL and Python cells can also read and query dataframes fetched or created by upstream cells in the notebook. Run a cell, read its result, decide the next step; add markdown cells to explain and summarize findings, and embed saved insights. Give it a title and optionally an initial markdown body that states the question and the plan, not results computed elsewhere. Returns the notebook_id to use with notebooks-add-cell. This is the default artifact for an analysis with a narrative — a deep dive, a one-off investigation, a 'why did X change' — where the reader needs the reasoning and caveats, not just a number; a dashboard is for metrics tracked repeatedly over time. Reach for a notebook without being asked whenever the work needs Python, so the code, its output, and its errors are visible to the user next to the result instead of running where they can't see them.\nWhen the notebook is ready, use a browser if available to check how it renders.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Create a markdown notebook for deep-dive analysis with SQL and Python cells.",
@@ -11264,7 +11264,7 @@
}
},
"notebooks-delete-cell": {
- "description": "Delete a cell from a markdown notebook by node_id. Nothing downstream is touched: the response lists orphaned_dependents — cells that referenced the deleted cell's dataframe and now need rewriting or deleting. The kernel keeps any already-materialized dataframe until it restarts, so a dependent may still run against the deleted cell's last result; rewrite dependents promptly.",
+ "description": "Delete a cell from a markdown notebook by node_id. Nothing downstream is touched: the response lists orphaned_dependents — cells that referenced the deleted cell's dataframe and now need rewriting or deleting. The kernel keeps any already-materialized dataframe until it restarts, so a dependent may still run against the deleted cell's last result; rewrite dependents promptly.\nIf you have browser access, check the notebook layout after deleting the cell.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Delete a notebook cell.",
@@ -11342,7 +11342,7 @@
"feature_flag": "revamped-py-notebooks"
},
"notebooks-partial-update": {
- "description": "Update an existing notebook by short_id. Can update title, content, and deleted status. IMPORTANT: when updating the content field, you must provide the current version number for optimistic concurrency control. Retrieve the notebook first to get the latest version. If the notebook content is a single ph-markdown-notebook node, preserve that structure and update attrs.markdown with valid markdown instead of replacing it with legacy rich-text blocks.",
+ "description": "Update an existing notebook by short_id. Can update title, content, and deleted status. IMPORTANT: when updating the content field, you must provide the current version number for optimistic concurrency control. Retrieve the notebook first to get the latest version. If the notebook content is a single ph-markdown-notebook node, preserve that structure and update attrs.markdown with valid markdown instead of replacing it with legacy rich-text blocks. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Update notebook",
@@ -11487,7 +11487,7 @@
}
},
"notebooks-update-cell": {
- "description": "Update a cell by node_id. For a SQL or Python cell pass `code` to replace its source and re-run it. To run a cell unchanged, for example a stale cell, use notebooks-run-cell. For a SQL cell, pass `visualization` to change its chart. With `visualization` and no `code`, only the chart changes and the cell does not re-run. Pass null to show the results table again. For a markdown cell (cell_type 'markdown' in notebooks-get: prose, a heading, a table, a fenced block) pass `markdown` instead: it replaces that block only, runs nothing, and leaves every other cell untouched. That is how you fix wording in a notebook you already shared, instead of appending a correction or recreating it under a new URL. Read the ids with notebooks-get and edit against that same read, because a markdown cell's id is derived from its text and changes once the text changes. Waits up to ~45s and returns the result like notebooks-add-cell, plus stale_dependents: the downstream cells whose inputs this run invalidated. Nothing re-runs automatically — inspect each dependent and run it with notebooks-run-cell or fix it first, walking the graph one hop at a time. To refresh the whole notebook in one call instead, use notebooks-run. The run binds the notebook's current variables, so running a cell is also how it picks up a changed variable value. Re-running a Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one.",
+ "description": "Update a cell by node_id. For a SQL or Python cell pass `code` to replace its source and re-run it. To run a cell unchanged, for example a stale cell, use notebooks-run-cell. For a SQL cell, pass `visualization` to change its chart. With `visualization` and no `code`, only the chart changes and the cell does not re-run. Pass null to show the results table again. For a markdown cell (cell_type 'markdown' in notebooks-get: prose, a heading, a table, a fenced block) pass `markdown` instead: it replaces that block only, runs nothing, and leaves every other cell untouched. That is how you fix wording in a notebook you already shared, instead of appending a correction or recreating it under a new URL. Read the ids with notebooks-get and edit against that same read, because a markdown cell's id is derived from its text and changes once the text changes. Waits up to ~45s and returns the result like notebooks-add-cell, plus stale_dependents: the downstream cells whose inputs this run invalidated. Nothing re-runs automatically — inspect each dependent and run it with notebooks-run-cell or fix it first, walking the graph one hop at a time. To refresh the whole notebook in one call instead, use notebooks-run. The run binds the notebook's current variables, so running a cell is also how it picks up a changed variable value. Re-running a Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one.\nIf you have browser access, check how the updated cell renders in the notebook.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Update a cell's code and re-run it.",
@@ -11507,7 +11507,7 @@
}
},
"notebooks-widget-attach": {
- "description": "Attach a reusable widget to an existing Widget node in a notebook. First save a `<Widget nodeId=\"...\" />` element in the notebook markdown, then pass that node_id here. Map every logical input slot from the widget contract to a dataframe in this notebook with `{source: \"dataframe_name\"}`. When source columns do not match the contract, add a pure Hog expression in `hog` that receives `rows`, `columns`, and `frame` and returns a list of objects with the contract's columns. Omit version_id or pass null to follow the latest shared version; pass a version UUID to pin this placement.",
+ "description": "Attach a reusable widget to an existing Widget node in a notebook. First save a `<Widget nodeId=\"...\" />` element in the notebook markdown, then pass that node_id here. Map every logical input slot from the widget contract to a dataframe in this notebook with `{source: \"dataframe_name\"}`. When source columns do not match the contract, add a pure Hog expression in `hog` that receives `rows`, `columns`, and `frame` and returns a list of objects with the contract's columns. Omit version_id or pass null to follow the latest shared version; pass a version UUID to pin this placement. After substantial visual changes, check the final saved notebook once if browser access is already available. Skip browser checks for small edits.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Add reusable widget to notebook",
@@ -14740,7 +14740,7 @@
}
},
"survey-create": {
- "description": "Creates a new survey in the project. For the draft, targeting, preview, and launch workflow, load the creating-surveys skill when available. Use this for both in-app surveys and hosted forms. Prefer draft creation by default and do not set start_date unless the user explicitly asks to launch immediately. For in-app surveys, popover is the default unless the user asks for widget or api. For hosted forms, use external_survey. Keep surveys short unless the user asks for a longer flow. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey.",
+ "description": "Creates a new survey in the project. For the draft, targeting, preview, and launch workflow, load the creating-surveys skill when available. Use this for both in-app surveys and hosted forms. Prefer draft creation by default and do not set start_date unless the user explicitly asks to launch immediately. For in-app surveys, popover is the default unless the user asks for widget or api. For hosted forms, use external_survey. Keep surveys short unless the user asks for a longer flow. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey. For substantial visual changes, preview the final draft once before launch if browser access is already available. Skip browser checks for small edits.",
"category": "Surveys",
"feature": "surveys",
"summary": "Creates a new survey in the project.",
@@ -14830,7 +14830,7 @@
}
},
"survey-update": {
- "description": "Update an existing survey by ID. Omitted top-level fields are preserved, but nested objects and arrays you provide may replace existing values. Before changing questions, conditions, appearance, targeting, translations, or hosted-form content, retrieve the survey first and preserve fields that should remain. Do not send null to clear a field unless the user explicitly asked to remove it. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey.",
+ "description": "Update an existing survey by ID. Omitted top-level fields are preserved, but nested objects and arrays you provide may replace existing values. Before changing questions, conditions, appearance, targeting, translations, or hosted-form content, retrieve the survey first and preserve fields that should remain. Do not send null to clear a field unless the user explicitly asked to remove it. Survey content is public: anyone can read the name, questions, and appearance text. In-app surveys send them to every visitor's browser, and a hosted survey shows them on its public page. Tell the user before putting a customer name or other private detail in a survey. For substantial visual changes, preview the final survey once if browser access is already available. Skip browser checks for small edits.",
"category": "Surveys",
"feature": "surveys",
"summary": "Update an existing survey by ID.",
diff --git a/services/mcp/schema/tool-definitions.json b/services/mcp/schema/tool-definitions.json
index 192b2bb33af3..88fad536291e 100644
--- a/services/mcp/schema/tool-definitions.json
+++ b/services/mcp/schema/tool-definitions.json
@@ -303,7 +303,7 @@
"feature_flag": "insight-data-checks"
},
"notebook-edit": {
- "description": "Edit part of a notebook's content by short_id.\n\nFor markdown notebooks, use `execute-sql` to read the current markdown from `system.notebooks.markdown`, then edit with `old_markdown` / `new_markdown`. These are plain markdown strings; do not copy or construct the nested `ph-markdown-notebook` JSON wrapper.\n\nFor legacy rich-text notebooks, inspect the JSON content from `system.notebooks.content`, then edit with `old_value` / `new_value` JSON subtree replacement. Matching is by content: the tool finds `old_value` anywhere in the notebook and swaps it for `new_value` in place.\n\nOn success, returns the updated notebook with the new content and bumped version. On a 409 or 410 error, the notebook has changed since you loaded it; reload the latest markdown or JSON content and re-apply your edit.",
+ "description": "Edit part of a notebook's content by short_id.\n\nFor markdown notebooks, use `execute-sql` to read the current markdown from `system.notebooks.markdown`, then edit with `old_markdown` / `new_markdown`. These are plain markdown strings; do not copy or construct the nested `ph-markdown-notebook` JSON wrapper.\n\nFor legacy rich-text notebooks, inspect the JSON content from `system.notebooks.content`, then edit with `old_value` / `new_value` JSON subtree replacement. Matching is by content: the tool finds `old_value` anywhere in the notebook and swaps it for `new_value` in place.\n\nOn success, returns the updated notebook with the new content and bumped version. On a 409 or 410 error, the notebook has changed since you loaded it; reload the latest markdown or JSON content and re-apply your edit.\nIf you have browser access, check how the edited notebook renders.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Edit part of a notebook's content.",
@@ -325,7 +325,7 @@
}
},
"notebooks-create-markdown": {
- "description": "Create a notebook for deep, step-by-step data analysis: query PostHog and connected data warehouse data with SQL (HogQL), or analyze with Python code. SQL and Python cells can also read and query dataframes fetched or created by upstream cells in the notebook. Run a cell, read its result, decide the next step; add markdown cells to explain and summarize findings, and embed saved insights. Give it a title and optionally an initial markdown body that states the question and the plan, not results computed elsewhere. Returns the notebook_id to use with notebooks-add-cell. This is the default artifact for an analysis with a narrative — a deep dive, a one-off investigation, a 'why did X change' — where the reader needs the reasoning and caveats, not just a number; a dashboard is for metrics tracked repeatedly over time. Reach for a notebook without being asked whenever the work needs Python, so the code, its output, and its errors are visible to the user next to the result instead of running where they can't see them.",
+ "description": "Create a notebook for deep, step-by-step data analysis: query PostHog and connected data warehouse data with SQL (HogQL), or analyze with Python code. SQL and Python cells can also read and query dataframes fetched or created by upstream cells in the notebook. Run a cell, read its result, decide the next step; add markdown cells to explain and summarize findings, and embed saved insights. Give it a title and optionally an initial markdown body that states the question and the plan, not results computed elsewhere. Returns the notebook_id to use with notebooks-add-cell. This is the default artifact for an analysis with a narrative — a deep dive, a one-off investigation, a 'why did X change' — where the reader needs the reasoning and caveats, not just a number; a dashboard is for metrics tracked repeatedly over time. Reach for a notebook without being asked whenever the work needs Python, so the code, its output, and its errors are visible to the user next to the result instead of running where they can't see them.\nWhen the notebook is ready, use a browser if available to check how it renders.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Create a markdown notebook for deep-dive analysis with SQL and Python cells.",
@@ -341,7 +341,7 @@
}
},
"notebooks-add-cell": {
- "description": "Add a cell to a markdown notebook. SQL and Python cells run as soon as they are added: the call waits up to ~45s and returns the result — columns, a capped row preview, stdout/stderr (a Python cell's logs and tracebacks), and error — so you can look at the output and decide the next step (fix, or proceed). If the status comes back 'running', poll notebooks-run-cell-result with the run_id. A cell that reads other cells' dataframes references them by dataframe_name; those cells must have completed a run first, so add cells in dependency order. Pass run: false to add a cell without running it, for example to lay out dependent cells first. Run it later with notebooks-run-cell, or run the whole notebook with notebooks-run. SQL cells are always HogQL: queries against PostHog or data warehouse tables run on ClickHouse, and a SQL cell that references a Python-created dataframe runs on the notebook's local engine automatically — any local dataframe is queryable by name, same syntax. To chart a SQL cell, set visualization: a display type plus optional chartSettings axes. The cell then opens on the chart instead of the table. Inside a notebook, chart a SQL result this way instead of saving a separate SQL insight. The response lists visualization_warnings when an axis names a column the query does not return, when a Y column is not numeric, or when the chart cannot plot every row. The first Python cell can take longer while the notebook's sandbox kernel starts. Run analysis Python here rather than in a runtime the user can't see — dataframe work, statistics, clustering, forecasting, plotting — so the code and its output stay visible and re-runnable beside the result; the sandbox has pandas, numpy, scipy, scikit-learn, and matplotlib. component cells add other node types: Query, Image, Embed, Latex, FeatureFlag, Survey, Experiment, Person, Cohort, Recording, RecordingPlaylist. Pass a short title on every cell you add, describing what that cell shows — it renders in the cell header and is what a reader skims instead of the code. Cells can read the notebook's variables (see notebooks-get, set with notebooks-set-variables): a SQL cell as a bare `{name}` placeholder, a Python cell as a plain global. A SQL cell reading an undeclared `{name}` fails to run, so declare the variable first. A notebook holds at most 50 cells; past that the call fails, so start a new notebook rather than retrying. A Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one. notebooks-list-frames reports that rate, and notebooks-compute-options lists the presets.",
+ "description": "Add a cell to a markdown notebook. SQL and Python cells run as soon as they are added: the call waits up to ~45s and returns the result — columns, a capped row preview, stdout/stderr (a Python cell's logs and tracebacks), and error — so you can look at the output and decide the next step (fix, or proceed). If the status comes back 'running', poll notebooks-run-cell-result with the run_id. A cell that reads other cells' dataframes references them by dataframe_name; those cells must have completed a run first, so add cells in dependency order. Pass run: false to add a cell without running it, for example to lay out dependent cells first. Run it later with notebooks-run-cell, or run the whole notebook with notebooks-run. SQL cells are always HogQL: queries against PostHog or data warehouse tables run on ClickHouse, and a SQL cell that references a Python-created dataframe runs on the notebook's local engine automatically — any local dataframe is queryable by name, same syntax. To chart a SQL cell, set visualization: a display type plus optional chartSettings axes. The cell then opens on the chart instead of the table. Inside a notebook, chart a SQL result this way instead of saving a separate SQL insight. The response lists visualization_warnings when an axis names a column the query does not return, when a Y column is not numeric, or when the chart cannot plot every row. The first Python cell can take longer while the notebook's sandbox kernel starts. Run analysis Python here rather than in a runtime the user can't see — dataframe work, statistics, clustering, forecasting, plotting — so the code and its output stay visible and re-runnable beside the result; the sandbox has pandas, numpy, scipy, scikit-learn, and matplotlib. component cells add other node types: Query, Image, Embed, Latex, FeatureFlag, Survey, Experiment, Person, Cohort, Recording, RecordingPlaylist. Pass a short title on every cell you add, describing what that cell shows — it renders in the cell header and is what a reader skims instead of the code. Cells can read the notebook's variables (see notebooks-get, set with notebooks-set-variables): a SQL cell as a bare `{name}` placeholder, a Python cell as a plain global. A SQL cell reading an undeclared `{name}` fails to run, so declare the variable first. A notebook holds at most 50 cells; past that the call fails, so start a new notebook rather than retrying. A Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one. notebooks-list-frames reports that rate, and notebooks-compute-options lists the presets.\nIf you have browser access, check how the cell renders in the notebook.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Add a cell to a notebook; SQL/Python cells run immediately.",
@@ -361,7 +361,7 @@
}
},
"notebooks-update-cell": {
- "description": "Update a cell by node_id. For a SQL or Python cell pass `code` to replace its source and re-run it. To run a cell unchanged, for example a stale cell, use notebooks-run-cell. For a SQL cell, pass `visualization` to change its chart. With `visualization` and no `code`, only the chart changes and the cell does not re-run. Pass null to show the results table again. For a markdown cell (cell_type 'markdown' in notebooks-get: prose, a heading, a table, a fenced block) pass `markdown` instead: it replaces that block only, runs nothing, and leaves every other cell untouched. That is how you fix wording in a notebook you already shared, instead of appending a correction or recreating it under a new URL. Read the ids with notebooks-get and edit against that same read, because a markdown cell's id is derived from its text and changes once the text changes. Waits up to ~45s and returns the result like notebooks-add-cell, plus stale_dependents: the downstream cells whose inputs this run invalidated. Nothing re-runs automatically — inspect each dependent and run it with notebooks-run-cell or fix it first, walking the graph one hop at a time. To refresh the whole notebook in one call instead, use notebooks-run. The run binds the notebook's current variables, so running a cell is also how it picks up a changed variable value. Re-running a Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one.",
+ "description": "Update a cell by node_id. For a SQL or Python cell pass `code` to replace its source and re-run it. To run a cell unchanged, for example a stale cell, use notebooks-run-cell. For a SQL cell, pass `visualization` to change its chart. With `visualization` and no `code`, only the chart changes and the cell does not re-run. Pass null to show the results table again. For a markdown cell (cell_type 'markdown' in notebooks-get: prose, a heading, a table, a fenced block) pass `markdown` instead: it replaces that block only, runs nothing, and leaves every other cell untouched. That is how you fix wording in a notebook you already shared, instead of appending a correction or recreating it under a new URL. Read the ids with notebooks-get and edit against that same read, because a markdown cell's id is derived from its text and changes once the text changes. Waits up to ~45s and returns the result like notebooks-add-cell, plus stale_dependents: the downstream cells whose inputs this run invalidated. Nothing re-runs automatically — inspect each dependent and run it with notebooks-run-cell or fix it first, walking the graph one hop at a time. To refresh the whole notebook in one call instead, use notebooks-run. The run binds the notebook's current variables, so running a cell is also how it picks up a changed variable value. Re-running a Python cell provisions the notebook's sandbox when none is running, and the user pays for it while it runs, so tell them its hourly_price the first time a run starts one.\nIf you have browser access, check how the updated cell renders in the notebook.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Update a cell's code and re-run it.",
@@ -381,7 +381,7 @@
}
},
"notebooks-delete-cell": {
- "description": "Delete a cell from a markdown notebook by node_id. Nothing downstream is touched: the response lists orphaned_dependents — cells that referenced the deleted cell's dataframe and now need rewriting or deleting. The kernel keeps any already-materialized dataframe until it restarts, so a dependent may still run against the deleted cell's last result; rewrite dependents promptly.",
+ "description": "Delete a cell from a markdown notebook by node_id. Nothing downstream is touched: the response lists orphaned_dependents — cells that referenced the deleted cell's dataframe and now need rewriting or deleting. The kernel keeps any already-materialized dataframe until it restarts, so a dependent may still run against the deleted cell's last result; rewrite dependents promptly.\nIf you have browser access, check the notebook layout after deleting the cell.",
"category": "Notebooks",
"feature": "notebooks",
"summary": "Delete a notebook cell.",
diff --git a/services/mcp/src/tools/generated/product_analytics.ts b/services/mcp/src/tools/generated/product_analytics.ts
index 72d41deaa21e..d0606fbc731d 100644
--- a/services/mcp/src/tools/generated/product_analytics.ts
+++ b/services/mcp/src/tools/generated/product_analytics.ts
@@ -376,7 +376,7 @@ const insightCreate = (): ToolBase<
]) as typeof result
return withAgentNote(
await withPostHogUrl(context, filtered, `/insights/${filtered.short_id}`),
- 'When you tell the user about this insight, name the display you chose and one or two other displays that also fit this query, in one short sentence, and offer to change it. If the user agrees, change it with insight-update. Suggest only displays that the insight kind supports and that fit the question:\n\n- Trends (`trendsFilter.display`): for change over time `ActionsLineGraph`, `ActionsAreaGraph`, `ActionsBar` or `ActionsUnstackedBar`; for totals per breakdown value or series `ActionsBarValue`, `ActionsPie` or `ActionsTable`; for one number `Metric` or `BoldNumber`, never with a breakdown or more than one series; `WorldMap` only for a `$geoip_country_code` breakdown.\n- Funnels (`funnelsFilter.funnelVizType`): `steps` for drop-off per step, `trends` for conversion over time, or `time_to_convert` for how long users take.\n- Retention (`retentionFilter.display`): `ActionsLineGraph` or `ActionsBar`.\n- Stickiness (`stickinessFilter.display`): `ActionsLineGraph`, `ActionsBar` or `ActionsAreaGraph`.\n- Lifecycle: stacked or side-by-side bars (`lifecycleFilter.stacked`).\n- SQL (`DataVisualizationNode` `display`): only displays that fit the columns the query returns.\n- Paths: suggest nothing.\n\nUse the chart names a person sees, such as "bar chart per category" or "line chart", not enum values or tool names. If the user named the chart they want, do not suggest others. If you create several insights in this task, give one short list of alternatives at the end, not one per insight.\n\nAfter creating a Trends, SQL (HogQL), Funnels or Metrics insight, call insight-query with the returned short_id, read the current value, and offer an alert when the metric is one someone would act on if it moved sharply (signups, active users, revenue, conversion rate, error or failure counts, latency). Name an actual number, never a placeholder such as X, for example "want me to alert you when daily signups drop below 400?". A count sitting at zero, such as errors or failures, is a strong case, so offer an upper bound of 1. Offer nothing when the insight returned no rows. When no absolute number fits and the insight supports it, offer a relative-change alert on a sudden increase or decrease. Skip metrics nobody acts on, such as raw pageview or event-volume counts, and skip high-cardinality breakdowns. Judge the metric, not the request. A newly created insight, or one the user just asked to see, is not throwaway for that reason. If the user already declined an alert in this conversation, do not offer again. If alert-create is unavailable, say nothing about alerts. Wait for the user to accept before creating an alert.\n'
+ 'When you tell the user about this insight, name the display you chose and one or two other displays that also fit this query, in one short sentence, and offer to change it. If the user agrees, change it with insight-update. Suggest only displays that the insight kind supports and that fit the question:\n\n- Trends (`trendsFilter.display`): for change over time `ActionsLineGraph`, `ActionsAreaGraph`, `ActionsBar` or `ActionsUnstackedBar`; for totals per breakdown value or series `ActionsBarValue`, `ActionsPie` or `ActionsTable`; for one number `Metric` or `BoldNumber`, never with a breakdown or more than one series; `WorldMap` only for a `$geoip_country_code` breakdown.\n- Funnels (`funnelsFilter.funnelVizType`): `steps` for drop-off per step, `trends` for conversion over time, or `time_to_convert` for how long users take.\n- Retention (`retentionFilter.display`): `ActionsLineGraph` or `ActionsBar`.\n- Stickiness (`stickinessFilter.display`): `ActionsLineGraph`, `ActionsBar` or `ActionsAreaGraph`.\n- Lifecycle: stacked or side-by-side bars (`lifecycleFilter.stacked`).\n- SQL (`DataVisualizationNode` `display`): only displays that fit the columns the query returns.\n- Paths: suggest nothing.\n\nUse the chart names a person sees, such as "bar chart per category" or "line chart", not enum values or tool names. If the user named the chart they want, do not suggest others. If you create several insights in this task, give one short list of alternatives at the end, not one per insight.\n\nAfter creating a Trends, SQL (HogQL), Funnels or Metrics insight, call insight-query with the returned short_id, read the current value, and offer an alert when the metric is one someone would act on if it moved sharply (signups, active users, revenue, conversion rate, error or failure counts, latency). Name an actual number, never a placeholder such as X, for example "want me to alert you when daily signups drop below 400?". A count sitting at zero, such as errors or failures, is a strong case, so offer an upper bound of 1. Offer nothing when the insight returned no rows. When no absolute number fits and the insight supports it, offer a relative-change alert on a sudden increase or decrease. Skip metrics nobody acts on, such as raw pageview or event-volume counts, and skip high-cardinality breakdowns. Judge the metric, not the request. A newly created insight, or one the user just asked to see, is not throwaway for that reason. If the user already declined an alert in this conversation, do not offer again. If alert-create is unavailable, say nothing about alerts. Wait for the user to accept before creating an alert. After substantial visual changes, check the final saved insight once if browser access is already available. Skip browser checks for small edits.\n'
)
},
})