A/B Testing

This reference is auto-generated from the registered MCP tool providers in perspectapiworkers. It reflects the tools exposed by the per-site Perspect MCP server.

Connection

Use the per-site MCP endpoint:

https://perspect.com/mcp/{siteName}

Authenticate with OAuth or an MCP API key using Authorization: Bearer sk_mcp_....

Tools

`ab_create_flag`

Title: Create A/B flag

Create a new A/B flag in draft state. Validates identifier charset, enforces the plan's maxRunningFlags (applied at ab_start_flag) and maxVisitorsPerFlag (applied at the ledger). Variants' weight_bp values must sum to 10000. The default_variant key must match one variant.

Required permission: ab.write

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	Slug identifier: lowercase letters, digits, and hyphens; 1-64 chars; must start with a letter.
`description`	string	No	—	Human-readable description of what's being tested.
`variants`	array<object>	Yes	—	The variants under test. At least two required. weight_bp values must sum to 10000.
`default_variant`	string	Yes	—	The variant key shown when the visitor is unenrolled (fails targeting / outside allocation).
`goals`	array<object>	Yes	—	Conversion events this experiment is measuring. At least one primary goal required.
`targeting_rules`	object	No	—	Optional JSONLogic-style targeting expression (omit to target everyone).
`traffic_allocation_bp`	integer	No	—	Fraction of eligible traffic enrolled, in basis points (0-10000). Default 10000 (100%).
`attribution_window_days`	integer	No	—	How long after exposure a conversion still counts (1-90 days). Default 7.

Example call

{
  "tool": "ab_create_flag",
  "arguments": {
    "key": "string",
    "variants": [
      {}
    ],
    "default_variant": "string",
    "goals": [
      {}
    ]
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_get_flag`

Title: Get A/B flag

Get a single A/B flag by key, including its variants and every recorded version with its config snapshot. Use this before ab_start_flag or to review what ran under a past version.

Required permission: ab.read

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key (e.g. "hero-copy-test").

Example call

{
  "tool": "ab_get_flag",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_get_results`

Title: Get A/B flag results

Get per-variant results for an A/B flag, grouped by version. Each version returns: exposures (visitor count) and conversions keyed by goal event_name, per variant. Stopped versions with elapsed attribution windows return a frozen definitive summary; others return the latest rollup.

Required permission: ab.read

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key to fetch results for.
`version`	integer	No	—	Optional specific version number (defaults to all versions, newest first).

Example call

{
  "tool": "ab_get_results",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_integration_guide`

Title: A/B integration guide

Return prose + code snippets explaining how to integrate A/B flags into a Perspect site: the SSR-first pattern, client-side variant access via /_perspect/ab/variants, the trust model, the variant.config public-safe contract, and handoff behavior when a running flag's version bumps. Call this before writing site code that consumes getVariant() or track().

Required permission: ab.read

Parameters

This tool accepts no arguments.

Example call

{
  "tool": "ab_integration_guide",
  "arguments": {}
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_list_flags`

Title: List A/B flags

List A/B flags for the current site. Returns each flag's current state, version, and declared goals. Does not include variant configs — use ab_get_flag for full details.

Required permission: ab.read

Parameters

Parameter	Type	Required	Default	Description
`status`	string	No	—	Filter by lifecycle status (omit to list all statuses). Allowed: `draft`, `running`, `paused`, `stopped`.
`limit`	number	No	`50`	Max flags to return (1-100, default 50).

Example call

{
  "tool": "ab_list_flags",
  "arguments": {
    "limit": 50
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_pause_flag`

Title: Pause A/B flag

Transition a running A/B flag to 'paused'. Existing assignments are preserved but new visitors see default_variant. Valid from: running.

Required permission: ab.write

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key to pause.

Example call

{
  "tool": "ab_pause_flag",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_resume_flag`

Title: Resume A/B flag

Transition a paused A/B flag back to 'running'. Valid from: paused.

Required permission: ab.write

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key to resume.

Example call

{
  "tool": "ab_resume_flag",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_start_flag`

Title: Start A/B flag

Transition an A/B flag from 'draft' or 'paused' to 'running'. Valid from: draft, paused. Returns the updated flag (same shape as ab_get_flag).

Required permission: ab.write

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key to start (e.g. "hero-copy-test").

Example call

{
  "tool": "ab_start_flag",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

`ab_stop_flag`

Title: Stop A/B flag

Transition an A/B flag to 'stopped'. Stopping is terminal — create a new flag to run again. Valid from: running, paused.

Required permission: ab.write

Parameters

Parameter	Type	Required	Default	Description
`key`	string	Yes	—	The flag key to stop.

Example call

{
  "tool": "ab_stop_flag",
  "arguments": {
    "key": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

This page is generated from the registered MCP tool providers. Do not edit it by hand.