A/B tests tools

search_discovery_experiments: List the A/B test experiments in an account, or fetch one by ID.
get_discovery_experiment_report: Get the analytics report for an experiment.
create_discovery_experiment: Create a new A/B test experiment in draft state.
start_discovery_experiment: Start a draft experiment and begin the live traffic split.
end_discovery_experiment: End a running experiment and optionally promote a winner.
archive_discovery_experiment: Archive a completed experiment.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Bloomreach dashboard, actions your users or agents take with these tools can have a substantial impact on your live search and category experience. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

search_discovery_experiments

Searches the A/B test experiments in an account, or fetches one by ID. Omit experiment_id to list paginated summaries — each with the experiment's name, status, traffic allocation, buckets (variants), and scheduling details. Filter by status or name to narrow the list.

Pass experiment_id to fetch the full configuration of one experiment, including its traffic allocation, buckets with rule info, success metric, and winner bucket if the experiment has completed. Use get_discovery_experiment_report for its statistical results.

Request parameters

Name	Type	Required?	Description
`experiment_id`	`int \| null`	No	The experiment ID. Omit to list all experiments; provide to fetch one.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected for you.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).
`page`	`int`	No	The page number, zero-based. Defaults to `0`. Ignored when `experiment_id` is set.
`limit`	`int`	No	The number of results per page. Defaults to `10`. Ignored when `experiment_id` is set.
`sort_by`	`str`	No	The field to sort by: `MODIFIED_AT`, `STARTED_AT`, `EXPERIMENT_NAME`, or `ID`. Defaults to `MODIFIED_AT`. Ignored when `experiment_id` is set.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`. Ignored when `experiment_id` is set.
`q`	`str \| null`	No	A search term, at least 3 characters, to filter by experiment or user name. Ignored when `experiment_id` is set.
`experiment_statuses`	`str \| null`	No	A comma-separated list of statuses to filter by: `DRAFT`, `RUNNING`, `COMPLETED`, or `ARCHIVED`. Ignored when `experiment_id` is set.

Response parameters

The tool returns an ExperimentsResponse object when experiment_id is omitted (a list of summaries) or an ExperimentResponse object when experiment_id is provided (a single experiment's full configuration).

The ExperimentsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ExperimentSummary]`	The experiments in the account.
`error`	`str \| null`	Error message if the request failed.

The ExperimentSummary object has the following fields:

Field	Type	Description
`id`	`int`	The experiment's unique ID.
`experimentName`	`str \| null`	The experiment's display name.
`experimentType`	`str \| null`	The experiment type, `targeting` or `testing`.
`experimentStatus`	`str \| null`	The status: `DRAFT`, `RUNNING`, `COMPLETED`, or `ARCHIVED`.
`isEditable`	`bool \| null`	Whether the experiment can be edited.
`sitegroupId`	`int \| null`	The site group this experiment runs on.
`influence`	`str \| null`	The influence metric.
`trafficPercentage`	`int \| null`	The total percentage of traffic allocated to the experiment.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the experiment started.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the experiment ended.
`modifiedAt`	`int \| null`	Unix timestamp in milliseconds of the last modification.
`user`	`str \| null`	The user who last modified the experiment.
`isInternal`	`bool \| null`	Whether this is an internal experiment.
`note`	`str \| null`	An optional note.
`buckets`	`list[ExperimentBucket]`	The traffic buckets (variants) in the experiment.

The ExperimentBucket object has the following fields:

Field	Type	Description
`id`	`int \| null`	The bucket's ID.
`bucketName`	`str \| null`	The bucket's display name.
`trafficPercentage`	`int \| null`	The percentage of traffic routed to this bucket.
`bucketDescription`	`str \| null`	The bucket's description.
`control`	`bool \| null`	Whether this is the control bucket.
`ruleIdentifierInfo`	`ExperimentBucketRuleInfo \| null`	The rule info for the variant.

The ExperimentBucketRuleInfo object has the following fields:

Field	Type	Description
`id`	`int \| null`	The rule ID.
`ruleType`	`str \| null`	The rule type, such as `ranking` or `redirect`.
`variantId`	`int \| null`	The variant ID.
`modifiedAt`	`int \| null`	Unix timestamp in milliseconds of the last modification.
`user`	`str \| null`	The user who last modified the rule.
`query`	`list[ExperimentBucketQuery]`	The queries associated with this rule.

The ExperimentBucketQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text.
`queryType`	`str \| null`	The query type, such as `sitesearch` or `category`.

When experiment_id is provided, the tool returns an ExperimentResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`ExperimentDetail \| null`	The full experiment record.
`error`	`str \| null`	Error message if the request failed.

The ExperimentDetail object adds the following fields on top of the summary record:

Field	Type	Description
`successMetric`	`str \| null`	The success metric: `AOV - Average Order Value`, `ATC Rate - Add to Cart Rate`, `CR - Conversion Rate`, or `RPV - Revenue Per Visit`.
`winnerBucketId`	`int \| null`	The ID of the winning bucket, set when the experiment completes.

get_discovery_experiment_report

Returns the analytics report for an experiment. The report shows performance metrics such as visitors, conversions, revenue, and statistical confidence, comparing the test buckets against a control bucket over a date range.

Every parameter is required. Use search_discovery_experiments first to obtain the bucket names and dates.

Request parameters

Name	Type	Required?	Description
`experiment_id`	`int`	Yes	The experiment ID.
`start_date`	`str`	Yes	The start date in `YYYYMMDD` format, for example `20240101`.
`end_date`	`str`	Yes	The end date in `YYYYMMDD` format, for example `20240131`.
`test_buckets`	`str`	Yes	A comma-separated list of test bucket names.
`control_bucket`	`str`	Yes	The control bucket name.
`experiment_session_type`	`str`	Yes	The session type: `SEARCH`, `CATEGORY`, or `GLOBAL`.
`experiment_name`	`str`	Yes	The experiment name. Must match exactly.

Response parameters

The tool returns an ExperimentReportResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The report data, returned as freeform JSON from the analytics backend.
`error`	`str \| null`	Error message if the request failed.

create_discovery_experiment

Creates a new A/B test experiment. Experiments follow a strict lifecycle: create, then start_discovery_experiment, then end_discovery_experiment, then archive_discovery_experiment. You can't skip steps. Because the experiment is created in draft state, no live traffic is affected until you start it.

Each bucket links to a rule variant. Exactly one bucket must be the control, the bucket traffic_percentage values must sum to 100, and an experiment can have at most four buckets including the control. You can build two patterns. In a rule-versus-default test, the control bucket has no customization_id and represents the default search behavior, while the test bucket sets customization_id to a rule ID. In a rule-A-versus-rule-B test, both buckets point to rule variants. Set success_metric to record your goal for reference, though the test doesn't use it to determine a winner. You decide the winner yourself from the results.

Request parameters

Name	Type	Required?	Description
`name`	`str`	Yes	The display name for the experiment, such as `Search terms - dress`. May contain only alphanumeric characters, spaces, underscores, and hyphens.
`traffic_percentage`	`int`	Yes	The percentage of eligible traffic to include in the test, from 0 to 100. `100` means all eligible traffic participates.
`buckets`	`list[dict]`	Yes	The test buckets. Each entry needs `bucket_name` (alphanumeric, spaces, underscores, and hyphens only), `traffic_percentage` (all buckets must sum to 100), `control` (exactly one bucket must be `True`), and optionally `customization_id` (omit for the default control bucket).
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).
`success_metric`	`str \| null`	No	The success metric: `AOV` (Average Order Value), `ATC_RATE` (Add to Cart Rate), `CR` (Conversion Rate), or `RPV` (Revenue Per Visit). Strongly recommended.
`note`	`str \| null`	No	An optional note for the experiment.

Response parameters

The tool returns an ExperimentMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The created experiment as freeform JSON. Use the returned `id` for later `start_discovery_experiment`, `end_discovery_experiment`, or `archive_discovery_experiment` calls.
`error`	`str \| null`	Error message if the operation failed.

start_discovery_experiment

Starts a draft experiment and moves it to running status. The traffic split begins the moment this call returns, so the experiment goes live immediately with no asynchronous buffer. All variant customizations are set live and enabled, so make sure every variant rule is correctly configured and enabled before you start.

Only draft experiments can be started. Once an experiment is running, only end_discovery_experiment can stop the traffic split.

Request parameters

Name	Type	Required?	Description
`experiment_id`	`int`	Yes	The ID of the draft experiment to start. Use `search_discovery_experiments` to find the ID.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).

Response parameters

The tool returns an ExperimentMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The updated experiment state as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.

end_discovery_experiment

Ends a running experiment and moves it to completed status. This takes effect immediately and can't be restarted. If you provide winner_bucket_id, that variant goes live to 100% of traffic the moment the call returns and all other variants are disabled. If you omit it, all variants are disabled and traffic reverts to the default behavior.

Only running experiments can be ended. Ending without a winner isn't supported when the test uses Global recall algorithm rules or when the default behavior control bucket, with no customization_id, is one of the buckets. In a rule-versus-default test you must always declare a winner. To archive after completion, use archive_discovery_experiment.

Request parameters

Name	Type	Required?	Description
`experiment_id`	`int`	Yes	The ID of the running experiment to end.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).
`winner_bucket_id`	`int \| null`	No	The ID of the winning bucket, which goes live to 100% of traffic immediately. Omit to end without a winner and revert traffic to the default. Use `search_discovery_experiments` to find bucket IDs.

Response parameters

The tool returns an ExperimentMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The updated experiment state as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.

archive_discovery_experiment

Archives a completed experiment. Archiving hides the experiment from the default dashboard view and has no live impact, since it's a visibility change only. You can unarchive an experiment later from the Discovery dashboard.

Only completed experiments can be archived.

Request parameters

Name	Type	Required?	Description
`experiment_id`	`int`	Yes	The ID of the completed experiment to archive.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).

Response parameters

The tool returns an ExperimentMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The updated experiment state as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.