: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
// AUTO-GENERATED from products/product_analytics/mcp/tools.yaml + OpenAPI — do not edit
import { z } from 'zod'
import type { Schemas } from '@/api/generated'
import * as orvalSchemas from '@/generated/product_analytics/api'
import { castStringToInt, normalizeParamAliases } from '@/tools/cast-helpers'
import {
withPostHogUrl,
withAgentNote,
omitResponseFields,
pickResponseFields,
type WithPostHogUrl,
type WithAgentNote,
} from '@/tools/tool-utils'
import type { Context, ToolBase, ZodObjectAny } from '@/tools/types'
const HogQLExpression = z.string()
const AssistantEventsQuery = z
.object({
kind: z.literal('EventsQuery').default('EventsQuery'),
select: z.array(HogQLExpression).describe('Event columns as HogQL expressions.'),
})
.catchall(z.unknown())
const AssistantDataTableNode = z
.object({
kind: z.literal('DataTableNode').default('DataTableNode'),
source: AssistantEventsQuery,
})
.catchall(z.unknown())
const AssistantBareHogQLQuery = z
.object({
kind: z.literal('HogQLQuery').default('HogQLQuery'),
query: z.string().describe('The HogQL query to run.'),
})
.catchall(z.unknown())
const AssistantBIVisualizationNode = z
.object({
config: z
.record(z.string(), z.unknown())
.describe('Complete worksheet configuration, including shelves and filters. Validated by the insight API.'),
kind: z.literal('BIVisualizationNode').default('BIVisualizationNode'),
source: AssistantBareHogQLQuery,
})
.catchall(z.unknown())
const AssistantPieChartOptions = z.object({
hideAggregation: z.coerce.boolean().describe('Hide the total on a pie chart.').optional(),
})
const AssistantVizSpecificOptions = z.object({
ActionsPie: AssistantPieChartOptions.optional(),
})
const AssistantInsightVizNode = z.object({
kind: z.literal('InsightVizNode').default('InsightVizNode'),
source: z
.record(z.string(), z.unknown())
.describe(
'Product analtycs query objects like TrendsQuery, FunnelsQuery, RetentionQuery, PathsQuery, StickinessQuery, LifecycleQuery'
),
vizSpecificOptions: AssistantVizSpecificOptions.describe('Chart rendering options.').optional(),
})
const AssistantDataVisualizationBoxPlotSettings = z.object({
excludeOutliers: z.coerce
.boolean()
.describe('Clip whiskers to 1.5 times the interquartile range. Defaults to true.')
.optional(),
maxColumn: z.string().describe('Numeric column containing the maximum for each box.'),
meanColumn: z.string().describe('Numeric column containing the mean for each box.'),
medianColumn: z.string().describe('Numeric column containing the median for each box.'),
minColumn: z.string().describe('Numeric column containing the minimum for each box.'),
p25Column: z.string().describe('Numeric column containing the 25th percentile for each box.'),
p75Column: z.string().describe('Numeric column containing the 75th percentile for each box.'),
seriesColumn: z
.string()
.nullable()
.describe(
'Optional column that groups each X-axis value into separate colored series. Set to `null` for one series.'
)
.optional(),
xAxisColumn: z
.string()
.nullable()
.describe('X-axis category column. Set to `null` for one overall distribution or one box per series.')
.optional(),
})
const AssistantDataVisualizationGoalLine = z.object({
label: z.string().describe('Label rendered next to the goal line.'),
value: z.coerce.number().describe('Y-axis value at which the goal line is drawn.'),
})
const AssistantDataVisualizationYAxisSettings = z.object({
label: z.string().describe('Label rendered beside this Y axis.').optional(),
scale: z.enum(['linear', 'logarithmic']).describe('Scale used for this Y axis.').optional(),
showGridLines: z.coerce.boolean().describe('Show grid lines for this Y axis.').optional(),
showTicks: z.coerce.boolean().describe('Show tick labels on this Y axis.').optional(),
startAtZero: z.coerce.boolean().describe('Whether this Y axis should start at zero.').optional(),
})
const AssistantDataVisualizationMetricSettings = z.object({
showChange: z.coerce.boolean().optional(),
summary: z.enum(['total', 'average', 'latest']).optional(),
})
const PieChartSettings = z.object({
showTotal: z.coerce
.boolean()
.describe('Whether to show the aggregation total. Defaults to on only when slices show values.')
.optional(),
sliceContent: z
.enum(['labels', 'values', 'none'])
.describe('What to render on each slice. Defaults to values.')
.optional(),
valueDisplay: z
.enum(['absolute', 'percentage'])
.describe(
'Whether slice values show as absolute amounts or shares of the total. Only applies when `sliceContent` is `values`.'
)
.optional(),
})
const AssistantDataVisualizationColumnDisplaySettings = z.object({
description: z.string().describe('Table column description shown in the header tooltip.').optional(),
})
const AssistantDataVisualizationAxisFormatting = z.object({
decimalPlaces: z.coerce.number().describe('Number of decimal places to display.').optional(),
prefix: z.string().describe('Text prepended to each value (e.g. `$`).').optional(),
style: z
.enum(['none', 'number', 'short', 'percent'])
.describe(
'`none`: unformatted; `number`: thousands separators; `short`: abbreviations (1.2k, 3.4M). `percent`: multiplies by 100 and adds `%`. Pass a 0–1 ratio (`a / b`) and omit the `%` suffix to avoid doubling it.'
)
.optional(),
suffix: z.string().describe('Value suffix (e.g. ` ms`). Omit for `percent`, which adds `%`.').optional(),
})
const AssistantDataVisualizationColumnSettings = z.object({
display: AssistantDataVisualizationColumnDisplaySettings.describe('Display settings for this column.').optional(),
formatting: AssistantDataVisualizationAxisFormatting.describe(
'Number-formatting settings for the values in this column.'
).optional(),
})
const AssistantDataVisualizationColumn = z.object({
column: z.string().describe('Name of a column returned by the SQL query.'),
settings: AssistantDataVisualizationColumnSettings.describe(
'Optional display and number-formatting settings for this column.'
).optional(),
})
const AssistantDataVisualizationAxisDisplaySettings = z.object({
color: z.string().describe('Custom color for this series as a hex string (e.g. `#1d4aff`).').optional(),
displayType: z.enum(['auto', 'line', 'bar', 'area']).describe('Chart type. `auto` uses `display`.').optional(),
excludeFromTotal: z.coerce
.boolean()
.describe(
"Keep this series out of the tooltip's total row, e.g. a target line over stacked bars. A bar series still stacks, so set `displayType` to `line` for a series drawn over the stack."
)
.optional(),
label: z.string().describe('Series label in legends and tooltips; replaces the column name.').optional(),
trendLine: z.coerce
.boolean()
.describe('Draw a linear trend line for this series. Only meaningful for line, bar, and area charts.')
.optional(),
valueLabels: z
.enum(['auto', 'show', 'hide'])
.describe(
'Per-series override of chart-level `showValuesOnSeries`. `show` labels this series even when the chart setting is off, `hide` leaves it unlabeled when the setting is on, `auto` follows the chart.'
)
.optional(),
yAxisPosition: z
.enum(['left', 'right'])
.describe('Which Y axis this numeric series should use. Use `right` for a secondary Y axis.')
.optional(),
})
const AssistantDataVisualizationAxisSettings = z.object({
display: AssistantDataVisualizationAxisDisplaySettings.describe(
'Display settings for a plotted Y series.'
).optional(),
formatting: AssistantDataVisualizationAxisFormatting.describe(
'Number-formatting settings for the values on this axis or series.'
).optional(),
})
const AssistantDataVisualizationAxis = z.object({
column: z.string().describe('Name of a column returned by the SQL query to map onto this axis.'),
settings: AssistantDataVisualizationAxisSettings.describe(
'Optional series settings. Only applies to Y-axis series.'
).optional(),
})
const AssistantDataVisualizationChartSettings = z.object({
boxPlot: AssistantDataVisualizationBoxPlotSettings.describe(
'Column mappings for `BoxPlot`. The SQL must return one pre-aggregated row per X-axis and series pair.'
).optional(),
goalLines: z
.array(AssistantDataVisualizationGoalLine)
.describe('Horizontal goal lines drawn across the chart.')
.optional(),
leftYAxisSettings: AssistantDataVisualizationYAxisSettings.describe('Settings for the left Y axis.').optional(),
legendPosition: z
.enum(['top', 'bottom', 'left', 'right'])
.describe('Where the legend sits. Defaults to right for pie and donut, top for other charts.')
.optional(),
metric: AssistantDataVisualizationMetricSettings.describe(
'Settings for `Metric`. `summary` defaults to `latest`.'
).optional(),
pie: PieChartSettings.describe('Settings for `ActionsPie` and `ActionsDonut`.').optional(),
rightYAxisSettings: AssistantDataVisualizationYAxisSettings.describe(
'Settings for the right Y axis. Only applies when a Y series uses `settings.display.yAxisPosition: "right"`.'
).optional(),
seriesBreakdownColumn: z
.string()
.nullable()
.describe(
'Column that splits a single Y series into multiple colored series — e.g. breaking down a line chart by `country`. Set to `null` or omit to disable. A breakdown buckets rows by x value, so it is ignored when `display` is `ScatterPlot`.'
)
.optional(),
showAnnotations: z.coerce
.boolean()
.describe(
'Show annotations on the chart. Only applies to line, area, bar, and stacked bar charts whose X axis is a date or datetime column.'
)
.optional(),
showLegend: z.coerce.boolean().describe('Show the chart legend.').optional(),
showNullsAsZero: z.coerce.boolean().describe('Replace null aggregation results with zero.').optional(),
showTotalRow: z.coerce
.boolean()
.describe('Show a total summing all Y series. Applies to line, bar, and area charts.')
.optional(),
showValuesOnSeries: z.coerce
.boolean()
.describe("Render each data point's value as a label directly on the series.")
.optional(),
stackBars100: z.coerce
.boolean()
.describe('Stack bars to 100% of the total. Only meaningful with `ActionsStackedBar`.')
.optional(),
xAxis: AssistantDataVisualizationColumn.describe(
'Column used as the X axis. Typically a time bucket or categorical column, but `ScatterPlot` plots two measures against each other, so it needs a numeric column here too.'
).optional(),
xAxisLabel: z.string().describe('Label rendered under the X axis.').optional(),
yAxis: z
.array(AssistantDataVisualizationAxis)
.describe('One or more numeric columns plotted as Y series.')
.optional(),
})
const AssistantDataVisualizationDisplayType = z.enum([
'ActionsTable',
'BoldNumber',
'Metric',
'ActionsLineGraph',
'ActionsBar',
'ActionsBarValue',
'ActionsPie',
'ActionsDonut',
'ActionsProportionBar',
'ActionsStackedBar',
'ActionsAreaGraph',
'TwoDimensionalHeatmap',
'ScatterPlot',
'BoxPlot',
])
const AssistantDataVisualizationTableSettings = z.object({
columns: z
.array(AssistantDataVisualizationColumn)
.describe('Columns to display and their order. Omit to show every column returned by the query.')
.optional(),
pinnedColumns: z.array(z.string()).describe('Column names to pin to the left of the table.').optional(),
transpose: z.coerce.boolean().describe('Transpose rows and columns.').optional(),
})
const AssistantDataVisualizationNode = z.object({
chartSettings: AssistantDataVisualizationChartSettings.describe(
'Chart configuration. Ignored when `display` is `ActionsTable` or `BoldNumber`.'
).optional(),
display: AssistantDataVisualizationDisplayType.describe(
'Chart type (default `ActionsTable`): `BoldNumber` = one value; `Metric` = KPI; `ActionsLineGraph` / `ActionsAreaGraph` = time series; `ActionsPie` / `ActionsDonut` / `ActionsProportionBar` = shares; `ActionsBar` / `ActionsStackedBar` = categories; `ActionsBarValue` = horizontal rankings; `TwoDimensionalHeatmap` = 2D aggregates; `ScatterPlot` = two measures; `BoxPlot` = distribution summaries with `chartSettings.boxPlot`.'
).optional(),
kind: z.literal('DataVisualizationNode').default('DataVisualizationNode'),
source: z.record(z.string(), z.unknown()).describe('HogQL query object that produces the rows to visualize.'),
tableSettings: AssistantDataVisualizationTableSettings.describe(
'Table configuration. Only applies when `display` is `ActionsTable` or omitted.'
).optional(),
})
const InsightNodeKind = z.enum([
'TrendsQuery',
'FunnelsQuery',
'RetentionQuery',
'PathsQuery',
'PathsV2Query',
'StickinessQuery',
'LifecycleQuery',
'WebStatsTableQuery',
'WebOverviewQuery',
])
const AssistantMetricsNodeKind = z.enum(['MetricsQuery', 'MetricsHistogramQuery'])
const AssistantBareInsightQuery = z
.object({
kind: z.union([InsightNodeKind, AssistantMetricsNodeKind]),
})
.catchall(z.unknown())
const InsightQuery = z.union([
AssistantDataTableNode,
AssistantBIVisualizationNode,
AssistantInsightVizNode,
AssistantDataVisualizationNode,
AssistantBareInsightQuery,
AssistantBareHogQLQuery,
AssistantEventsQuery,
])
const ElementsStatsRetrieveSchema = () => {
const ElementsStatsRetrieveQueryParams = orvalSchemas.ElementsStatsRetrieveQueryParams()
return ElementsStatsRetrieveQueryParams
}
const elementsStatsRetrieve = (): ToolBase<
ReturnType<typeof ElementsStatsRetrieveSchema>,
Schemas.ElementStatsResponse
> => ({
name: 'elements-stats-retrieve',
schema: ElementsStatsRetrieveSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof ElementsStatsRetrieveSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.ElementStatsResponse>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/elements/stats/`,
query: {
data_attributes: params.data_attributes,
date_from: params.date_from,
date_to: params.date_to,
filter_test_accounts: params.filter_test_accounts,
include: params.include,
limit: params.limit,
offset: params.offset,
properties: params.properties,
sampling_factor: params.sampling_factor,
},
})
return result
},
})
const InsightCreateSchema = () => {
const InsightsCreateBody = orvalSchemas.InsightsCreateBody()
return InsightsCreateBody.omit({ derived_name: true, order: true, deleted: true, _create_in_folder: true }).extend({
query: InsightQuery,
dashboards: InsightsCreateBody.shape['dashboards'].describe(
'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(
'Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.'
),
})
}
const insightCreate = (): ToolBase<
ReturnType<typeof InsightCreateSchema>,
WithAgentNote<WithPostHogUrl<Schemas.Insight>>
> => ({
name: 'insight-create',
schema: InsightCreateSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightCreateSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const body: Record<string, unknown> = {}
if (params.name !== undefined) {
body['name'] = params.name
}
if (params.dashboards !== undefined) {
body['dashboards'] = params.dashboards
}
if (params.description !== undefined) {
body['description'] = params.description
}
if (params.tags !== undefined) {
body['tags'] = params.tags
}
if (params.favorited !== undefined) {
body['favorited'] = params.favorited
}
if (params.query !== undefined) {
body['query'] = params.query
}
const result = await context.api.request<Schemas.Insight>({
method: 'POST',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/`,
body,
})
const filtered = omitResponseFields(result, [
'result',
'hasMore',
'columns',
'is_cached',
'query_status',
'hogql',
'types',
]) 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. After substantial visual changes, check the final saved insight once if browser access is already available. Skip browser checks for small edits.\n'
)
},
})
const InsightDeleteSchema = () => {
const InsightsDestroyParams = orvalSchemas.InsightsDestroyParams()
return z.preprocess(
normalizeParamAliases({ id: ['insightId', 'insight_id', 'short_id', 'shortId'] }),
InsightsDestroyParams.omit({ project_id: true })
)
}
const insightDelete = (): ToolBase<ReturnType<typeof InsightDeleteSchema>, Schemas.Insight> => ({
name: 'insight-delete',
schema: InsightDeleteSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightDeleteSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.Insight>({
method: 'PATCH',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/${encodeURIComponent(String(params.id))}/`,
body: { deleted: true },
})
return result
},
})
const InsightGetSchema = () => {
const InsightsRetrieveParams = orvalSchemas.InsightsRetrieveParams()
const InsightsRetrieveQueryParams = orvalSchemas.InsightsRetrieveQueryParams()
return z.preprocess(
normalizeParamAliases({ id: ['insightId', 'insight_id', 'short_id', 'shortId'] }),
InsightsRetrieveParams.omit({ project_id: true })
.extend(InsightsRetrieveQueryParams.omit({ format: true, from_dashboard: true, refresh: true }).shape)
.extend({
filters_override: z
.union([z.string(), z.record(z.string(), z.unknown())])
.optional()
.describe(
"Object (or pre-encoded JSON string) to override the insight's filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged — pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token."
),
variables_override: z
.union([z.string(), z.record(z.string(), z.unknown())])
.optional()
.describe(
'Object (or pre-encoded JSON string) to override the insight\'s HogQL variables for this request only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include `code_name` — partial entries are silently dropped. The simplest workflow is to call `insight-get` first, copy the matching entry from the response, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token.'
),
})
)
}
const insightGet = (): ToolBase<ReturnType<typeof InsightGetSchema>, WithPostHogUrl<Schemas.Insight>> => ({
name: 'insight-get',
schema: InsightGetSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightGetSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.Insight>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/${encodeURIComponent(String(params.id))}/`,
query: {
filters_override: params.filters_override,
include_dashboards: params.include_dashboards,
variables_override: params.variables_override,
},
})
const filtered = omitResponseFields(result, [
'result',
'hasMore',
'columns',
'is_cached',
'query_status',
'hogql',
'types',
]) as typeof result
return await withPostHogUrl(context, filtered, `/insights/${filtered.short_id}`)
},
})
const InsightUpdateSchema = () => {
const InsightsPartialUpdateBody = orvalSchemas.InsightsPartialUpdateBody()
const InsightsPartialUpdateParams = orvalSchemas.InsightsPartialUpdateParams()
return z.preprocess(
normalizeParamAliases({ id: ['insightId', 'insight_id', 'short_id', 'shortId'] }),
InsightsPartialUpdateParams.omit({ project_id: true })
.extend(
InsightsPartialUpdateBody.omit({
derived_name: true,
order: true,
deleted: true,
_create_in_folder: true,
}).shape
)
.extend({
query: InsightQuery.optional(),
dashboards: InsightsPartialUpdateBody.shape['dashboards'].describe(
'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(
'Optional, about 15 words. Omit if the name is enough. No change notes. Max 400 characters.'
),
})
)
}
const insightUpdate = (): ToolBase<
ReturnType<typeof InsightUpdateSchema>,
WithAgentNote<WithPostHogUrl<Schemas.Insight>>
> => ({
name: 'insight-update',
schema: InsightUpdateSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightUpdateSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const body: Record<string, unknown> = {}
if (params.name !== undefined) {
body['name'] = params.name
}
if (params.dashboards !== undefined) {
body['dashboards'] = params.dashboards
}
if (params.description !== undefined) {
body['description'] = params.description
}
if (params.tags !== undefined) {
body['tags'] = params.tags
}
if (params.favorited !== undefined) {
body['favorited'] = params.favorited
}
if (params.query !== undefined) {
body['query'] = params.query
}
const result = await context.api.request<Schemas.Insight>({
method: 'PATCH',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/${encodeURIComponent(String(params.id))}/`,
body,
})
const filtered = omitResponseFields(result, [
'result',
'hasMore',
'columns',
'is_cached',
'query_status',
'hogql',
'types',
]) as typeof result
return withAgentNote(
await withPostHogUrl(context, filtered, `/insights/${filtered.short_id}`),
"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 the dashboard id you just added was not already on the insight before this call. Offer at most once per dashboard in a conversation, however many insights you attach to it. First call subscriptions-list with `dashboard` set to that dashboard's id, and do not offer a second subscription when it returns one. Say nothing when this update left `dashboards` alone or only removed the insight from a dashboard. Describe it the way a person would recognize it, for example a weekly email every Monday morning with these charts attached, or the same thing posted to a Slack channel. To create it, use subscriptions-create. It needs `dashboard` set to the dashboard's id, `dashboard_export_insights` listing up to 20 charts, `target_type` of `email` or `slack`, and `target_value`, `frequency`, `interval` and `start_date`. For a Slack delivery, also set `integration_id`. Find the connected Slack workspace with integrations-list (filter kind=slack) and the channel for `target_value` with integrations-channels-retrieve. Ask the user for the recipients and the cadence rather than choosing them, since this creates a recurring outbound delivery. If either subscriptions-create or subscriptions-list is not available to you in this session, say nothing about subscriptions. If the user already declined a subscription earlier in this conversation, do not offer again."
)
},
})
const InsightsActivityRetrieveSchema = () => {
const InsightsActivityRetrieveParams = orvalSchemas.InsightsActivityRetrieveParams()
const InsightsActivityRetrieveQueryParams = orvalSchemas.InsightsActivityRetrieveQueryParams()
return InsightsActivityRetrieveParams.omit({ project_id: true }).extend(
InsightsActivityRetrieveQueryParams.omit({ format: true }).shape
)
}
const insightsActivityRetrieve = (): ToolBase<
ReturnType<typeof InsightsActivityRetrieveSchema>,
WithPostHogUrl<Schemas.ActivityLogPaginatedResponse>
> => ({
name: 'insights-activity-retrieve',
schema: InsightsActivityRetrieveSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightsActivityRetrieveSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.ActivityLogPaginatedResponse>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/${encodeURIComponent(String(params.id))}/activity/`,
query: {
limit: params.limit,
page: params.page,
},
})
const filtered = {
...result,
results: (result.results ?? []).map((item: any) =>
omitResponseFields(item, [
'detail.changes.*.before',
'detail.changes.*.after',
'detail.trigger',
'detail.type',
])
),
} as typeof result
return await withPostHogUrl(context, filtered, '/insights')
},
})
const InsightsAllActivityRetrieveSchema = () => {
const InsightsAllActivityRetrieveQueryParams = orvalSchemas.InsightsAllActivityRetrieveQueryParams()
return InsightsAllActivityRetrieveQueryParams.omit({ format: true })
}
const insightsAllActivityRetrieve = (): ToolBase<
ReturnType<typeof InsightsAllActivityRetrieveSchema>,
WithPostHogUrl<Schemas.ActivityLogPaginatedResponse>
> => ({
name: 'insights-all-activity-retrieve',
schema: InsightsAllActivityRetrieveSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightsAllActivityRetrieveSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.ActivityLogPaginatedResponse>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/activity/`,
query: {
limit: params.limit,
page: params.page,
},
})
const filtered = {
...result,
results: (result.results ?? []).map((item: any) =>
omitResponseFields(item, [
'detail.changes.*.before',
'detail.changes.*.after',
'detail.trigger',
'detail.type',
])
),
} as typeof result
return await withPostHogUrl(context, filtered, '/insights')
},
})
const InsightsListSchema = () => {
const InsightsListQueryParams = orvalSchemas.InsightsListQueryParams()
return InsightsListQueryParams.omit({ format: true, basic: true, refresh: true }).extend({
limit: z.preprocess(castStringToInt, InsightsListQueryParams.shape['limit']).optional(),
offset: z.preprocess(castStringToInt, InsightsListQueryParams.shape['offset']).optional(),
})
}
const insightsList = (): ToolBase<
ReturnType<typeof InsightsListSchema>,
WithPostHogUrl<Schemas.PaginatedInsightList>
> => ({
name: 'insights-list',
schema: InsightsListSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightsListSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.PaginatedInsightList>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/`,
query: {
created_by: params.created_by,
created_date_from: params.created_date_from,
created_date_to: params.created_date_to,
dashboards: params.dashboards,
date_from: params.date_from,
date_to: params.date_to,
display: params.display,
exclude_bi: params.exclude_bi,
favorited: params.favorited,
include_dashboards: params.include_dashboards,
insight: params.insight,
last_viewed_date_from: params.last_viewed_date_from,
last_viewed_date_to: params.last_viewed_date_to,
limit: params.limit,
offset: params.offset,
order: params.order,
saved: params.saved,
search: params.search,
short_id: params.short_id,
tags: params.tags,
user: params.user,
},
})
const filtered = {
...result,
results: (result.results ?? []).map((item: any) =>
pickResponseFields(item, [
'id',
'short_id',
'name',
'derived_name',
'description',
'tags',
'favorited',
'dashboards',
'created_at',
'created_by',
'last_modified_at',
'last_modified_by',
'last_viewed_at',
'alerts',
])
),
} as typeof result
return await withPostHogUrl(
context,
{
...filtered,
results: await Promise.all(
(filtered.results ?? []).map((item) => withPostHogUrl(context, item, `/insights/${item.short_id}`))
),
},
'/insights'
)
},
})
const InsightsTrendingRetrieveSchema = () => {
const InsightsTrendingRetrieveQueryParams = orvalSchemas.InsightsTrendingRetrieveQueryParams()
return InsightsTrendingRetrieveQueryParams.omit({ format: true })
}
const insightsTrendingRetrieve = (): ToolBase<
ReturnType<typeof InsightsTrendingRetrieveSchema>,
WithPostHogUrl<Schemas.PaginatedTrendingInsightList>
> => ({
name: 'insights-trending-retrieve',
schema: InsightsTrendingRetrieveSchema(),
handler: async (context: Context, params: z.infer<ReturnType<typeof InsightsTrendingRetrieveSchema>>) => {
const projectId = await context.stateManager.getProjectId()
const result = await context.api.request<Schemas.PaginatedTrendingInsightList>({
method: 'GET',
path: `/api/projects/${encodeURIComponent(String(projectId))}/insights/trending/`,
query: {
days: params.days,
include_dashboards: params.include_dashboards,
limit: params.limit,
offset: params.offset,
},
})
const filtered = {
...result,
results: (result.results ?? []).map((item: any) =>
pickResponseFields(item, [
'id',
'short_id',
'name',
'derived_name',
'description',
'tags',
'favorited',
'dashboards',
'created_at',
'created_by',
'last_modified_at',
'last_modified_by',
'last_viewed_at',
'view_count',
'viewers',
])
),
} as typeof result
return await withPostHogUrl(
context,
{
...filtered,
results: await Promise.all(
(filtered.results ?? []).map((item) => withPostHogUrl(context, item, `/insights/${item.short_id}`))
),
},
'/insights'
)
},
})
export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
'elements-stats-retrieve': elementsStatsRetrieve,
'insight-create': insightCreate,
'insight-delete': insightDelete,
'insight-get': insightGet,
'insight-update': insightUpdate,
'insights-activity-retrieve': insightsActivityRetrieve,
'insights-all-activity-retrieve': insightsAllActivityRetrieve,
'insights-list': insightsList,
'insights-trending-retrieve': insightsTrendingRetrieve,
}