# ConvertNow guide

ConvertNow runs quiz funnels: a visitor answers a few fun questions, leaves their contact details, and gets a result made for them with one next step (book a call, buy, read).

## The model
- A funnel = intro screen -> questions (one per screen) -> contact step (optional) -> result.
- Each question has answer options. Each option gives points to results (by result id). The result with the most points is shown.
- Each question can have up to 4 live versions ("variants"): different wording of the same question. Answer options and points are shared, so the data stays comparable. A version may also re-word the answers with "labels" (by option id).
- Visitors are split evenly between live versions. The same visitor always sees the same version.

## How a test is judged
- For each version we count: shown, answered, and kept going (the visitor reached the end of the quiz after seeing it).
- "Chance to be best" is a Bayesian estimate of the chance each version has the highest keep-going rate.
- Autopilot: once every live version has been seen at least minViews times (default 150) and one version's chance to be best reaches the confidence level (default 95%), it becomes the winner and the others retire. A note records the numbers.

## The self-improving loop
1. Call get_optimization_tasks. Each task is a question that needs a new version (a finished test, or a question with only one version).
2. For each task, write ONE new version (add_variant, writtenByAi: true). Make it different in a way you can learn from: shorter, more personal ("you"), more specific, more curious, or easier to answer. Do not repeat wording that lost.
3. The new version joins the test with an even share. Wait for data, then repeat.
Run this once a day.

## What makes quiz funnels convert
- Intro: promise a specific result ("Find out what is holding your business back"), say how long it takes ("60 seconds"), one big button.
- 3 to 6 questions. The first question is the easiest to answer. Ask about the visitor, not about you.
- 2 to 4 answers per question. Emojis help people answer fast.
- Ask for the email right before the result ("Your plan is ready"), not at the start.
- The result names the visitor's situation and gives one clear next step with a link.
- Plain words. No jargon. Short sentences.

## Sites: see why visitors do not buy, and fix it
ConvertNow also tracks whole websites. One script on every page records visits (pages, time, scroll depth, clicks, rage clicks, dead clicks, forms people give up on, script errors), place (country, region, city) and company (from the visitor's network, when it is a business), and, after the visitor allows it, a recording of the visit.
- Start: create_site (returns the script), then create_goal (what counts as a conversion).
- Read: get_site_overview, get_page_report, get_leave_report (how and where people leave: the ways they leave, exit pages, a step funnel to the goal, a page flow, leave rates by device, source and country), get_exit_tree, get_friction, list_sessions.
- Act: get_site_tasks gives a ranked list of what loses visitors, with evidence and a test idea. Turn the best one into create_site_test.
- A page test changes the live page in the browser: text, html, attr, hide, css, move, redirect or popup (on exit, after seconds, or after scroll; it can open a quiz). Use exact CSS selectors that exist on the page. Kind "test" splits visitors between the original and your versions; kind "personalize" always shows the changes to an audience (countries, cities, devices, sources, companies, new or returning, UTM).
- Judging: visitors are counted once per test. "Chance to be best" is Bayesian. Autopilot picks the winner when every version has minVisitors and one passes the confidence level; then call set_test_status with keepWinner: true, or let the owner do it.
- Each preview link (?cn_preview=<testId>.<armId>) shows a version without counting the visit. Send it to the owner before a big change.
- Good first tests: a headline that says what you sell and for whom, one main button above the fold, fewer form fields, proof (reviews, logos) next to the button, an exit popup with a quiz for visitors who leave the pricing page.
Daily loop: get_site_tasks -> one new test or version -> get_test_results -> keep winners.

## Set up a new account
Call get_setup_steps and do what it says; call it again after each stage. It walks you through: find the owner's sites (propose_sites), the owner picks, then per site install the script, research customers (save_research with seeAndHear and usedTo per segment) and competitors, and build a full new website design draft (save_site_draft). Never overwrite a live site; ask the owner before any deploy.

## Grow a site end to end (the AI does all the work)
The owner connects their AI and it runs the whole job. The MCP prompt grow_my_site starts it.
1. Customers: read get_research. If the audience is empty or older than 30 days, work out who buys: the site's own words, the visits (sources, countries, companies, pages read before converting), reviews and forums you can read. Save it with save_research (audience: segments with what they want, what they fear and the words they use; sources: where each fact came from).
2. Competitors: find 3 to 6 sites that sell the same thing to the same people. Read each with study_competitor (message, calls to action, prices, proof, offers, ad and analytics tools, page sections from the sitemap) and estimate_competitor_traffic (monthly visits from public signals, trend, likely sources). Keep the basis next to every number. Save with save_research (competitors). Never present an estimate as a measured fact.
3. Plan: compare our site with the best competitor and with get_leave_report and get_site_tasks. Pick the 1 to 3 changes most likely to raise conversions.
4. Build: make each change a test with create_site_test (writtenByAi: true) with 1 to 3 versions written in the customers' own words. One test per page at a time.
5. Keep winners: get_test_results; when one is clear, set_test_status with keepWinner: true so it stays live for everyone.
6. Report: once a week, save_report with a plain summary, what is winning, what you changed and why, what is next, and the numbers (visits, conversion rate now and the week before). The owner reads it in the app.

## Make a site convert (Buy score)
The Buy score (0 to 100) says how likely a buyer is to act on a page. The MCP prompt make_it_convert runs the whole job.
- score_page runs 21 page checks (80 points: clarity, action, trust, friction, speed). judge_page adds your 3 checks (20 points): is the offer clear in 5 seconds (ai_offer), does the page speak to the customers in get_research (ai_match), is the next step obvious and safe (ai_next). Judge strictly, as a first-time buyer, on desktop and phone, and list every obvious problem you see.
- Fix the problems in order of points lost, score again with a version label ("after new headline"), and repeat until 95 or 3 rounds bring no gain. Never change the live site without the owner's yes: use a preview, a test or a draft.
- Never trade quality for clicks: judge_page also takes quality (0-10). Keep a change only if the Buy score rises and quality does not drop. Fake urgency, clutter and spammy pop-ups are flagged and do not count as wins.
- New site designs: score_page with draftId, so the owner sees the new design's score next to the live page.
- Real visitors decide: put the changes that raised the score most into A/B tests. get_score_check compares the scores with real conversion rates; the goal is 95% agreement.

## Jobs and the live work tree
The owner can ask for work in the app (like "make these lines plain"). list_jobs shows it with a todo; the prompt do_my_jobs runs it.
- Report every step with job_step (running, then done with what you found). Nest sources under their step. The owner watches the tree live from any page.
- For your own multi-step work (research, tests, new designs), start_job first so the owner can watch it too, and finish_job at the end.
- Plain words: check_plain_words finds AI-sounding lines, jargon and long sentences. Rewrite in the words of the customers (get_research, reviews, forums), same meaning, no new claims, check again, then submit_rewrites with selectors.

## Test users (you play the customers)
The MCP prompt run_test_users runs the whole job. You need a browser tool.
- get_test_personas gives personas from the customer research. start_sim_run gives an address with ?cn_sim=<run id>: open it at the persona's screen size. Those visits are recorded (heatmaps and recordings in the Test users view) and never count in real stats or A/B tests.
- Act like the persona: their patience, worries and words. No devtools, no page code, fake details only, stop at payment. Give up where they would.
- report_sim_run right after each visit: steps, thoughts, outcome, where stuck with why and the fix, quotes, wouldBuy 0-10. list_sim_runs shows the stuck points, biggest first.

## Ids and safety
- Keep existing ids (questions, options, variants, results) when you edit, or the test data is lost.
- New funnels start as drafts. publish_funnel sets them live. Never delete a funnel unless the owner asked.

## REST API
Every MCP tool is also POST /api/v1/<tool_name> with a JSON body of the same arguments and the header "Authorization: Bearer <key>". Read-only tools also answer GET with query parameters.
Public (no key, used by quiz pages and custom front ends): GET /api/public/funnels/<slug>, POST /api/public/events, POST /api/public/leads.

## Connect
MCP server (Streamable HTTP): https://convertnow.westwardconsulting.ai/api/mcp
  claude mcp add --transport http convertnow https://convertnow.westwardconsulting.ai/api/mcp --header "Authorization: Bearer <your key>"
REST: POST https://convertnow.westwardconsulting.ai/api/v1/<tool_name> with "Authorization: Bearer <your key>".

## Tools
- get_platform_guide: Read this first. Explains the funnel model, how A/B tests and the self-improving loop work, and how to write questions that convert.
- list_templates: Ready-made funnels (qualify leads, recommend a product, score check). Use one as the base for create_funnel.
- list_funnels: All quiz funnels in this workspace with their status and public link.
- get_funnel: The full funnel: intro, questions with every version, contact step, results and autopilot settings.
- create_funnel: Create a quiz funnel from a full spec, or from a template key (see list_templates). Give each question 2 versions (variants) so testing starts at once. Options carry points per result id; the result with the most points is shown. Starts as a draft unless status is "live".
- update_funnel: Change part of a funnel. Top-level keys you send replace the current ones (objects like intro/capture/autopilot are merged). To change questions, send the whole questions array. Keep existing variant ids so test data is kept.
- replace_funnel: Save a complete new spec for an existing funnel (same link). Use get_funnel first and edit it.
- publish_funnel: Set a funnel live (visitors can take it) or back to draft (the link shows a closed page).
- duplicate_funnel: Copy a funnel as a new draft with a new link.
- delete_funnel: Take a funnel down and hide it. Its leads are kept. Only do this when the owner asked for it.
- get_results: Views, starts, finishes and leads, plus every question version with how many saw it, answered it and kept going to the end, and its chance to be best. Also runs the autopilot check, so finished tests pick their winner.
- get_optimization_tasks: Questions that need a new version: tests that finished (write a challenger to beat the winner) and questions with only one version. Each task shows the current wording, the versions that lost and the answer options. Write a new version with add_variant.
- add_variant: Add a new wording for a question. It joins the A/B test at once and gets an even share of visitors. Max 4 live versions per question.
- retire_variant: Stop showing one version of a question. Its numbers are kept.
- list_leads: People who left their contact details, newest first, with their answers and result.
- get_embed_code: The public link, a snippet to put the quiz on any website, a popup snippet, and the headless endpoints for a fully custom front end.
- get_setup_steps: Start here on a new account, and call it again after each stage. It says what to do next: find the owner's sites (propose_sites), wait while the owner picks, then for each picked site: install the script, research customers and competitors, and build a full new website design draft (save_site_draft). The owner watches the results fill in live.
- propose_sites: Send the websites you found for this owner (from their projects, configs and what they told you). They show up as cards in ConvertNow and the owner picks which ones to use.
- save_site_draft: Save a full new website design you built for a site, so the owner sees it in ConvertNow: a name, a plain summary of what changed and why, the pages it covers, what research it is based on, a previewUrl (a live preview deploy) and/or html (the new home page as one self-contained file, inline CSS, under 700 KB). Give draftId to update an existing draft. Later it can run as an A/B test against the live site (create_site_test with a redirect change to the previewUrl).
- list_site_drafts: The new website design drafts saved for a site, newest first (without the html).
- list_sites: Every website being tracked, with its domains, whether the script has been seen, running tests and 7-day numbers.
- create_site: Start tracking a website. Returns the site id and the script to paste at the top of the <head> of every page.
- get_site_overview: Visits, visitors, conversion rate, bounce rate, goal counts, a daily series, and top sources, countries, cities, companies, devices, first pages and campaigns.
- get_page_report: Every page: views, time, how far people scroll, entries, exits, exit rate, rage clicks, dead clicks and script errors.
- get_exit_tree: A tree of the paths visitors take, page by page. Each node has sessions, how many left the site there, and how many converted after it.
- get_leave_report: Why visits end without a conversion: how they left (script error, rage clicks, gave up on a form, left at once, left without reading, read and left), the pages they leave from most, a step funnel to the goal with the drop at each step and where those people went instead, a page flow (top pages at steps 1 to 4 and the moves between them), and leave rates by device, source, country and new or returning. Give steps (page paths, "/blog/*" works) to measure your own funnel.
- get_friction: Elements with rage clicks (4+ fast clicks in one spot) or dead clicks (nothing happened), forms people give up on and the field where they stop, and script errors.
- list_sessions: Recent visits with pages, time, source, device, place, company, goals and friction. Filter to find visits to watch. A visit with replay: true has a recording in the app.
- create_goal: Say what counts as a conversion. type "page": a page path is opened (match, * allowed). "click": an element is clicked (match = CSS selector). "submit": a form is sent (match = CSS selector, empty = any). "event": the site calls convertnow("goal", "<goal id>"). value: optional money value per conversion.
- create_site_test: A/B test (kind "test": the original plus your versions, visitors split evenly) or personalization (kind "personalize": always show the changes to one audience). Changes edit the live page in the browser: text, html, attr, hide, css, move, redirect, popup. Audience can target countries, regions, cities, devices, sources, companies, new or returning visitors and UTM values. Starts running at once unless start is false.
- add_test_arm: Add one more version to a page test. It gets an even share of new visitors. Max 6 live versions.
- set_test_status: status: running, paused or done. keepWinner: true turns the winning version into a personalization, so every visitor in the audience sees it.
- get_test_results: Each version: visitors, conversions, rate, lift over the original and chance to be best, plus progress to a decision. Also runs the autopilot check, so finished tests pick their winner.
- get_site_tasks: A ranked list of what loses visitors, with the evidence: pages people leave, rage and dead clicks, forms people give up on, errors, missing goals, finished tests that need a challenger. Each task has an idea for a test. Make the test with create_site_test.
- get_snippet: The script to paste at the top of the <head> of every page of the site.
- score_page: Scores one page 0 to 100: would a buyer act here? Runs 21 page checks now (clarity, action, trust, friction, speed; 80 points) and leaves 3 checks (20 points) for you: then open the page like a first-time buyer (on a phone too), read get_research, and call judge_page. Returns every check with what was found and how to fix it, and the problems ranked by points lost. url can be a path on the site ("/pricing"), a full URL, or a draft preview URL. Give version a label like "before" or "after new headline".
- judge_page: After score_page: score the 3 AI checks as a strict first-time buyer would (ai_offer max 8: in 5 seconds a buyer knows what it is, who it is for and why it beats the other options; ai_match max 6: it says what the buyers in get_research want to see and hear, in their words; ai_next max 6: the next step is obvious and feels safe, with what happens after the click, the cost and the time), each with why and the exact fix, plus quality (0-10: does the site still look premium and trustworthy; fake urgency, clutter and spammy pop-ups lower it), and add obvious problems the page checks miss (broken parts, phone layout, slow parts, confusing words). The owner sees them in the app.
- list_scores: Past Buy scores for a site, newest first, with versions, so you can see what each change did.
- get_score_check: Compares AI-judged Buy scores with the real conversion rate of each page (visits that landed there and reached a goal, last 30 days, pages with 30+ visits). Agreement = how often a higher score means more real sales; the goal is 95. If it is low, look at the pages where they disagree and tell the owner which checks seem wrong.
- check_plain_words: Finds lines that sound machine-written (unlock, seamless, elevate, "not just X, it is Y"...), jargon visitors do not use (solutions, leverage, scalable...) and sentences too long to read at a glance. Give a page address; or the page address plus the lines you read in your browser (for pages built by scripts); or only your own new lines, to check them before you submit (not saved). Returns a plain score 0-100 and each flagged line with why.
- run_nightly_check: Runs the check ConvertNow does every night: picks test winners, scores the top pages, checks the words, and refreshes the "nightly" job of potholes. Call it at the start of a daily run if the last check (get_last_night) is older than 20 hours, then do the nightly job from list_jobs.
- get_last_night: The last nightly check of a site: visitors and buyers this week and the week before, the top leak, page scores, how many potholes wait in the nightly job.
- list_jobs: Jobs the owner asked for in the app (like "make these lines plain" or a request typed in "Tell your AI"), newest first, with what to do. Do every waiting job. Report each step with job_step so the owner sees the work tree live.
- start_job: For any work with several steps (research, a test, a new design): start a job, then report each step with job_step and end with finish_job. The owner sees it live as a tree from any page of the app.
- job_step: Adds or updates one step in the work tree of a job. Send a step as "running" when you start it and again as "done" (with what you found in detail) when it ends. Use parent to nest steps, like each source under "Research". Keep titles plain: "Reading 14 reviews on Trustpilot".
- submit_rewrites: For a plain_words job: each old line, your new line, why, the CSS selector of that element on the live page, and the sources of the words. Check your lines with check_plain_words first. The owner approves each one; approved lines start as an A/B test against the old words.
- finish_job: Ends a job you started with start_job, with a one or two sentence summary. failed: true if it could not be done (say why in the summary).
- get_test_personas: Personas to play as test users, built from the customer research (who they are, what they came to do, device, patience, worries, their words), and the site goals. Edit them freely before start_sim_run.
- start_sim_run: Starts one test user visit. Returns a run id, the address to open (with ?cn_sim=<run id>, so the visit is recorded and kept out of real stats and A/B tests) and the rules. Then open the address in your own browser at the persona's screen size and act as that persona, like a real person. If you have no browser tool, tell the owner to add one to their AI first. Never pay or send real personal data.
- report_sim_run: After a test user visit: every step (page, what the persona did, what they thought, ok or not), the outcome (done, stuck or gave_up), where it went wrong with why and the fix, short quotes in the persona's words, and wouldBuy (0-10). Be honest: a real person with this patience would leave where you would hesitate. The owner sees it in the Test users tab with the recording.
- list_sim_runs: Past test user runs, newest first, with the steps, where they got stuck, and the recorded visits; plus a summary: runs, finished, stuck, average wouldBuy, and stuck points grouped by page, biggest first. Fix the top stuck point first.
- get_research: What has been learned about this site's customers (segments, what they want and fear, the words they use, sources) and its competitors (offer, price, strengths, weaknesses, traffic estimates with their basis, ideas to copy or beat). Empty until save_research is called.
- save_research: Save customer research (audience replaces the old one) and competitors (matched by domain; a new entry replaces the old one for that domain). Put the source of each fact in sources or traffic.basis. Label traffic numbers as estimates and say which public signals they come from. The owner sees all of it in the app under AI work.
- estimate_competitor_traffic: Estimates a website's monthly visits (low, likely, high) from its public top-sites rank and the trend over the last month, reads its likely traffic sources from its ad tags and content, and lists its biggest page sections. It is an estimate, not measured data: always show the basis with the numbers. Save the result in the competitor's traffic field with save_research.
- study_competitor: Reads a public page of any website (default the home page) and its sitemap: title, headlines, calls to action, prices, proof, offers (trials, guarantees, discounts), ad and analytics tools it runs (a sign of paid traffic), and its page sections with page counts. Use it to see what a competitor promises and how it sells.
- save_report: Save the weekly report the owner reads in the app: a plain summary, what is winning, what you changed and why, what is next, and the numbers (visits, conversion rate now and the week before). Call once a week.
- list_reports: The latest weekly reports for the site, newest first. Read the last one before you plan, so you do not repeat what lost.