> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiment tools

> MCP tools for creating, configuring, running, and reading Web Experiments.

Experiment tools cover the Web Experiment lifecycle. Your assistant can create a test, write the code for each variation, set the traffic split and goals, start the test, and check its health and results.

## Tools

| Tool | Description | Example prompt |
| - | - | - |
| `experiment_list` | Find experiments by name or ID, or list only those with a given status, such as the running ones. Returns paginated summaries (id, name, status, and tags). | "List running experiments on site `d1alzzxd7k`." |
| `experiment_get` | Retrieve an experiment's full configuration: variations, traffic split, goals, and targeting. | "Show the configuration for experiment `149640`." |
| `experiment_code_get` | Pull a variation's raw JavaScript, CSS, and custom JSON, plus the experiment's shared common JS and CSS. | "Pull the code for variation 1 of experiment `149640`." |
| `experiment_results_get` | Fetch statistical results for every attached goal: per-variation conversion rates, significance, confidence intervals, and the winner. Optionally split the results with `breakdown`, narrow them with `filters`, `dateFrom`, and `dateTo`, and choose the `statisticalMethod`, `conversionType`, and `referenceVariationId`. | "Summarize results for experiment `149640`." |
| `experiment_create` | Create a draft experiment (type, base URL, goals, optional common code). It comes with a first variation and a targeting rule. | "Create a CLASSIC experiment `Homepage hero` on site `d1alzzxd7k`." |
| `experiment_variation_create` | Add a variation with its own JavaScript, CSS, custom JSON, or redirect settings to an existing experiment. Draft experiments split traffic evenly. A running experiment gets the new variation at 0%. | "On experiment `149640`, add a variation that makes the `#buy-now` button green." |
| `experiment_variation_update` | Change a variation's code, name, or redirect. Only the fields you pass change, and repeating a call with the same values changes nothing. | "In variation 1 of experiment `149640`, make the `#buy-now` button red." |
| `experiment_update` | Change an existing experiment's settings: name, description, base URL, tags, goals and main goal, shared JavaScript and CSS, global script, data collection, whether shared code also runs on the original page, multiple testing correction, and traffic allocation method. Use it to attach the goal an experiment needs before it can start. Only the fields you pass change. Needs confirmation when the experiment isn't a draft. | "On experiment `149640`, set goal `271552` as the main goal." |
| `experiment_traffic_allocation_set` | Set the traffic split of the original page and every variation. Draft experiments change immediately. Scheduled and paused experiments need confirmation, and the new split takes effect when they start or resume. Use the Kameleoon app to change the split of running, deviated, and stopped experiments. | "On experiment `149640`, split traffic 50/50 between the original and variation 1." |
| `experiment_duplicate` | Clone an experiment into a new draft, copying variations, code, deviations, and targeting. | "Duplicate experiment `149640`." |
| `experiment_health_check_get` | Run the Health tab checks for an experiment: visit and conversion tracking per goal, sample ratio mismatch, and overlapping exposure. Returns an overall status with a finding and next step for each check. | "Is experiment `149640` healthy? Are its results reliable?" |
| `experiment_lifecycle_update` | Drive the lifecycle: start, pause, resume, stop, or delete (stop and delete require confirmation). Starting an experiment requires a goal, variations, and a traffic split. You can pause running or scheduled experiments, and stop running, scheduled, or paused ones. You can delete only draft or stopped experiments. | "Start experiment `149640`." |
| `transpose_winning_experiment` | Single-entry-point tool that fetches a winning (or manually selected) variation's code, applies winner-decision logic, and returns instructions for the calling agent to re-implement the variation and gate it behind a new feature flag. One call replaces the older multi-step manual prompt workflow. | "Implement the winning variant of experiment `373001` as a feature flag." |

> [!NOTE]
>
> `experiment_create` accepts `MVT` and `SDK_HYBRID` as valid `type` values, but this tool can't actually create either one. `MVT` always fails because the API requires `mvtVariations` (sections and variations) on creation, and no MCP tool exposes that field. `SDK_HYBRID` always fails with an "Incorrect Experiments type" error, regardless of payload. `AI`, `CLASSIC`, `DEVELOPER`, and `PROMPT` all create successfully. To create an MVT experiment, call the Automation API directly and follow the steps in [Create a multivariate experiment](https://docs.kameleoon.com/developer-docs/apis/automation-api-rest/tutorials/experiments/creation/create-a-multivariate-experiment.md).

> [!NOTE]
>
> The variation tools don't support stopped, MVT, or feature-flag experiments. For feature flag variations, use `feature_flag_variation_create`. You can't change the traffic split of a running experiment, or of one that uses a bandit allocation method, through the MCP server.

## Check experiment health

Ask your assistant to run the Health tab checks before you act on a test's results.

* **Is the test healthy?** `experiment_health_check_get` runs the checks of the Health tab: visit and conversion tracking, sample ratio mismatch, and overlapping exposure.

## Parameters

Use the exact parameter names that `tools/list` returns.

| Tool | Required parameters | Optional parameters |
| - | - | - |
| `experiment_list` | None | `siteCode`, `filterQuery`, `status` (one or more of `active`, `deviated`, `draft`, `paused`, `scheduled`, `stopped`, `used_as_personalization`; running experiments are `active` and `deviated`), `page`, `perPage`, `sortField`, `sortOrder` |
| `experiment_get` | `experimentId` | None |
| `experiment_code_get` | `experimentId`, `variationId` | None |
| `experiment_results_get` | `experimentId` | `goalIds`, `audienceBasis` (`VISITORS` by default, or `VISITS`), `includeRawReport`, `breakdown` (`DAY`, `WEEK`, `MONTH`, `HOUR`, `DEVICE_TYPE`, `BROWSER`, `OS`, or `NEW_VISITOR`), `filters` (a list of strings, or one `;`-separated string, in the format `DIMENSION=V1,V2` or `DIMENSION!=V1,V2`), `dateFrom` and `dateTo` (`YYYY-MM-DD`), `statisticalMethod` (`FREQUENTIST` by default, `SEQUENTIAL`, `BAYESIAN`, or `CUPED`), `conversionType` (`CONVERTED` by default, or `ALL`), `referenceVariationId` (a variation ID, or `0` for the original) |
| `experiment_create` | `payload` (`siteCode`, `name`, `type`, `baseURL`) | `payload`: `mainGoalId`, `goals`, `tags`, `description`, `commonJavaScriptCode`, `commonCssCode`, `trafficAllocationMethod`, `collectingDataEnabled`, `multipleTestingCorrection`, `executeCodeForReference` |
| `experiment_variation_create` | `experimentId`, `name` | `jsCode`, `cssCode`, `customJson` (a JSON string), `isJsCodeAfterDomReady`, `shadowDom`, `redirection` (`type` required; `url` for `GLOBAL_REDIRECTION`; `parameters` for `PARAMETER_REDIRECTION`; `includeQueryParameters`, default `false`), `confirm` (required when the experiment isn't a draft) |
| `experiment_variation_update` | `variationId` | `experimentId` (the tool refuses the call if it doesn't match the variation's experiment), `name`, `jsCode`, `cssCode` (an empty string clears the field), `customJson` (a JSON string), `isJsCodeAfterDomReady`, `shadowDom`, `redirection` (replaces the existing redirect settings; `type` required), `confirm` (required when the experiment isn't a draft) |
| `experiment_update` | `experimentId` | `name`, `description` (an empty value keeps the current one), `baseURL` (an absolute `http` or `https` URL), `tags` and `goals` (each replaces the whole list), `mainGoalId`, `commonJavaScriptCode`, `commonCssCode`, `globalScript` (an empty string clears the field), `collectingDataEnabled`, `executeCodeForReference`, `multipleTestingCorrection`, `trafficAllocationMethod` (not while the experiment serves traffic or after it has stopped), `confirm` (required when the experiment isn't a draft) |
| `experiment_traffic_allocation_set` | `experimentId`, `originPercentage` (0 to 100), `variationAllocations` (one entry for every variation, each with `variationId` and `percentage`; the total with `originPercentage` can't exceed 100) | `respool` (default `false`), `confirm` (required for scheduled and paused experiments) |
| `experiment_duplicate` | `experimentId` | None |
| `experiment_health_check_get` | `experimentId` (for a feature flag experiment, the experiment ID of the rule) | None |
| `experiment_lifecycle_update` | `experimentId`, `status` | `confirm` (required for `stopped` and `deleted`), `reason` |
| `transpose_winning_experiment` | `experimentId` | `mode` (`strict_winner_only` default, or `manual_variation_conversion`), `fallbackVariationId` (required when `mode` is `manual_variation_conversion`), `targetFeatureKey` (defaults to `pbx-winning-experiment-<experimentId>`) |

**Accepted enum values:** `experiment_lifecycle_update.status` is `started`, `resumed`, `paused`, `stopped`, or `deleted`. Experiment `type` is `AI`, `CLASSIC`, `DEVELOPER`, `MVT`, `PROMPT`, or `SDK_HYBRID`. `trafficAllocationMethod` is `MANUAL` (default), `MULTI_ARMED_BANDIT`, or `CONTEXTUAL_BANDIT`. `audienceBasis` is `VISITORS` (default) or `VISITS`.

### Results settings

Read an experiment's results with `experiment_results_get`.

For `experiment_results_get`, `feature_flag_experiment_results_get`, and `transpose_winning_experiment`, the `goalResults` array covers every goal attached to the experiment, which includes primary and secondary goals. Kameleoon computes a winner verdict for the primary goal only. Secondary goals return the same statistical figures as guardrail metrics, without a verdict.

`experiment_results_get` and `feature_flag_experiment_results_get` accept these optional settings:

* `breakdown`: splits the results. `DAY`, `WEEK`, and `MONTH` show a trend over time. `HOUR` shows a trend over a `dateFrom` and `dateTo` window of at most 2 days. `DEVICE_TYPE`, `BROWSER`, `OS`, and `NEW_VISITOR` return one bucket per value. Period buckets carry audience, conversions, and conversion rate only. Improvement and reliability stay in the summary for the whole run.
* `filters`: a list of strings, or one string with `;` between filters. Kameleoon combines the filters with AND. Each filter has the format `DIMENSION=V1,V2` or `DIMENSION!=V1,V2`. The dimensions and values are `DEVICE_TYPE` (`DESKTOP`, `TABLET`, `PHONE`), `BROWSER` (`CHROME`, `EDGE`, `FIREFOX`, `SAFARI`, `OPERA`, `OTHERS`), `OS` (`WINDOWS`, `MAC_OS`, `I_OS`, `LINUX`, `ANDROID`, `WINDOWS_PHONE`, `OTHERS`), and `NEW_VISITOR` (`NEW`, `RETURNING`). A breakdown by `DEVICE_TYPE` can show an `OTHERS` bucket, but you can't filter on `DEVICE_TYPE=OTHERS`.
* `dateFrom` and `dateTo`: a specific period, as `YYYY-MM-DD` dates in the account time zone. `dateTo` is inclusive. Set them only when you need a specific period. A narrower window gives noisier figures, so don't call a winner from a short window.
* `statisticalMethod`: `FREQUENTIST` (default), `SEQUENTIAL`, `BAYESIAN`, or `CUPED`. With `BAYESIAN`, `reliabilityRate` becomes the probability to beat the reference. `CUPED` applies to whole-run figures only, and breakdown buckets stay frequentist. The tool rejects a method that your plan doesn't include.
* `conversionType`: `CONVERTED` (default) counts each converting visitor once. `ALL` counts every conversion, so the rate can exceed 100%. Improvement and reliability follow it: with `ALL` they compare conversions per visitor.
* `referenceVariationId`: the variation that the others compare against. Pass a variation ID, or `0` for the original. For feature flags, pass a variation ID or key, or `0` or `off` for the off variation. The default is the experiment's saved reference, or the original if the experiment has none.

The response states the settings it applied in `appliedOptions` and adds notes where a figure needs context. The response leaves out figures that the engine didn't compute, for example because of too little data or a reference without conversions, and adds a note for each one.

Results compare against the reference saved on the experiment, as the results screen does. Experiments that Kameleoon builds from a prompt, and feature flag experiments whose off variation gets 0% of the traffic, don't return improvement and reliability.

## Tutorials

* [Create variations with custom code](https://docs.kameleoon.com/mcp/create-variations-with-code.md): Build a test with several variations, each with its own code.
* [Prepare a draft experiment](https://docs.kameleoon.com/mcp/prepare-draft-experiment.md): Set the goal, traffic split, and targeting before you start.
* [Ship a winning variation to production](https://docs.kameleoon.com/mcp/ship-winning-variation.md): Turn a winning variation into a gated feature flag.