finding-experiments

Finding experiments

Users refer to experiments by name, description, or relative references — not by ID. This skill resolves natural language references to concrete experiment IDs.

How to find an experiment

Use the experiment-list tool from the Posthog-local MCP server.

IMPORTANT: Do NOT use feature-flag-get-all or any feature flag tool to find experiments. Use the dedicated experiment list tool: experiment-list.

This tool returns experiments with their id, name, status, feature_flag_key, start_date, end_date, and created_at. Browse the returned list to find the experiment matching the user's reference:

• By name: scan the name field for matches
• By recency: results are ordered newest first by default
• By status: match the status field (draft, running, paused, exposure_frozen, stopped)
• By flag key: skip the list and call experiment-get-by-flag-key with the key. It returns the full experiment, or found: false with a reason. no_flag and no_experiment mean the key is free, so this is also the existence check to run before experiment-create. ambiguous means several experiments share the flag and none is the single live one: show the candidates and pick one with experiment-get rather than creating another.

After finding matches

• Exactly one match: Use it. Confirm with the user by name before destructive actions (delete, ship, end).
• Multiple matches: List them with name, status, and creation date. Ask the user to pick.
• No matches: Tell the user. Suggest checking archived experiments or different terms.

Get full details if needed

After resolving to an ID, call experiment-get for the full object (metrics, flag details, parameters).

Examples

User: "pause my signup experiment"

Agent:
1. Calls experiment-list
2. Scans results, finds "New signup process" (ID: 1371, status: running)
3. Proceeds to pause experiment 1371

When NOT to search

• You already have the experiment ID from earlier in the conversation
• The user just created the experiment — you have the ID from the create response
• The user provided the ID directly

Related skills

• managing-experiment-lifecycle — act on the experiment once you've resolved its ID
• diagnosing-experiment-results — investigate the experiment you found