MCP tools for split tests
Create, inspect, update, start, complete, and delete split tests, including variant payloads and the publication boundary.
Split-test tools manage test records for existing questions, offers, and flows. They do not create duplicate base resources. Starting a test changes its stored status immediately; publication deploys the active test to the website. Ending a test records the winner and can replace original content in the draft.
MCP split-test access and lifecycle
Every operation accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. Invalid or inaccessible projects return errors.
split_test_pid is the public test ID returned as pid, not a resource ID or a made-up st_ identifier. Missing input, invalid IDs, and cross-project or unknown tests return errors.
The state sequence is draft → active → completed. Only draft tests can be edited or started. Only active tests can be ended. Completed tests cannot be restarted. Deleting an active test is prohibited.
Examples are illustrative and were not executed. Requests are tools/call parameters; responses are decoded payloads. Synthetic resource IDs assume that the corresponding resources already exist in WorkForge.
Variant payloads
variants is an array of variant objects. Control is implicit and should not be included. Common fields are:
| Field | Type | Meaning |
|---|---|---|
id | string | Nonempty variant identifier, distinct from control. |
name | string | Nonempty display name. |
weight | number | Creation requires 0–100; non-control weights must total at least 1 and less than 100. |
The remaining weight is reserved for control. A supplied control object is removed during creation, and the remaining weights are redistributed. Don't copy the tool description's two-variant example with weights 50 and 50. Creation rejects that sum.
Question overrides
Question tests support one to three non-control variants, with unique IDs. Only one draft or active test may exist for a question.
text: optional nullable string overriding question text. Blank wording inherits control.description: optional nullable string with the same inheritance behavior.answers: optional nullable object keyed by an existing answer's segment ID. A value can be a label string or an object withlabelandimageUrl. Omitted, null, or empty-string values inherit control; promotion applies only nonempty label/image strings. Unknown segment keys do not create options.
Choice questions can vary question and answer wording. Input questions use text and description overrides. These payloads do not create new answer segments or change the underlying input type. buttonText is not a promoted question override.
Offer overrides
Offer variants can contain parts, an object with title, description, buttonText, and imageUrl string overrides. Omit a part to inherit it. Use intentional, nonempty values rather than null or empty patches.
A link-action offer can also contain link, a sparse object with only:
url: optional nonempty destination string.open: optional boolean controlling whether it opens in a new tab.
Omitting link inherits the complete link. Within a supplied link, omitted fields inherit. Unknown link keys, null/empty link objects, malformed values, or link overrides on non-link offers are rejected. The create handler does not impose an offer-specific variant-count maximum.
Flow overrides
Flow creation accepts up to four variants. Every variant must include a complete funnelDefinition object with type: "root". It is a replacement tree, not a patch.
The tool advertises this as an open object rather than a separate recursively enumerated JSON schema. Preserve the complete valid flow node structure, including each node's type-specific fields and ordered child or branch arrays. The creation handler checks that the supplied root is a nonempty object/array with root type; that is not a guarantee that every nested node is runnable. Read the existing flow and use its validated node definitions rather than inferring a tree from these minimal root checks.
create-split-test
Creates a test record in draft status.
| Argument | Type | Required | Meaning |
|---|---|---|---|
project_id | string | No | Public project ID. |
resource_type | string | Yes | question, offer, or flow. |
resource_id | string | Yes | Existing resource ID. |
variants | array of objects | Yes | Nonempty array using the payload rules above. |
Creation immediately stores the test record but does not start or publish it. Missing fields, unsupported resource types, invalid weights, excessive question/flow variants, duplicate open question tests, and invalid variant definitions return errors. Shared mutation failures use Validation error: ... or Operation failed: ....
list-split-tests
Lists stored tests, optionally filtered.
Arguments: optional project_id string; optional resource_type, resource_id, and status strings. Supported resource types are question, offer, and flow; normal status values are draft, active, and completed. For clarity, pair a resource ID with its type. The handler applies supplied filters independently.
Each item contains pid, resource_type, resource_id, status, variants, started_at, ended_at, and winner_id; resolved resources can add resource_name. There are no pagination arguments. No matches returns []. This does not compute metrics or alter a test.
get-split-test
Reads one test, its original content, and optionally its metrics.
Arguments: optional project_id string; required split_test_pid string; optional include_metrics boolean, default true.
Illustrative response excerpt:
The full response includes test metadata and variants described under listing, plus snapshot. original_content for a question contains text, description, buttonText, and options, whose items contain segmentId, label, and imageUrl. Offer original content contains title, description, buttonText, and imageUrl; link-action offers also include url and openInNewTab. A flow does not receive the same top-level original-content expansion.
Original content uses draft-first configuration for draft tests and published configuration for active/completed tests. A completion snapshot, when present, contains created_at, original_content, and metrics; question snapshots also preserve related segment information.
Metrics are attached only for active/completed tests when requested. A metrics exception can leave the test readable with metrics: null and metrics_error. This operation changes neither test state nor configuration.
get-split-test-metrics
Retrieves performance for an active or completed test.
Arguments: optional project_id string and required split_test_pid string. There is no date-range or winner-selection argument.
Illustrative offer-test response:
The envelope contains splitTestPid and metrics, keyed by variant ID. Entries include variantId, resolved variantName, exposures, conversions, and percentage conversionRate.
Question entries also include confidenceInputs: {visitors, answered} and answerDistribution: {coverage, respondents, answers}. answers is keyed by segment ID with {count, share}. Coverage contains status (available or unavailable), nullable reason, and nullable from timestamp. respondents can be null when answer capture is unavailable. Do not substitute empty distributions for proven zero answers.
Flow responses add primaryMetric, either offerConversionRate when an arm includes offers or completionRate otherwise. Flow entries add completions, completionRate, offerConversions, offerConversionRate, avgDurationMs, dropoffs, and dropoffRate. Flow and question queries reject incomplete metric results. The older offer metric path can return zero control metrics after a backend exception, so zero values alone are not proof of a functioning data pipeline.
Draft tests return an error. The tool does not declare statistical significance, choose a winner, or change state. Inspect the sample size and coverage before making a decision.
update-split-test
Replaces the stored variants of a draft test. It is not a per-variant merge.
Arguments: optional project_id string; required split_test_pid string; variants array of objects. Although the advertised schema does not mark variants required, the handler rejects a request without it because there are no other editable fields.
Include every variant you want to retain. This overwrites stored test data immediately, but does not publish it. Active/completed tests return a state error; absent update data returns No update fields provided. Pass variants to update. Model validation still applies to question and offer variants. The update handler does not repeat all of creation's weight and flow-root checks, so clients should retain the valid creation contract rather than relying on weaker update validation.
start-split-test
Changes a draft test to active and records started_at.
Arguments: optional project_id string and required split_test_pid string.
This is a consequential activation, not a private preview. Variants become locked, and a subsequent configuration publication can include the active test. The handler itself does not compile or publish the snippet. The response's active message describes stored test state, not proof that new code reached visitors.
An active question test also locks changes to the question's wording, answers, display, behavior, linked segment values, and non-sync Auto-Segment rules. This applies to other mutation tools and configuration restores too. Sync mappings, internal names, and flow membership can still change. End the test before attempting a locked edit.
Only draft tests can start. Confirm the intended resource and variants, then use the publication tools when ready to deploy. Publication can include other pending configuration changes.
end-split-test
Completes an active test and declares control or a stored variant the winner.
Arguments: optional project_id string; required split_test_pid string and winner_id string. winner_id must be control or an existing variant ID.
Ending a test saves a completion snapshot and attempts to capture metrics. A metrics error leaves snapshot.metrics: null but does not by itself prevent completion. Test completion and promotion of a non-control winner either succeed together or fail together. A non-control winner overwrites supported question copy and answer wording, offer content and links, or the flow tree in the draft. Promoting a question's answer label can also change the corresponding segment name. Choosing control leaves original content unchanged but still completes the test record.
A winning variant replaces the prior editable content. The tool saves a configuration snapshot before promotion and notifies editors. It does not publish. Publish to deploy the winner and remove the running experiment from the served configuration. A completed test record alone does not prove that a previously published test has stopped running in browsers.
Wrong state, unknown winner, invalid ID, or invalid promotion returns an error. Review metrics and obtain a deliberate winner decision before calling it; the completion snapshot is not a guaranteed substitute for that review.
delete-split-test
Permanently deletes a draft or completed test record, including its stored completion snapshot.
Arguments: optional project_id string and required split_test_pid string.
Active tests must be ended first. Deletion is immediate account-record removal, not a draft operation. Configuration undo cannot restore the test record, and deleting a completed test does not revert content already promoted or published. Missing/invalid IDs, unknown tests, and active-state deletion return errors.