Funnels
These tools cover the full AI-powered funnel lifecycle: find a funnel, create one from a natural-language brief or copy an existing one, request content edits, poll an async job until it finishes, and publish the result. A typical flow is create_funnel → get_funnel_job_status (loop until completed) → publish_funnel once the user agrees, then update_funnel → get_funnel_job_status → publish_funnel for each later revision.
Creating and editing only change the funnel's draft. Nothing reaches a visitor until publish_funnel is called, so confirm with the user before each publish.
Before calling create_funnel you must pick (or create) a brand profile via list_brands and get_brand — the brand's colors, typography, and voice are woven into the generation brief automatically.
Funnels can also run A/B tests. When a funnel has one, update_funnel and publish_funnel behave a little differently; see Experiments (A/B Tests).
Tools
| Tool | Purpose | Key inputs | Returns |
|---|---|---|---|
list_funnels | List a workspace's funnels and their IDs | workspaceId, status?, includeArchived? | Paginated funnel list |
create_funnel | Create a funnel and start async AI HTML generation | data.name, data.prompt, one of data.brandId / data.noBrand | jobId, funnelId, status: "pending" |
duplicate_funnel | Copy an AI/HTML funnel as a new draft | funnelId, data.name? | New funnel id, name, editorUrl |
update_funnel | Request an AI content edit on an existing funnel | funnelId, prompt, version? | jobId, funnelId, editorUrl, status: "pending" |
get_funnel_html | Read an existing funnel's HTML, in numbered windows of up to 32 KB | funnelId, optional offset / column / limit / version | content, line window, totals, nextOffset / nextColumn |
update_funnel_metadata | Rename a funnel | funnelId, data.name | Updated funnel object |
get_funnel_job_status | Poll a generation or edit job (long-poll, ~20 s per call) | jobId | Status, URLs and summary when completed |
publish_funnel | Put the current draft live | funnelId, data?, confirmStartExperiment? | funnelId, liveUrl, experiment? |
list_funnels
The main way to discover funnels and their IDs. Each funnel has a status (draft, live, offline). Drafts and classic (non-HTML) funnels are included; archived funnels only with includeArchived: true. Check isHtmlFunnel on each item: only AI/HTML funnels can be edited, copied or tested through MCP.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Workspace whose funnels to list, from list_workspaces |
status | "draft" | "live" | "offline" | No | Only funnels with this status. Omit for all statuses |
includeArchived | boolean | No | Include archived funnels. Defaults to false |
page | number | No | Page number, starting at 1 (default 1) |
limit | number | No | Page size, 1–100 (default 25) |
Returns the funnels plus pagination info (count, totalCount, pageCount). More pages exist while page is below pageCount.
create_funnel
Starts AI generation of a brand-new funnel from a natural-language brief. The call is non-blocking: it creates an empty funnel shell, kicks off the AI generation job, and returns immediately with status: "pending". Poll get_funnel_job_status until status: "completed" to get the editor URL.
The funnel is created as a draft and does not publish itself. Once generation completes, ask the user whether to publish, then call publish_funnel.
Mandatory pre-call flow:
- Call
list_brandsand present the user with a 4-option brand-pick choice. - Call
get_brand(or use thecreate_brandresponse directly) to load brand identity. - Ask 3–5 brand-aware clarification questions (goal, audience temperature, length, primary objection).
- Then call this tool with
brandIdset (ornoBrand: trueif the user declined a brand).
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
data.name | string | Yes | Short human-readable funnel name |
data.prompt | string | Yes | Natural-language brief built from brand-aware clarification answers; cover goal, audience temperature, length tolerance, primary objection |
data.brandId | string | Exactly one of brandId / noBrand | ID of the brand profile to apply (from list_brands → get_brand) |
data.noBrand | true | Exactly one of brandId / noBrand | Set only after the user actively chooses to create without a brand |
data.workspaceId | string | No | Target workspace; defaults to account default |
Returns { data: { jobId, funnelId, status: "pending" } }.
duplicate_funnel
Copies an existing AI/HTML funnel into the same workspace, keeping its integrations and brand. The copy is created immediately, so there is no job to poll. It is always an unpublished draft, even when the source is live; ask the user before publishing it with publish_funnel.
A classic funnel returns "Funnel not found" here, so pick one with isHtmlFunnel: true from list_funnels. The copy counts against the account's funnel and workspace limits but uses no AI credits. The copy starts without the source's AI chat history; the first update_funnel on it opens a new conversation on top of the copied page.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | ID of the AI/HTML funnel to copy |
data.name | string | No | Name for the copy. Omit to reuse the source name as is (prefer a distinct name) |
Returns { data: { id, name, editorUrl } }.
update_funnel
Appends a natural-language edit instruction to the funnel's existing AI conversation, so each edit keeps the earlier context. The edit changes the funnel's draft only: the live URL stays the same until publish_funnel is called again after the job completes. Only one generation may run at a time per funnel — poll get_funnel_job_status until the current job is done before calling again.
Works on any AI/HTML funnel: created with create_funnel, copied with duplicate_funnel, or created through the API. Classic funnels have to be edited in the Perspective app.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | ID of the AI/HTML funnel to edit (isHtmlFunnel: true in list_funnels) |
prompt | string | Yes | Natural-language description of the change (e.g. "make the headline punchier and add a testimonials section"). For a bug, describe the symptom and steps to reproduce, not a fix |
version | "original" | "variant" | While the funnel has an A/B test | Which version of the page to edit. Required while the funnel has a draft or running test; leave it out otherwise |
version and A/B tests
A funnel with a draft or running A/B test has two pages: the original and the variant. Every edit has to say which one it is for. Without version, the call fails with EXPERIMENT_VERSION_REQUIRED. On a funnel without a test, version: "variant" fails with NO_EXPERIMENT_VARIANT.
Both versions share the funnel's one AI conversation, so the returned jobId and get_funnel_job_status work the same for either. The share card, favicon and cookie banner belong to the whole funnel and cannot be changed on the variant, so change them with version: "original", which applies them to both versions.
On a running test, a finished edit is saved but visitors keep seeing the old content of that version until the funnel is published again. See Changes go live on publish.
Returns { data: { jobId, funnelId, editorUrl, status: "pending" } }.
get_funnel_html
Reads the current HTML of an existing AI/HTML funnel, so the assistant can see what is on its pages before it describes a change for update_funnel. Read-only: edits still go through update_funnel.
Lines come back numbered (N→). Each result is capped at 32 KB, cut at a whole line, so a large funnel is read in windows: the result reports the window, the document's total size, and nextOffset to continue from. A single line larger than the cap (for example a minified funnel) is cut mid-line; the result then also returns nextColumn, and passing it as column reads on inside that line.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | ID of an AI/HTML funnel (list_funnels reports isHtmlFunnel: true) |
offset | integer | No | 1-indexed line to start from (default 1) |
column | integer | No | Only to continue a line the cap cut: pass the previous nextColumn unchanged, with its nextOffset |
limit | integer | No | Maximum number of lines (default 2000); the 32 KB cap still applies |
version | "original" | "variant" | No | On a funnel with an A/B test, which version to read (default original) |
Returns { data: { funnelId, content, startLine, startColumn?, endLine, totalLines, totalBytes, truncated, nextOffset?, nextColumn? } }. nextOffset is absent once the window reaches the end of the document.
update_funnel_metadata
Renames a funnel without touching its content. It does not publish; to move a funnel to another domain or slug, use publish_funnel.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | ID of the funnel to rename (from create_funnel or list_funnels) |
data.name | string | Yes | New funnel name (minimum 1 character) |
Returns { data: { id, name, ... } } — the updated funnel object.
get_funnel_job_status
Long-polls a job started by create_funnel, update_funnel or create_experiment. Each call waits until the job finishes or for about 20 seconds (occasionally longer when the upstream is slow), then returns the latest status, so no extra delay is needed between calls. A full generation usually completes within about 5 minutes.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
jobId | string | Yes | Job token returned by create_funnel, update_funnel or create_experiment |
On completed, returns the funnel name, editorUrl, liveUrl (only once the funnel has been published), a short summary, a ready-to-display markdown rendition, and nextStep, a suggested next step. On failed, returns an error and a hint on how to retry. When the job edited one version of an A/B test, the response says which one and what the next publish will do to the test.
publish_funnel
Promotes the funnel's current draft to a live, browser-viewable URL. Publishing makes changes visible to visitors, so confirm with the user before each publish.
When the funnel is already live, publishing again keeps it on its current domain (omit data). On a first publish, the funnel can go to the shared Perspective domain (omit domainId) or to one of the company's own ready domains from list_domains.
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | ID of the funnel to publish (from create_funnel or list_funnels) |
data.domainId | string | No | Domain to publish under (from list_domains). Omit for the shared Perspective domain |
data.slug | string | No | URL path segment, combined with domainId into {domainUrl}/{slug}. Letters, digits and hyphens only. Ignored without a domainId |
confirmStartExperiment | boolean | No | Set to true only after the user has agreed to start the funnel's draft A/B test, in reply to an EXPERIMENT_START_NOT_CONFIRMED error. Not needed when the funnel has no test or its test is already running |
confirmStartExperiment and A/B tests
Publishing is the moment a draft A/B test starts. So on a funnel with a draft test, the first call does not publish. It fails with EXPERIMENT_START_NOT_CONFIRMED and includes the test's name and split. Confirm with the user that they want to start the test (both versions go live and visitors are split), then call again with confirmStartExperiment: true. Publishing such a funnel always tries to start its test; to publish without it, discard the test first.
On a running test, publishing pushes the latest edits and split of both versions to visitors. No confirmation flag is needed.
After a publish, the response's message says what happened to the test:
- Started: the draft test is now running and visitors are split.
- Refreshed: the test was already running; the latest edits and split now reach visitors.
- Not started: the user's role does not allow starting tests. The funnel is still published, showing only the original, and the test stays a draft (
experiment.statusisdraft). - Failed: the funnel is published, but starting or refreshing the test failed. A draft test stays a draft, and a running test keeps serving each version as of the previous publish. Publishing again retries it.
Errors
FUNNEL_GENERATION_IN_PROGRESS: an AI generation (including a variant being written) is still running. Pollget_funnel_job_statusuntil it completes. A failed generation does not block publishing.EXPERIMENT_START_NOT_CONFIRMED: see above.
Returns { data: { funnelId, liveUrl, experiment? }, message? }. Share liveUrl with the user. experiment (id, status, arms with each version and weight) and message are present whenever the funnel has a draft or running test.
Related
- Tools: Experiments (A/B Tests)
- Guide: ../../guides/funnels