Skip to main content

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​

ToolPurposeKey inputsReturns
list_funnelsList a workspace's funnels and their IDsworkspaceId, status?, includeArchived?Paginated funnel list
create_funnelCreate a funnel and start async AI HTML generationdata.name, data.prompt, one of data.brandId / data.noBrandjobId, funnelId, status: "pending"
duplicate_funnelCopy an AI/HTML funnel as a new draftfunnelId, data.name?New funnel id, name, editorUrl
update_funnelRequest an AI content edit on an existing funnelfunnelId, prompt, version?jobId, funnelId, editorUrl, status: "pending"
get_funnel_htmlRead an existing funnel's HTML, in numbered windows of up to 32 KBfunnelId, optional offset / column / limit / versioncontent, line window, totals, nextOffset / nextColumn
update_funnel_metadataRename a funnelfunnelId, data.nameUpdated funnel object
get_funnel_job_statusPoll a generation or edit job (long-poll, ~20 s per call)jobIdStatus, URLs and summary when completed
publish_funnelPut the current draft livefunnelId, 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​

NameTypeRequiredDescription
workspaceIdstringYesWorkspace whose funnels to list, from list_workspaces
status"draft" | "live" | "offline"NoOnly funnels with this status. Omit for all statuses
includeArchivedbooleanNoInclude archived funnels. Defaults to false
pagenumberNoPage number, starting at 1 (default 1)
limitnumberNoPage 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:

  1. Call list_brands and present the user with a 4-option brand-pick choice.
  2. Call get_brand (or use the create_brand response directly) to load brand identity.
  3. Ask 3–5 brand-aware clarification questions (goal, audience temperature, length, primary objection).
  4. Then call this tool with brandId set (or noBrand: true if the user declined a brand).

Inputs​

NameTypeRequiredDescription
data.namestringYesShort human-readable funnel name
data.promptstringYesNatural-language brief built from brand-aware clarification answers; cover goal, audience temperature, length tolerance, primary objection
data.brandIdstringExactly one of brandId / noBrandID of the brand profile to apply (from list_brands → get_brand)
data.noBrandtrueExactly one of brandId / noBrandSet only after the user actively chooses to create without a brand
data.workspaceIdstringNoTarget 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​

NameTypeRequiredDescription
funnelIdstringYesID of the AI/HTML funnel to copy
data.namestringNoName 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​

NameTypeRequiredDescription
funnelIdstringYesID of the AI/HTML funnel to edit (isHtmlFunnel: true in list_funnels)
promptstringYesNatural-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 testWhich 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​

NameTypeRequiredDescription
funnelIdstringYesID of an AI/HTML funnel (list_funnels reports isHtmlFunnel: true)
offsetintegerNo1-indexed line to start from (default 1)
columnintegerNoOnly to continue a line the cap cut: pass the previous nextColumn unchanged, with its nextOffset
limitintegerNoMaximum number of lines (default 2000); the 32 KB cap still applies
version"original" | "variant"NoOn 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​

NameTypeRequiredDescription
funnelIdstringYesID of the funnel to rename (from create_funnel or list_funnels)
data.namestringYesNew 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​

NameTypeRequiredDescription
jobIdstringYesJob 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​

NameTypeRequiredDescription
funnelIdstringYesID of the funnel to publish (from create_funnel or list_funnels)
data.domainIdstringNoDomain to publish under (from list_domains). Omit for the shared Perspective domain
data.slugstringNoURL path segment, combined with domainId into {domainUrl}/{slug}. Letters, digits and hyphens only. Ignored without a domainId
confirmStartExperimentbooleanNoSet 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.status is draft).
  • 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. Poll get_funnel_job_status until 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.