:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(mcp): clarify dashboard and insight description visibility (#123172)
posthog[bot]0a8d99f3c5d0
diff --git a/products/dashboards/backend/api/dashboard.py b/products/dashboards/backend/api/dashboard.pyindex c5be846196b7..21128c48a868 100644--- a/products/dashboards/backend/api/dashboard.py+++ b/products/dashboards/backend/api/dashboard.py@@ -1324,7 +1324,12 @@ class DashboardBasicSerializer(read_only_fields = fieldsextra_kwargs = {"name": {"help_text": "Name of the dashboard."},- "description": {"help_text": "Description of the dashboard."},+ "description": {+ "help_text": (+ "Short note for people who open the dashboard. Say what it shows in one or two sentences, "+ "about 30 words. Leave it empty when the name already says it. Do not write how it was built or changed."+ )+ },"pinned": {"help_text": "Whether the dashboard is pinned to the top of the list."},}diff --git a/products/dashboards/frontend/generated/api.schemas.ts b/products/dashboards/frontend/generated/api.schemas.tsindex d761c64a2761..062ab3124ae3 100644--- a/products/dashboards/frontend/generated/api.schemas.ts+++ b/products/dashboards/frontend/generated/api.schemas.ts@@ -344,7 +344,7 @@ export interface DashboardBasicApi {* @nullable*/readonly name: string | null- /** Description of the dashboard. */+ /** Short note for people who open the dashboard. Say what it shows in one or two sentences, about 30 words. Leave it empty when the name already says it. Do not write how it was built or changed. */readonly description: string/** Whether the dashboard is pinned to the top of the list. */readonly pinned: booleandiff --git a/products/dashboards/mcp/tools.yaml b/products/dashboards/mcp/tools.yamlindex 45c7289b3ac7..adcf6f89d99a 100644--- a/products/dashboards/mcp/tools.yaml+++ b/products/dashboards/mcp/tools.yaml@@ -19,10 +19,12 @@ tools:enrich_url: '{id}'title: Create dashboarddescription: >- 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.+ Create a new dashboard. Provide a name and optional description, tags, and pinned status. All viewers see+ the description at the top of the dashboard. Write one or two short sentences for them, about 30 words. Skip+ it when the name already says it. Do not write agent notes. 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.Load the building-a-dashboard skill before you create or change a dashboard. It covers when to update anexisting dashboard instead, which insights to reuse, and how to lay out the tiles.@@ -443,7 +445,9 @@ tools:title: Update dashboarddescription: >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,+ status, tags, and filters. All viewers see the description at the top of the dashboard. If you change it,+ rewrite it in one or two short sentences, or clear it when the name already says it. Do not append revision+ history or agent notes. 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. Thisworks for every tile type, including insight tiles. The desktop grid (`layouts.sm`) is 12 columns wide. Seteach tile's width and height for its content and importance. Width can be any whole number from 1 to 12,diff --git a/products/dashboards/skills/building-a-dashboard/SKILL.md b/products/dashboards/skills/building-a-dashboard/SKILL.mdindex 8fbfd8f29d49..dfd624e53429 100644--- a/products/dashboards/skills/building-a-dashboard/SKILL.md+++ b/products/dashboards/skills/building-a-dashboard/SKILL.md@@ -87,6 +87,15 @@ metric as noncanonical and do not claim that `agent_context` makes it governed.- Existing dashboard: use `dashboard-update` to add insight tiles or change their layout. Tiles omitted from a PATCHremain on the dashboard. To remove a tile, find its ID with `dashboard-get`, then use `dashboard-delete-tile`.To replace an insight tile, add the new insight and delete the old tile.+- Description on create and update: it is a short note for people who open the dashboard. Say what the dashboard shows+ and who it is for, in one or two sentences (about 30 words). Shorter is better. The limit is not a target.+ - Skip the description when the name already tells a viewer what the dashboard shows. An empty description is fine.+ - Test: would a viewer who never saw this session need the sentence? If not, delete it.+ - Good: "Weekly signups and activation by plan."+ - Bad: "Tracks signups, activation, and churn across all plans. Revised 3 March to add the enterprise tile."+ - When you update it, rewrite it. Do not append.+ - Put metric definitions in the Data Catalog. Put working notes in a text tile's `agent_context`.+ - Use the same rules for insight descriptions. Write plain, short copy: see `writing-user-facing-copy`.- Layout: after you add insight tiles, call `dashboard-get` again to get their tile IDs. Use `dashboard-update` to planeach tile independently on the 12-column grid. Tile widths can be any whole number from 1 to 12, subject to eachtile's minimum size. Use wider tiles for primary charts and smaller tiles for supporting metrics. Mixed rows such asdiff --git a/products/product_analytics/mcp/tools.yaml b/products/product_analytics/mcp/tools.yamlindex 03e1e67c9e3a..ce4e69c4a0ef 100644--- a/products/product_analytics/mcp/tools.yaml+++ b/products/product_analytics/mcp/tools.yaml@@ -160,7 +160,7 @@ tools:existing dashboard IDs when adding a new one.description:description: |- Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected).+ Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.response:exclude:- result@@ -283,7 +283,7 @@ tools:existing dashboard IDs when adding a new one.description:description: |- Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected).+ Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.response:exclude:- resultdiff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 5f2a2c00d7b3..86ab436f0ca6 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -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. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",+ "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. All viewers see the description at the top of the dashboard. Write one or two short sentences for them, about 30 words. Skip it when the name already says it. Do not write agent notes. 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",@@ -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. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",+ "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. All viewers see the description at the top of the dashboard. If you change it, rewrite it in one or two short sentences, or clear it when the name already says it. Do not append revision history or agent notes. 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",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 2fe1ee0636d1..1868569e90b5 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -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. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",+ "description": "Create a new dashboard. Provide a name and optional description, tags, and pinned status. All viewers see the description at the top of the dashboard. Write one or two short sentences for them, about 30 words. Skip it when the name already says it. Do not write agent notes. 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",@@ -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. After substantial visual changes, check the final saved dashboard once if browser access is already available. Skip browser checks for small edits.",+ "description": "Resize, reposition, or update dashboard tiles. It can also update the dashboard name, description, pinned status, tags, and filters. All viewers see the description at the top of the dashboard. If you change it, rewrite it in one or two short sentences, or clear it when the name already says it. Do not append revision history or agent notes. 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",diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 5c2495ff0696..6f1e02ee62c1 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -29299,7 +29299,7 @@ export namespace Schemas {* @nullable*/readonly name: string | null;- /** Description of the dashboard. */+ /** Short note for people who open the dashboard. Say what it shows in one or two sentences, about 30 words. Leave it empty when the name already says it. Do not write how it was built or changed. */readonly description: string;/** Whether the dashboard is pinned to the top of the list. */readonly pinned: boolean;diff --git a/services/mcp/src/tools/generated/product_analytics.ts b/services/mcp/src/tools/generated/product_analytics.tsindex d0606fbc731d..2ec44c88357a 100644--- a/services/mcp/src/tools/generated/product_analytics.ts+++ b/services/mcp/src/tools/generated/product_analytics.ts@@ -328,7 +328,7 @@ const InsightCreateSchema = () => {'Dashboard IDs this insight should belong to. This is a full replacement — always include all existing dashboard IDs when adding a new one.'),description: InsightsCreateBody.shape['description'].describe(- 'Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected).'+ 'Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.'),})}@@ -474,7 +474,7 @@ const InsightUpdateSchema = () => {'Dashboard IDs this insight should belong to. This is a full replacement — always include all existing dashboard IDs when adding a new one.'),description: InsightsPartialUpdateBody.shape['description'].describe(- 'Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected).'+ 'Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.'),}))diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-create.jsonindex 16fcf5526826..fc97cbd10e0e 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-create.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-create.json@@ -18,7 +18,7 @@"type": "null"}],- "description": "Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected)."+ "description": "Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters."},"favorited": {"type": "boolean"diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-update.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-update.jsonindex b3b91c79c5ed..075afae7cbec 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-update.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/insight-update.json@@ -18,7 +18,7 @@"type": "null"}],- "description": "Human-readable summary of what the insight shows. Max 400 characters (longer values are rejected)."+ "description": "Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters."},"favorited": {"type": "boolean"