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.

fix(experiments): say which id the recalculation MCP tool wants (#128662)

ruby childsa80cae507f0e
diff --git a/products/experiments/mcp/tools.yaml b/products/experiments/mcp/tools.yaml
index 261ac290badc..ed4563d81c50 100644
--- a/products/experiments/mcp/tools.yaml
+++ b/products/experiments/mcp/tools.yaml
@@ -940,11 +940,16 @@ tools:
Returns 404 if the run id does not exist or belongs to a different experiment.
param_overrides:
id:
+ description:
+ The experiment's numeric ID, not the recalculation run UUID. Get it from experiment-get or from the
+ response of experiment-metrics-recalculation-create. The run UUID goes in recalculation_id.
cast: string-int
aliases:
- experimentId
- experiment_id
recalculation_id:
+ description: The recalculation run UUID, from experiment-metrics-recalculation-create or
+ experiment-metrics-recalculation-latest-retrieve.
aliases:
- run_id
- runId
diff --git a/services/mcp/src/tools/generated/experiments.ts b/services/mcp/src/tools/generated/experiments.ts
index a4d3a96e3bd2..0f2b1826377e 100644
--- a/services/mcp/src/tools/generated/experiments.ts
+++ b/services/mcp/src/tools/generated/experiments.ts
@@ -960,7 +960,15 @@ const ExperimentMetricsRecalculationRetrieveSchema = () => {
recalculation_id: ['run_id', 'runId', 'recalculationId'],
}),
ExperimentsMetricsRecalculationRetrieveParams.omit({ project_id: true }).extend({
- id: z.preprocess(castStringToInt, ExperimentsMetricsRecalculationRetrieveParams.shape['id']),
+ id: z.preprocess(
+ castStringToInt,
+ ExperimentsMetricsRecalculationRetrieveParams.shape['id'].describe(
+ "The experiment's numeric ID, not the recalculation run UUID. Get it from experiment-get or from the response of experiment-metrics-recalculation-create. The run UUID goes in recalculation_id."
+ )
+ ),
+ recalculation_id: ExperimentsMetricsRecalculationRetrieveParams.shape['recalculation_id'].describe(
+ 'The recalculation run UUID, from experiment-metrics-recalculation-create or experiment-metrics-recalculation-latest-retrieve.'
+ ),
})
)
}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-metrics-recalculation-retrieve.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-metrics-recalculation-retrieve.json
index 593b27814095..980db6d75529 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-metrics-recalculation-retrieve.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/experiment-metrics-recalculation-retrieve.json
@@ -2,11 +2,11 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
- "description": "A unique integer value identifying this experiment.",
+ "description": "The experiment's numeric ID, not the recalculation run UUID. Get it from experiment-get or from the response of experiment-metrics-recalculation-create. The run UUID goes in recalculation_id.",
"type": "number"
},
"recalculation_id": {
- "description": "UUID of the recalculation run to fetch. This is the run's own id, not the experiment id.",
+ "description": "The recalculation run UUID, from experiment-metrics-recalculation-create or experiment-metrics-recalculation-latest-retrieve.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string"
}
diff --git a/services/mcp/tests/unit/experiment-id-aliases.test.ts b/services/mcp/tests/unit/experiment-id-aliases.test.ts
index ae1d26a76c1a..47e85665e945 100644
--- a/services/mcp/tests/unit/experiment-id-aliases.test.ts
+++ b/services/mcp/tests/unit/experiment-id-aliases.test.ts
@@ -99,6 +99,20 @@ describe('experiment id aliases', () => {
it('still rejects a call with no run id', () => {
expect(schema.safeParse({ id: 1 }).success).toBe(false)
})
+
+ // Production traces show agents sending the run UUID as `id`. The rejection echoes
+ // the param description, so the description must point at the right params or the
+ // agent's retry has nothing to go on.
+ it('tells an agent that sent the run UUID as `id` where both values belong', () => {
+ const result = schema.safeParse({ id: runId })
+ expect(result.success).toBe(false)
+ const advertised = z.toJSONSchema(schema, { io: 'input', reused: 'inline' }) as {
+ properties?: Record<string, { description?: string }>
+ }
+ expect(advertised.properties?.id?.description).toMatch(/not the recalculation run UUID/)
+ expect(advertised.properties?.id?.description).toMatch(/goes in recalculation_id/)
+ expect(advertised.properties?.recalculation_id?.description).toMatch(/run UUID/)
+ })
})
describe('experiment-results-get (hand-written) normalizes aliases to `id`', () => {