accept_exclusion_suggestion
ChatGPTAccept one of pagent's suggestions (get_exclusion_suggestions): the subject test is kept apart from the suggested tests, joining the exclusion one of them is already in or creating a new one with an equal split per visitor. Tests that could not be moved (already in another exclusion, or running and asked to join an existing one) come back in skipped — tell the user about them, they still overlap with the subject. Confirm with the user first; every member will take longer to finish.
activate_page
ChatGPTActivate a registered page so the platform crawls and analyses it, making it ready for tests. Use the page id returned by create_page. Activation starts background work (crawl, screenshot); it can take a while and does not need polling.
add_keywords
ChatGPTAdd one or more keywords to the workspace. Optionally link them all to specific pages by path. Use get_keywords to see what already exists first so you do not duplicate.
add_list_entries
ChatGPTAdd exact values or regular expressions to a reusable trigger list in one batch. Existing entries are preserved. If an active trigger references the list, the new entries can immediately change which visitors match running tests.
add_test_to_exclusion_group
ChatGPTAdd a test that has not started to an existing exclusion. It takes its share of visitors the moment it starts; visitors already in another member stay where they are. A test is in one exclusion at most, and a running test cannot join.
archive_goal
ChatGPTArchive a conversion goal so it is no longer tracked. Use get_goals to find the id. This affects future measurement only; running tests keep their existing goals.
archive_hypothesis
ChatGPTArchive a hypothesis the user no longer wants to see. Archiving hides noise and never stops or changes linked tests; an archived hypothesis can be unarchived in the hypothesis workspace. Prefer retire_hypothesis when an answered idea should remain visible as evidence, or park_hypothesis when it is only postponed.
archive_trigger
ChatGPTArchive a trigger so it is no longer included in the SDK payload. Existing records and test history are preserved, but a running test that uses the trigger can stop matching visitors immediately.
attach_hypothesis_asset
ChatGPTAttach supporting evidence to a hypothesis. Accepts PNG, JPEG, GIF, WebP, PDF, TXT, and Markdown files. Each file may be up to 10 MB, and each hypothesis may have up to eight attachments. TXT and Markdown attachments are readable reference material for the agent. Files over 256KB must not be sent inline: call prepare_hypothesis_asset_upload, PUT the file to the upload URL it returns, then call this with the uploadToken. Only send contentBase64 for a genuinely small file.
attach_test_goal
ChatGPTMake a test measure an existing conversion goal, as a secondary goal by default. Use get_goals (optionally with testId) to find goal ids and see what the test already measures, and create_click_goal / create_event_goal / create_page_view_goal to create the goal first. Attaching to a draft test takes effect at launch; attaching to a running test republishes its tracking and counts from now on for click and page-view goals (event goals count retroactively). Never change the primary metric unless the user asks for that explicitly.
capture_hypothesis
ChatGPTCapture a new hypothesis (a test idea or brief) for either a registered page or an existing trigger. Use a trigger when the test needs CSS, URL, JSON-LD, list, or JavaScript targeting; otherwise provide the page. This saves immediately. Sharing an idea or answering a clarifying question is not by itself a request to save. If save intent is unclear, ask whether to save or keep brainstorming and wait for the user's answer before calling this tool. Respect requests to brainstorm, discuss without saving, or confirm before saving across clarifying turns. An explicit create/save request is sufficient unless the user has asked for confirmation before saving: then present the proposed idea and wait for acceptance of your save question, unless they explicitly waive confirmation. Acceptance of your save offer is sufficient; do not ask again for consent already given. For improvements to a saved hypothesis the user is already working on, use update_hypothesis with its resolved id instead of creating another hypothesis. New-creation consent does not add a confirmation step to those updates. If the user explicitly asks to discuss without saving or editing, keep proposed revisions in chat until they ask to apply them. New hypotheses have no priority by default. Only use update_hypothesis to assign one if the user explicitly asks for a priority or asks you to prioritize the ideas. Capture one concrete, single-change idea per call. Clarify vague ideas first, and split independent changes into separate hypotheses. Provide exactly one of page or triggerId, and the hypothesis text. Exact page targeting is the default; never substitute a covering wildcard without confirmation. A trigger must be active and have an example URL. A hypothesis carries no audience: pick the audience when the test is built with create_test_from_hypothesis. Visitor conditions such as utm_* parameters, referrer, device, or country belong in an audience, not in a trigger or in the text: an idea for one visitor group, or with content per group (a hero per ad campaign), is one hypothesis per group, each written as the change those visitors see and never as a check like "only when utm_campaign=sport". This captures an editable idea; it does not create or launch a test. Write the text with the hypothesis template when you can support each part: "Based on [evidence] we think [theory]. We believe we can [outcome] by changing [change] for [visitors]. We know this is supported if they [new behaviour] and we see [effect on metrics]." Name visitors in words; eligibility stays in the audience. The result includes the five-pillar evaluation of the saved hypothesis (as evaluate_hypothesis reports it), so there is no need to call evaluate_hypothesis afterwards. Act on its nextStep in the same reply: when pillars are missing, look them up in pagent's data as it describes before asking the user, rather than moving on.
compare_tests
ChatGPTCompare tests against each other: rank them by one stated measure, with each test's uplift range, and summarise them as a program. Use this to answer "which of my tests is winning", "compare these tests", or how the testing program is doing (win rate per quarter, average uplift across tests). Name the tests in testIds (2-20, each by id or by its number as shown in the dashboard, e.g. 7), or pass all: true for every started test on the website (optionally since a date). Measures to rank by: - uplift: relative lift of the variation over control. - probability: chance the variation beats control. Only Bayesian tests have it; frequentist tests (statisticsEngine FREQUENTIST) get a null value here and are listed after the ranked tests, so rank them by uplift instead or say they use p-values. - conversion_rate: the variation's observed conversion rate. Tests are returned ranked best-first by that measure. A number naming more than one test is reported under ambiguous rather than guessed at; ask which was meant and pass that test's id. Tests without results yet are listed last with a null value and hasResults=false; say they cannot be compared yet rather than ranking them. A null value with hasResults=true means the measure does not exist for that test's engine. Always state which measure you ranked by. Each test also carries its result, dates, quarter, visitors, uplift with a 95% range, and a shrunk uplift: the winner's-curse correction. A test that won was picked because its observed uplift was high, so its raw uplift overstates what shipping it adds; the shrunk uplift pulls it towards the average of the compared tests in proportion to how noisy it is. Use the shrunk uplift for revenue projections of shipped winners. Each test carries plannedDays, the runtime it was set up for, next to runtimeDays. program sums up the compared tests: totals, counts, win rate and learning rate per quarter (learning rate: the share of finished tests that gave a clear answer, a win or a clean loss; judge a program by it more than by its win rate), and the pooled average uplift across tests (random-effects meta-analysis) with its 95% range. Uplifts are ratios (0.042 = +4.2%).
complete_website_onboarding
ChatGPTMark a ready website onboarded. Safe to retry with the same idempotency key.
configure_website_onboarding
ChatGPTReplace the website's selected persona set and start goal/strategy generation after analysis is ready.
continue_test_build
ChatGPTContinue building a test that was waiting for the owner's input, once every blocker is fixed, answered, or dismissed. Open suggestions do not hold it back. pagent picks up its draft where it stopped, with the owner's answers and optional instructions, and the test is ready or asks again when done. Confirm with the user first: this starts a new build.
create_audience
ChatGPTCreate an audience: a named set of targeting rules that tests and explorers can be scoped to. Use this for requests like "test this on mobile visitors from paid search" or "target France and Germany". Rules are a list joined by match (and/or). An entry is either a condition or a nested group { match, conditions }, and groups nest as deep as needed, so pairwise logic is one audience: for "(google AND cpc) OR (bing AND cpc)" send match: or with one and-group per pair, each holding a utm_source condition and a utm_medium condition. To match any of several values of one field, use the member_of operator with a comma-separated value and valueKind csv, e.g. country member_of "FR,DE". Do not split a request into several audiences when one tree expresses it. Creating an audience does not put it on a page. Use set_page_audiences for that, or allPages: true to apply it everywhere.
create_click_goal
ChatGPTCreate a click conversion goal: a click on the element matched by a CSS selector counts as a conversion. Provide the selector, a name, and where the goal counts: either a page URL (scopes it to that exact path) or a pagePattern (exact path, glob like '/products/', or '' for every page). The goal is created at workspace level; call attach_test_goal to make a test measure it. Use get_goals first to avoid duplicates (an existing goal with the same selector and scope is returned instead of duplicated). When a name is given, suggest appending ', [data-pagent-track="<name>"]' to the selector so equivalent new or rebuilt controls in variations can count toward the same goal. Escape the name as a CSS attribute string. One DOM element carries one goal id: a selector overlapping an existing goal's element does not count for a second goal, even if the selector text differs (for example div.btn-cart versus an existing add-to-cart goal). Widen the existing goal with update_click_goal instead of creating an overlapping goal. Goals created here are workspace goals: tracked on every matching page from the moment they are published, whether or not a test measures them yet, and only archived by a person. Rules the user should hear: click goals are not retroactive (they count from publication), and a goal only yields a comparable rate when the element exists in control as well as in the variation. A glob or '**' scope is right for elements that live on other pages than the test's page (add-to-cart on product pages measured by a home-page test); the SDK then counts the click wherever the element exists and does not report the goal as missing on pages without it. For elements a variation injects itself, tell the user it is engagement diagnostics, not a rate. For clicks that also push a dataLayer event, prefer define_event + create_event_goal, which is retroactive.
create_event_goal
ChatGPTCreate an event conversion goal over an event label the site emits (a dataLayer / GTM event, a window CustomEvent, or a pagent.emit call). Event goals are computed at query time, so they count retroactively over everything already recorded and work in both test arms. Provide the label; use get_events first to see which labels exist and how often they fire. If the label is not observed yet, create its definition with define_event so the SDK starts observing it. The goal is created at workspace level; call attach_test_goal to make a test measure it.
create_exclusion_group
ChatGPTKeep two or more tests apart: create an exclusion so a visitor only ever sees one of them. Use it when tests change the same page, aim at the same goal, or share many visitors, and never as a default: every member gets a share of the visitors and takes correspondingly longer to finish. Defaults are an equal split per visitor; name, description, scope and mode are optional. Tests already in an exclusion cannot be added; use add_test_to_exclusion_group to join an existing one instead. A running test can be a member only if it is already in the exclusion; it is never moved.
create_follow_up_hypothesis
ChatGPTCreate a follow-up hypothesis linked to an existing hypothesis, recording whether it follows up on, pivots from, or narrows the source idea. Anchor it with fromHypothesisId, or with fromTestId when a finished test prompted the idea. A test must be finished before it can anchor a follow-up. Following up from an archived or retired hypothesis is allowed. The new hypothesis inherits the source's page or trigger targeting unless page is provided. This does not create a test. The result includes the five-pillar evaluation of the saved hypothesis (as evaluate_hypothesis reports it), so there is no need to call evaluate_hypothesis afterwards. Act on its nextStep in the same reply: when pillars are missing, look them up in pagent's data as it describes before asking the user, rather than moving on.
create_guideline
ChatGPTCreate a brand or content guideline the AI must follow when generating variations, e.g. "Never mention discounts", "Always write CTAs in sentence case", "Use only lifestyle imagery". Phrase the content as a clear instruction. Pick the role for the step the rule constrains (wording rules → COPYWRITER, imagery → GRAPHICS_DESIGNER, layout → ARCHITECT). Guidelines apply to all future variation generation; use read_product_area with area "guidelines" first to check for an overlapping existing rule. While knowledge docs are the website's main context system, use create_knowledge_section instead.
create_knowledge_section
ChatGPTSave a rule or fact to the website's knowledge docs, which the AI reads whenever it builds tests. Use it when the user asks you to remember something about their website or business for future tests, e.g. "remember that our coupon is SAVE20", "never mention free shipping", "our brand voice is informal". State the exact values in the text, as the AI will use it as written. Call get_knowledge first: when a section already covers the topic, change it with update_knowledge_section instead of adding a duplicate. If get_knowledge says the docs are not editable yet, tell the user what its note says instead of calling this. Available only while knowledge docs are the website's main context system; otherwise use create_guideline.
create_list
ChatGPTCreate an empty reusable trigger list. Add exact values or regexes with add_list_entries. Names must be unique within the workspace.
create_page
ChatGPTRegister a Page through the same authenticated service used by the dashboard. Omit targeting for exact matching of the literal page path. Use targeting.kind="glob" only when the user explicitly requests a multi-page wildcard such as /products/*. Wildcard Pages require a matching exampleUrl and explicit user confirmation through wildcardConfirmed=true. Never add a leading wildcard to an exact path. The deprecated isGlob, exampleUrl, and wildcardConfirmed fields remain accepted for compatibility. Activate newly created Pages with activate_page before Pagent analyses them.
create_page_view_goal
ChatGPTCreate a page-view conversion goal: a visit to a specific page counts as a conversion. Provide a short name (tag) and the page path. Use get_goals first to avoid duplicating an existing goal. For rule- or property-based goals, direct the user to the goals UI.
create_persona
ChatGPTCreate a persona: a described audience segment the agent optimises for. Use this when the user wants to add a new persona and has given its details. Provide a name plus the demographic, behaviours, psychographic, goals, challenges, and industry. Set selected to make it active immediately. Ask for any missing detail rather than inventing it.
create_programmatic_goal
ChatGPTDeprecated: prefer an event goal (get_events, define_event when the label is not observed yet, then create_event_goal); use this only when the user explicitly asks for a programmatic goal or the site already sends direct conversions. Existing programmatic goals keep working. Creates a programmatic conversion goal: a direct conversion the site sends through the pagent SDK (window._pgnt.push({ kind: "conversion", ... })) counts. Provide the exact event tag. Use get_goals first to avoid duplicating an existing goal; if a goal with the same tag already exists, this returns it instead of creating a duplicate. Property-filtered goals (matching on event properties) stay in the goals UI.
create_pull_request
ChatGPTTurn a completed test into a pull request on the customer's connected GitHub repository. pagent implements the test's variation in the source code inside an isolated environment, runs the repository's recorded checks, and opens a pull request for the team to review. Nothing is merged automatically and the website does not change until the team merges. Recommend this only for a test that won. Any stopped test qualifies though: implementing a variation that did not win is the user's decision, so do it when they ask, and say plainly that the test did not win; never suggest it yourself for such a test. A repository must be connected and prepared under Integrations, GitHub, and one open pull request per test is allowed. The result reports where it stands; use get_pull_request to follow progress. When the website has several prepared repositories, pass repository (owner/name) to choose. When the test has several variations, pass variation to choose; without it the best-performing variation is implemented.
create_strategy
ChatGPTCreate a new optimisation strategy. Provide a name and a description of the approach. The new strategy is not activated automatically; use select_strategy to make it active.
create_test_from_hypothesis
ChatGPTTurn a specific hypothesis into a test. This starts the build and returns immediately while the variation copy and relevant images are generated in the background. The test is not made live: it remains a building or idle draft until the user takes another action. After this returns, tell the user the test is building, offer private review as an optional next step, and do not poll for results. Never call prepare_review unless the user explicitly asks for it or accepts the offer. When the user gave or approved an offer or other fact the variation should show (a coupon code, a discount, a price), pass it in confirmedFacts with the exact values: it is added to the hypothesis notes, which the build reads, so the build does not stop to ask for it again. When you have more context for the build than the hypothesis states (exact copy, which elements to change or leave alone, layout, styling or implementation constraints, findings from the site's code), pass it in additionalInstructions. It is stored on this test only, not on the hypothesis, and the build reads it alongside the hypothesis; be as detailed as helps. When the user agreed which goal decides the test, pass it as decidingGoalId. The test then starts with that goal as its only primary goal; without it, a new test inherits the primary goals of earlier tests on the page, which may measure something else entirely. A goal you picked yourself is not agreed, however well it fits: while the deciding goal is still open, omit decidingGoalId, build anyway, and ask the user which goal should decide the test. Pass only a goal that measures what the hypothesis expects to change. When none does yet (newsletter signups but only purchase goals), omit decidingGoalId and tell the user that goal still has to be set up; never substitute a goal that measures something else. To prevent duplicate work, this returns the existing test when the hypothesis already has one that is still open; a hypothesis whose tests have all finished can be built again. The capture page comes from the hypothesis's trigger or page example URL; when neither provides one, supply url. A hypothesis on every page (the match-all page "**") without its own trigger needs triggerId: the trigger decides which pages the test runs on, and its first example URL is captured. The audience belongs to the test, not the hypothesis: pass audience to target one, omit it for all visitors. When the hypothesis is for a visitor group (a campaign, channel, device, or country), pass that group's audience; pagent then shows the variation only to those visitors, so the variation itself needs no eligibility check. Leave out every optional input that does not apply. Never fill one with a guess or with an id of another kind.
create_trigger
ChatGPTCreate a CSS, URL, JSON-LD, mixed, or JS trigger with at least one example URL. Non-JS triggers use one flat AND/OR rule. Use list_lists before referencing a list id. This creates targeting only; it does not create a hypothesis or test.
create_variation
ChatGPTAdd a new variation with your JavaScript to a group (arm) of a draft test. Variations are immutable: the new variation becomes the group's current one, the one it replaces stays in the group's history, and nothing is edited in place. Use it for every change to a group's code. Give the test by id or by its number (e.g. 7), and the group by letter (B is the first after the control A), its exact label, or variation id. The control cannot take code. For a new arm, call create_variation_group first and pass its letter here. Each change is JavaScript the pagent SDK runs on the page as the body of a function receiving window and document, plus reverseJs that undoes it. The SDK runs it only when the website allows JavaScript execution. Style changes go through the JavaScript too, e.g. by appending a <style> element. Read a group's current changes with get_test_changes. By default the new variation holds only the changes you pass; set keepCurrentChanges to add them on top of the current variation's changes. Only works on a draft test that has not started. Check the result with start_preview.
create_variation_group
ChatGPTAdd a new variation group (an arm, such as "C") to a draft test. The group starts with an empty variation that changes nothing, and the test's traffic is split evenly across all its groups. Then call create_variation to give the group its code. Only works on a draft test that has not started. Give the test by id or by its number (e.g. 7). To change an existing group (B, C, ...), call create_variation on that group instead; most changes belong there.
create_website
ChatGPTCreate a pagent website and start its analysis workflow. Poll get_website_onboarding_status before configuring later steps.
define_event
ChatGPTDefine an event the pagent SDK should observe on the customer's site, so it is recorded under a label that event goals can use. Supports GTM-style dataLayer pushes ('data_layer': the object's event value, e.g. dataLayer.push({event: "conversation-started"})), window CustomEvents ('window_event'), and trigger matches ('trigger': the SDK records the event once per page start on which the trigger from triggerId matches, so a trigger like "cart has items" or "checkout page" becomes a goal without any site code). Confirm the exact event name and where it fires with the user before defining a listener source; the site's own code must already emit the event (an event fired only inside GTM, inside a cross-origin iframe, or as a bare gtag()/fbq() call cannot be observed). Observation starts once the definition is published and, for dataLayer, includes pushes that happened before the SDK loaded on that page. Labels the site already emits show up in get_events as OBSERVED; defining one promotes it. Then create_event_goal on the label.
delete_audience
ChatGPTDelete an audience. This also discards any draft tests scoped to it and archives its explorers, and removes it from every page it targets. It is refused while tests are running or being built on it, so stop those first.
delete_keyword
ChatGPTDelete a keyword and unlink it from any pages. Use get_keywords to find the id.
delete_list
ChatGPTDelete a trigger list. This is refused while any active trigger condition references it.
delete_persona
ChatGPTPermanently delete a persona and remove it from any audiences that reference it. This cannot be undone. Use get_personas to find the id.
delete_strategy
ChatGPTDelete a strategy. The active strategy cannot be deleted, select a different one first. Use get_strategies to find the id.
delete_trigger
ChatGPTDelete an unused trigger. This is refused if any test references it; archive referenced triggers instead.
detach_test_goal
ChatGPTStop a test from measuring one of its conversion goals. The goal itself is kept for other tests (a click goal used by no other test is archived and can be restored from the Tracking page). Refuses to remove a test's primary goal: tell the user to attach another goal as primary first.
dismiss_exclusion_suggestion
ChatGPTDismiss one of pagent's suggestions to keep tests apart. The pair is remembered and never suggested again, so only dismiss when the user has decided the tests may run alongside each other.
evaluate_hypothesis
ChatGPTCheck how completely a hypothesis is written, using Booking.com's five pillars: prior evidence, the change, the audience, the expected visitor response, and the metrics. Returns a band (weak, acceptable, excellent) and which pillars are present or missing. It judges how clearly the idea is written, not whether it is a good idea, and it never blocks capturing or testing. The pillars are read from the hypothesis text (and its notes), written with the template: "Based on [evidence] we think [theory]. We believe we can [outcome] by changing [change] for [visitors]. We know this is supported if they [new behaviour] and we see [effect on metrics]." Pass hypothesisId to check a saved hypothesis, or pass the draft text to check an idea before capturing it. With both, the draft text replaces the saved one, so you can check whether an edit would close a gap before making it. Use it before offering ideas you generated from data, and when the user asks how strong or complete a hypothesis is. capture_hypothesis, create_follow_up_hypothesis and update_hypothesis already return this evaluation for what they save, so do not call it again after them. When pillars are missing, its message says where pagent's data can fill each one: look those up before asking the user, and ask only for what the tools cannot establish. Never invent evidence or metrics to fill them. When it returns unavailable, say the evaluation can't run at the moment.
evolve_test
ChatGPTEvolve a completed test into its follow-up: the platform picks the next step for that page and audience (the next queued test, the next ready hypothesis, or a new variation built on what was learned) and creates or starts it. Use this when the user wants to iterate on a finished test ("what's next for this page", "build on the winner"). Scope: this iterates on the ONE test you name, and only on its own page and audience. It does not combine, merge, or stack winners from several tests, and there is no capability that does. If the user asks to combine winning variations from multiple tests, say that is not something this platform can do rather than offering evolve as a substitute. Only a stopped (completed) test can be evolved. The evolved (original) test keeps its status; the follow-up arrives as newTestId with its own newTestStatus. Refer to the follow-up when describing what was created or started.
explain_lifecycle
ChatGPTExplain how testing works in Pagent, grounded in this workspace. Use this when the user asks how something works rather than for data: "do I need to stop my current test to start a new one", "what is a hypothesis", "what happens in review", or "what do the test states mean". Pick the topic: - lifecycle: what the test states mean and how a test moves between them. - conflict: the one-running-test-per-page-and-audience rule and the stop-vs-queue choice. Pass page (and cohort) to ground it in what is actually running there now. - brief: what a hypothesis (brief) is and when it can still be edited. - review: how proposed changes go through review and never go live without approval. Returns guidance text plus any relevant current-state facts to weave into the answer. It never invents data.
generate_goals
ChatGPTKick off AI generation of conversion goals from a plain-language description of what the business wants visitors to do. This runs once per workspace in the background; if goal generation has already run, define goals directly with create_page_view_goal instead.
generate_personas
ChatGPTKick off AI generation of personas from the crawled site. This runs in the background and only applies while a workspace is still being set up; on an onboarded workspace, add personas manually with create_persona instead.
generate_strategies
ChatGPTKick off AI generation of strategies from the crawled site. Optionally pass suggestions to steer them. This runs in the background and only applies while a workspace is still being set up; on an onboarded workspace, add strategies manually with create_strategy instead.
get_analytics
ChatGPTRead the workspace's traffic, conversion and revenue analytics over time, and segment it. Use this for questions about the site's numbers rather than one test's statistics (use get_test_results for a test's uplift and significance). Every answer has a unit, and the unit depends on the measurement you ask for. "count" counts events: page views, conversions, sessions. "unique" counts distinct visitors per time bucket, which is what the Cockpit dashboard shows by default. "aggregate" with property "revenue" reads money. Cite the unit the response gives back, never just "views". A "unique" series cannot be added up. Its total comes back as null with additive: false, because a visitor active on three days is counted in three buckets. Quote the mean per bucket or the per-bucket numbers instead of inventing a total. For a conversion rate, ask for both metrics with measurement "count" and divide the totals. Segment with filters. Within one filter the values are ORed, and separate filters are ANDed, so two filters on the same dimension would ask for an impossible intersection and are rejected. Name tests, arms, audiences, pages and goals the way a person does, not by id: a test by its dashboard number, an arm as "control" or a letter, the rest by name, path or tag. For referrer, city, country, browser, language and the five UTMs, call get_analytics_filters to see which values the site actually has. "mobile" takes "true" or "false". Two things to say out loud when they apply. If coverage.collectsOutsideTests is false, these numbers only cover pages with a running test, and the workspace can widen that in Settings then Setup, "Keep collecting analytics when no test is running". On a "unique" series, visitors who did not consent are deduplicated by IP and browser within a rotating daily window rather than by a cookie, so people sharing a connection merge together and the same person recurs across days. Pick the range from the user's words and today's date: "last week" = 1w, "this month" = 1m, a quarter = custom start and end dates. The first and last bucket of a preset range are partial. A "page" filter selects sessions on that page by URL path, whether or not a test was running there; a page with a pattern such as /products/** covers every path it matches. If a metric comes back in errors, say what it says instead of guessing.
get_analytics_filters
ChatGPTList the values a segmentation dimension actually has in this workspace, so get_analytics filters on something real instead of a guess. Returns each value with how many sessions carried it, busiest first. Covers the dimensions whose values only exist in the traffic itself: referrer, city, country, browser, language, the five UTMs, and ad_platform (google, meta, microsoft, linkedin, x or tiktok, from the click ID in the landing URL). The other dimensions need no lookup. Name a test by its dashboard number, an arm as "control" or a letter, an audience by name, a page by path and a goal by its tag, and get_analytics resolves them; "mobile" is just "true" or "false". Values are scoped to a time range, because a campaign that ran in March has no values in May. Use the same range you plan to query. Only the busiest hundred come back, so truncated: true means the tail is missing, not that the list is wrong.
get_analytics_sql_guide
ChatGPTRead how to query this website's analytics with run_analytics_sql: the pagent.* views and every column with its type and meaning, the rules every query must follow, how to count page views, visitors, conversions and revenue the way the dashboard does, worked examples, and this website's test, arm, goal and page ids. Call it once before your first run_analytics_sql in a conversation, and again only if a query fails with an unknown name. The views carry ids, not names, so look up the ids you need here instead of guessing them.
get_audience
ChatGPTLook up one audience (cohort) by name and return its description, targeting rules, personas, and how many tests and explorers use it. Use this for questions like "tell me about my Mobile audience" or when you need a cohort's details before acting on it. Provide the audience name (case-insensitive); omit it for the default audience (all visitors). If no audience matches, this returns found: false.
get_entity_link
ChatGPTGet the canonical in-app link to a specific entity you already have an id for. Use this after search_entities (or any read tool that returned an id) to hand the user a working deep link, e.g. to a test's results. - entityType: test, result, explorer, page, audience, guideline, hypothesis, review, persona, strategy, keyword, goal, trigger, or list (a reusable trigger list). - id: the entity's id. For a test or result this also accepts the test's number as shown in the dashboard, as "7" or "#7". Returns { found: true, url, label } when the entity exists in this workspace, or { found: false, message } when it does not. Link the label (or the name you already use for the entity) with the url, exactly as returned. Never construct a link yourself; always get it here so it is correct.
get_events
ChatGPTList the events this workspace knows about: every label the site has emitted or that has been defined for the pagent SDK to observe, with its source (a dataLayer / GTM push, a window event, a reported pagent.emit call, a server event, or a trigger match the SDK records itself), whether it is merely OBSERVED or DEFINED, how many times it fired in the last 30 days, and whether an event goal already exists on it. Use this before create_event_goal or define_event, and to answer "does the site send an event when X happens?".
get_exclusion_groups
ChatGPTList the workspace's exclusions (ENG-1515): each is a set of tests a visitor only ever sees one of, with every member's share of the exclusion's visitors right now and once every member runs. Use this before starting a test that might overlap with a running one, when the user asks which tests are kept apart, or to find the exclusionGroupId for add_test_to_exclusion_group / update_exclusion_group. Only started tests (running or paused) hold a share; queued and idle members take theirs when they start. locked means a member runs, so the split and scope are frozen.
get_exclusion_suggestions
ChatGPTList pagent's suggestions to keep tests apart (ENG-1515). A suggestion names a test about to start and the running or queued tests it overlaps with, with reasons: same_page (both change the same page), same_goal (judged on the same primary goal), shared_visitors (a large share of the new test's visitors also saw the other page; overlapShare is that share, 0..1). Pending suggestions wait for a human under Audience > Exclusions; resolve one with accept_exclusion_suggestion or dismiss_exclusion_suggestion. A dismissed pair is never proposed again.
get_explorer
ChatGPTLook up the Explorer for one page and audience and list the tests (rounds) it has run, newest first. An Explorer is the container that runs a sequence of tests for a given page and audience; each round shows the hypothesis its test was built from, when there is one. Provide the page (endpoint path) and, optionally, the cohort (audience) name; omit cohort for the default audience. If no Explorer exists for that page and audience, this returns found: false. Hypotheses themselves live in the workspace, not on the Explorer: use get_hypotheses to list ideas.
get_goals
ChatGPTList what "conversion" means in this workspace: the metrics (conversion goals) the agent optimises towards, plus the explorer goals used to steer hypothesis generation. Use this for questions like "what are we optimising for?", before creating, updating, archiving, or attaching a goal, and with testId to see what one test measures. Two sections are always returned. "metrics" are conversion goals with their name, description (what the goal measures, when one was written), kind (DOM = click on a selector, PAGE_VIEW, PROGRAMMATIC = pagent.track tag, EVENT = query-time event label, PROPERTY_FILTERED, FUNNEL), tag, selector, page, and how many tests use them; goals a JavaScript change provisioned for its own test are marked temporary. "explorerGoals" are the named goals that guide idea generation. With testId, "testGoals" lists the goals that test measures, flagged primary / secondary / guardrail. Archived metrics are excluded.
get_hypotheses
ChatGPTList the hypotheses (test ideas / briefs) in this workspace. Use this to answer "what ideas do I have", "show my hypotheses for the homepage", or to find a hypothesis before turning it into a test. To read an already resolved saved hypothesis before improving it, pass its hypothesisId. This reads that exact hypothesis regardless of page, trigger, outcome, linked, or derived-state list filters. It remains scoped to this workspace and excludes deleted records. Archived hypotheses still require state="archived"; otherwise they stay hidden. Use the resolved ID rather than filtering for unlinked ideas: hypotheses with tests remain editable. Each hypothesis carries a short code name (shortName, generated by pagent when it is captured) next to its full text; use the short name when referring to it, linked with the hypothesis's url. Each hypothesis is homed on a page or a trigger and has a derived state: idea (nothing built yet), testing (a linked test is open), concluded (its tests finished and the outcome is known), parked (set aside, revisit later), retired (stopped for good, kept as evidence), or archived (hidden). There is no queue or ordering; a hypothesis can be edited even after tests are linked to it, and it can have several tests as evidence. All filters are optional (omit what you do not need; an empty string means omitted): - page: substring of the page/endpoint path the hypothesis is homed on. - trigger: substring of the trigger name the hypothesis is homed on. - state: one derived state (idea, testing, concluded, parked, retired, archived). Without it, everything except archived hypotheses is returned. - outcome: PENDING, CONFIRMED, REJECTED, CONTRADICTED, or INCONCLUSIVE. - linked: true returns only hypotheses with at least one test; false returns only hypotheses without a test. Newest first.
get_keywords
ChatGPTList the keywords defined for this workspace and which pages each is linked to. Keywords describe what a page is about and steer copy generation. Use this for questions like "what keywords do we track?" or before adding, editing, or deleting one. Each entry reports the keyword text and the page paths it is attached to (empty when it is not linked to any page yet). Returns an empty list when none exist.
get_knowledge
ChatGPTFind the website's knowledge docs and sections: the rules, facts and references the AI uses when it builds tests. Use it before create_knowledge_section to check for a section that already covers the rule or fact, and before update_knowledge_section to read the section's current text and version. - query: words to look for in section titles and text, e.g. "coupon". Sections matching more words come first. Omit it to list sections in doc order. - doc: a doc id or title, to look only in that doc. - sectionId: only to read one section in full, by its id from an earlier result. Returns every doc with its section count, and the matching sections with their kind (RULE, FACT or REFERENCE), version and text. Long texts are cut short unless you ask for one section by id. A design system section (colors, typography, spacing and shape, components, UI tone) also lists its tokens as path and value when you ask for it by id; those paths are what update_knowledge_section changes. Returns unavailable when knowledge docs are not the website's main context system; guidelines hold its rules then.
get_list
ChatGPTGet one reusable trigger list and all active entries. Use list_lists to find its id.
get_live_results
ChatGPTRead how a finished test's winner is doing live, against the holdout that still sees the original page. Use this for "how is the holdout doing", "is the winner still winning now that it's live", or "what is pagent bringing us since the test ended". This is not the test's result. A finished test can keep its winning variation live through pagent (a rollout). Some visitors (holdoutPercent) are kept on the original page so the winner can still be measured. get_test_results reads the completed experiment; this reads the rollout since the test ended. Never present one as the other: say "while the test ran" for the test's result and "live, against the holdout" for this one. originalResult repeats the test's result briefly, so you can contrast the two. The comparison is the test's own analysis run on the rollout's two arms, with the same engine, goals and attribution, so a conversion counts as it did during the test. It covers the test's primary goals together since measuredSince, which is when the holdout was last set. reach counts unique visitors in each arm since the rollout started, so its numbers can be larger than the comparison's. The comparison is read once at the current sample size and decides nothing, so never call it a verdict. Use the test's engine vocabulary: a Bayesian test reports probabilityToBeatHoldout, a frequentist one reports pValue. Surface lowTraffic and srm warnings. A holdout is small by design, so lowTraffic is common: then say the live numbers are too thin to read yet instead of calling the winner better or worse. Unavailable results carry a reason: not_finished (the test has not finished), not_live (nothing is live through pagent; lastRollout says when it ended and why), no_holdout (live with no holdout, so there is nothing to compare against), no_primary_goal, measurement_unavailable (the live numbers could not be read now). Report the message instead of computing the split yourself with analytics SQL.
get_operation_guidance
ChatGPTExplain whether a requested Pagent platform operation is supported, partially supported, available only in the product UI, or planned. Use this when no available action tool fully answers a platform-operation request. Guidance is looked up on demand and respects the caller's workspace permissions. - query: the user's requested platform operation in a short phrase. Returns the exact limitation and a canonical product destination or next step when available. A permission-hidden operation returns only generic access guidance. Planned work never includes a delivery date.
get_personas
ChatGPTList the personas defined for this workspace: who the agent targets and optimises for. Use this for questions like "what personas do we have?" or before creating or editing a persona so you can reference existing ones. Each persona reports whether it is currently selected (active), plus its demographic, behaviours, goals, and challenges. Returns an empty list when none exist yet.
get_preview_results
ChatGPTRead what pagent recorded during a recorded preview session started with start_preview: whether the variation was applied, which of the test's goals fired, the errors the SDK reported (such as a change whose target was not found on the page), and the timeline of page views, clicks, conversions and events. Use it while the session records to check progress, or after stop_preview to read the results again. Report only what it returns. A goal that did not fire was not triggered during this session; it does not say the goal is broken unless you did what it tracks. If applied is false although the page was open for more than a few seconds, the website is probably missing the pagent SDK or the page is not one the test targets. The timeline holds the newest events, up to timelineLimit (0 for none); counts cover every event. Sessions expire 24 hours after they start.
get_profile
ChatGPTRead the authenticated pagent profile and this connection's immutable permission set.
get_pull_request
ChatGPTRead the pull request pagent opened for a completed test, if any: whether it is being created, open, merged, closed or failed, the GitHub link, and what pagent did (the implementation of the variation and any fixes collaborators requested by mentioning @pagent on the pull request). Use this to answer "did the PR for test 7 open", "is it merged yet", or "why did the pull request fail". Give the test by id or by its number as shown in the dashboard. Reads pagent's records only; merging happens on GitHub.
get_review
ChatGPTRead the review of a test: its status, who still needs to submit, and what is blocking it from going live. Use this when a test is in review, when start_test reports the review is incomplete, or when the user asks "why can't this test start?" or "where is the review up to?". Provide the test id. Returns found: false when the test has no review. Otherwise it reports the review status, the lead's note for reviewers, each reviewer's progress (member or guest, done or pending, mandatory or optional), a tally of the verdicts on the proposed changes, how many actionable rejections still block launch, and whether the test can start yet, plus a link to the review. Read generalFeedback for reviewers' overall comments, changeFeedback for each reviewer's verdict and comment on an individual modificationId, and annotations for comments pinned to page elements in the review extension (including their target and resolved status). These preserve the original comments, including the reasons behind rejections; verdict totals alone do not explain the requested changes. It also returns the proposed changes under review (each with its modificationId, a summary, and the before/after text), the tracking reviewers asked for as goalRequests (each a to-do: map it to a goal kind, confirm the ambiguous ones with the user, then create and attach the goal), what reviewers said about the test's setup as setupFeedback (one entry per reviewer and item: GOALS, SETTINGS, TRIGGER, or COHORT, with their comment and the actionable requests extracted from it) and the setup items the review agent escalated to a person as setupEscalations, and, when the calling user is one of the reviewers, their own submission as mySubmission. A PENDING mySubmission means the user can submit their verdict from chat with submit_review_verdict; always read the review first so the verdict covers the real change list.
get_reviewers
ChatGPTSee who would review a test before sending it to review. Returns the recommended reviewers for the test's page (the same reviewers as the last review on that page, or the workspace's configured defaults) plus the full pools of workspace members and guests the user may pick from instead. Provide the test id. ALWAYS call this before send_to_review and tell the user which reviewers would be assigned; they can accept the recommendation, pick different people from the pools, or invite an external reviewer by email. When decidingGoalSuggestion is set, pagent suggests deciding the test on that goal instead of its current one. Before sending, tell the user which goal decides the test now and which one pagent suggests, and that reviewers judge the test on the deciding goal (an approved test may start on its own). They can apply the suggestion with resolve_test_blocker, keep the current goal, or send anyway.
get_sdk_setup
ChatGPTRead the workspace's SDK install status and the exact install snippet. Use this when the user asks how to install pagent on their site, whether the SDK is set up, or why no traffic is arriving. Returns whether the SDK has reported in (integrated + integratedAt), the site's domain, and the copy-paste script snippet. Present the snippet in a fenced code block exactly as returned. Tell the user to paste it into the <head> of every page (or their shared layout/template); for framework-specific guidance (Next.js, Shopify theme, GTM), explain where a script tag belongs in that stack. After they install it, the SDK reports in on the first page load; suggest checking back or using the live page inspector to verify the tag is present.
get_strategies
ChatGPTList the optimisation strategies defined for this workspace. A strategy is the guiding approach the agent uses when generating variations. Use this for questions like "what strategies do we have?" or before creating, selecting, or editing one. Exactly one strategy is active at a time (the selected one). Each entry reports its name, description, any remarks, and whether it is selected. Returns an empty list when none exist yet.
get_test_changes
ChatGPTRead the actual changes inside a test: what each variation does differently from the control. Use this to answer "what does this test change", "what is in variation B", or "show me the copy this test is testing". Give the test by id or by its number as shown in the dashboard (e.g. 7). Returns one entry per variation (arm), each with its changes: the kind of change, a summary, and the before and after text, clipped. This reads the changes as data. It cannot see the page rendered with them applied, and never returns a screenshot: renderedPreview is always null, and seeing the result needs the pagent dashboard or the browser extension. Say that plainly rather than implying you looked at the page. Pass detailed: true to also get each change's raw payload under detail, as the SDK applies it: selectors, fingerprints, inner and outer HTML, attributes, and the JavaScript of a JS change (js, reverseJs, jsContract). Use it to read or debug what a change actually does to the page. The before-HTML is the targeted element as it was when the change was made, which for a broad selector can be most of the page; it is not the live page now. JS changes only run on a website that allows JavaScript execution, which this does not show, so do not claim a JS change is running from its detail alone. A test with many JS changes makes a large response, so read one change with modificationId, or lower changesPerVariation, when you need only part of it. Any field longer than 60k characters is cut and named in truncatedFields. A test still building has no variations yet, which is reported as an empty list, not as a missing test.
get_test_interactions
ChatGPTRead the saved cross-test report: visitor overlap, assignment diagnostics and primary-goal effects for each whole variation pair. No live analytics are run. Findings are observational and advisory: never change a verdict or claim causality from them. Secondary goals and guardrails are not assessed. Missing reports are unavailable, not evidence of no interaction. Explain limited coverage and link to the saved comparison evidence.
get_test_results
ChatGPTRead the statistical results of one test by its id. Use this to answer "is my test winning", "what is the uplift", "is it significant", or "can I stop it yet". Results exist only for tests that are RUNNING or HALTED. For any other status, or a test that has not produced an analysis yet, this returns an "unavailable" result with the reason — report that honestly instead of guessing numbers. When results are available it returns the statistics engine the test runs on, conversion rates, relative uplift, the engine's evidence and interval, a verdict, an isConclusive flag, and data-quality flags (sample-ratio mismatch and low traffic). Conclusive means the analysis recommends implement_variation or keep_control. Low traffic follows the test page reliability check: fewer than 25 total conversions or an arm with zero conversions. If isConclusive is false you MUST tell the user the result is not conclusive yet; never present an inconclusive test as a winner. Bayesian tests report probabilityToBeatControl and a credible interval; frequentist tests report pValue, the p-value the current check needs (pValueThreshold) and a confidence interval. Describe a test only in its own engine's vocabulary: never quote a chance to beat control for a frequentist test or a p-value for a Bayesian one. Always surface an SRM or low-traffic warning when present. Also surface saved interaction findings as advisory; use get_test_interactions for primary-goal evidence. Unavailable or limited interaction data is not a clean bill of health. Explaining a recommendation: use stopping and decisionThreshold, never speculate. stopping.rule names what ended or held the test (null while it continues): probability_threshold or significance (the evidence crossed the winning or the losing bar), expected_loss_threshold (expected loss confirmed it), practical_equivalence (the effect is too small to matter, so inconclusive even with a high chance to beat control), max_duration (the maximum runtime ran out and the final evidence decides: a win at or above the bar, a loss past the losing bar, otherwise inconclusive), max_duration_insufficient_data (the runtime ran out before the minimum data or duration was met). stopping.reason is the engine's own wording; quote it. For Bayesian tests decisionThreshold.effective is the chance to beat control this check needed for the reported variation. It is stricter than the configured threshold in a test with several variations: the configured error budget (1 minus the threshold) is split evenly across decisionThreshold.comparisons, so 95% with two variations needs 97.5% per comparison. When effective is above perComparison, the deprecated sequential correction raised it for this check. A null field was not recorded for this result (older results): say it is unavailable, never fill it in from a default or the website's current settings. recordedResult.result is the test's final recorded result. These are the results while the test ran. When liveRollout is set, the winner is still live through pagent against a holdout: for how it does now, call get_live_results, and keep the two apart. statisticalResult is pagent's own result and userResult is one the user set by hand, which wins; when they differ, say which is which. A result with resultDecidedBy null was recorded before pagent tracked who decided: report it, and say the decider is unknown. Each goal on its own: results also carry goalResults, a compact reading of every conversion goal of the test with its role (primary, secondary or guardrail). Pass goal (a goal's name or goalId) to read one goal in full, for questions like "how did Completed purchase do?" or "did any guardrail get worse?". Only the primary goals together decide the test: a single goal's result, a guardrail's included, is informational and never a verdict to ship or stop on, so say that when you report one. Single-goal results are read once at the current sample size (fixed horizon) and are not adjusted for checking the test repeatedly. Use the same engine vocabulary for them. When lowerIsBetter is true, say that …
get_tests
ChatGPTList the tests (experiments) in this workspace, newest first. Use this to answer "what tests do I have", "show me my running/draft tests", or to find a test before reading its results. All filters are optional: - bucket: dashboard category (all, running, queued, winners, decisions, failed, inconclusive, archived). Running includes paused tests; winners are stopped successful tests; decisions includes tests in review and running tests with an implement_variation or keep_control recommendation. Prefer this for dashboard categories. - Archived tests were superseded and are kept for reference only. They are left out unless bucket is archived; they keep their status but cannot be started, queued or resumed until a person unarchives them. - status: only tests in this lifecycle state (RUNNING, HALTED, REVIEW, QUEUED, IDLE, PAUSED, CREATING, ERROR, WAITING). - bucket and status, when both supplied, must both match. - page: substring of the page/endpoint path the test runs on. - audience: substring of the audience/cohort name. - query: free text matched against the test's hypothesis, page, and url. - take / skip: pagination (default 10, max 50). Returns a structured list. Cite each test's label and status when you answer; never invent a test that is not in the list. Each test carries ground truth about what is true of it right now. Use it instead of inferring: - result: recorded outcome (PENDING, SUCCESS, LOSS, STOPPED_LOSING, INCONCLUSIVE, ERROR, ABORTED), or null when unset. Use it to distinguish stopped winners from other stopped tests. STOPPED_LOSING is a one-sided test pagent stopped because the variation was losing: it protected the website but is not a result to learn from. ERROR and ABORTED mean something went wrong, not that the variation lost. - statusLabel: the status in words. Use this wording. HALTED is "stopped", which is not the same as "paused". - allowedNextActions: the lifecycle actions that would actually succeed on that test. Do not offer an action that is not listed there. - progress and errorReason: while a test is CREATING, progress shows the build is still moving; if it ended in ERROR, errorReason says why. If a build failed and errorReason is empty, say the reason was not recorded rather than guessing a cause. - blockers: a BLOCKED test ("needs input") kept its draft and waits for the owner. Each item says what is missing and why, and evidence says what the build observed (e.g. which browser check failed); relay that evidence instead of calling the blocker unspecific. Open items need a fix, an answer, or a dismissal (resolve_test_blocker) before continue_test_build. - suggestions: setup pagent recommends after a build, such as a primary goal for a test that has none. Optional: the test works without them and nothing needs continuing. Apply or dismiss with resolve_test_blocker, or set it up another way.
get_trigger
ChatGPTGet one trigger's complete rule, list references, code, and example URLs. Use list_triggers to find its id.
get_website_context
ChatGPTRead setup and test-policy context for one pagent website before operating on it.
get_website_onboarding_status
ChatGPTDerive the current onboarding state from the website, its generated records, and workflows. No separate onboarding-attempt state is stored.
list_audiences
ChatGPTList the workspace's audiences with their targeting rules, the pages they target, and how many tests and explorers use each. Use this to answer "what audiences do I have", "which audiences are on the pricing page", or "where is nothing running yet", and to find an audience's name before acting on it. Every visitor is also covered by the default "all visitors" set, which is not an audience and is not listed here. Use get_audience for one audience in full.
list_lists
ChatGPTList reusable trigger value/regex lists in this workspace. Use this before creating or editing a trigger with in_list or not_in_list.
list_organisation_members
ChatGPTList an organisation's owner, active members, and pending invitations.
list_organisations
ChatGPTList the organisations this connection may access, including the caller's current role and website count.
list_profile_connections
ChatGPTList active and revoked MCP connections owned by this pagent profile.
list_profile_invitations
ChatGPTList pending organisation invitations sent to the authenticated user's email address.
list_triggers
ChatGPTList trigger definitions in this workspace, including their example URLs and test usage. Archived triggers are omitted unless requested.
list_websites
ChatGPTList or search pagent websites available to this connection. Use the returned agentId on every website-scoped tool call.
park_hypothesis
ChatGPTPark a hypothesis as "not now" without losing it. Parking changes only its parked state, hides it from the default list, and is idempotent; unpark_hypothesis restores it unchanged. A retired hypothesis cannot be parked.
pause_test
ChatGPTPause a running test so it stops serving visitors but keeps its data and can be resumed later. Use this when the user explicitly asks to pause a specific test. Only a running test can be paused. Pausing does not compute a final result; the test can be resumed where it left off. This changes a live test, so it is confirmed with the user before it runs.
prepare_hypothesis_asset_upload
ChatGPTStart a direct upload of hypothesis evidence, so the file goes straight to storage instead of through this conversation. Use this for anything but a small file; each file may be up to 10 MB, and each hypothesis may have up to eight attachments. Steps: 1. Call this with the file's exact size in bytes. 2. PUT the raw bytes to uploadUrl, sending every header from headers verbatim. Do not base64-encode or otherwise transform the file, e.g. curl --upload-file ./evidence.png -H "content-type: image/png" "<uploadUrl>". 3. Call attach_hypothesis_asset with the uploadToken to create the attachment. The headers are part of the signature, so omitting or changing one, including its casing, fails with 403. The upload URL expires at expiresAt. Prepare, upload, and attach one file before preparing the next, so no signed URL expires while another file is uploading.
prepare_review
ChatGPTPrepare a private, self-only review of a building or idle test. Use this only after the user explicitly asks to prepare, inspect, or privately refine a review, including when they accept your offer after a test is created. Never call this automatically after creating a test. It does not start the full approval flow, notify anyone, or make the test live. Calling it again returns the current preparation state and link. When the preparation is ready, the user reviews it in the review-shaped page and can request revisions with quick actions or a custom rewrite. Only send_to_review promotes the resulting proposal into full review. A test that stopped for the owner's input (BLOCKED) cannot be prepared until that input is settled; the owner checks its draft in the preview on the test page instead.
queue_test
ChatGPTQueue a test to start automatically when the test currently running on the same page and audience ends. Use this when the user wants to run a test but another is already running there and they choose to wait rather than stop it. Only an idle or in-review test can be queued, and there must already be a test running on the same page and audience to queue behind; otherwise the user should just start it directly. If the test still needs review, it reports that. This is confirmed with the user before it runs.
read_product_area
ChatGPTGet a short, read-only summary and a link for a product area the assistant cannot change from chat. Use this for questions about billing, the organisation, integrations, or guidelines. - area: billing, org, integrations, or guidelines. Returns a plain summary and a link to where the user manages that area. You cannot make changes here; point the user to the link for anything beyond reading.
remove_list_entry
ChatGPTRemove one entry from a reusable trigger list. If an active trigger references the list, the removal can immediately change which visitors match running tests.
remove_test_from_exclusion_group
ChatGPTLet a test run alongside every other test again by taking it out of its exclusion. A running or paused test cannot leave (its visitors are assigned); pause is not enough, it must be stopped. An exclusion left with fewer than two tests dissolves.
resolve_test_blocker
ChatGPTResolve one item pagent raised on a test: a blocker on a build waiting for the owner's input (status BLOCKED, shown as "Needs input"), or a suggestion left after a finished build, such as a primary goal for a test that has none. Apply its suggested fix, answer it, or dismiss it. Setup items also count as done once the owner fixes that setup another way, e.g. by attaching an audience or choosing a primary goal. Returns the updated lists; when every blocker of a BLOCKED test is done, offer continue_test_build. Suggestions never need continuing. When the owner checked a blocked draft themselves and wants it finished without another build (for example an automatic check that cannot pass on their site), accept it as is instead; that keeps the blockers on record and makes the test a ready draft. A trigger fix ("Create ... trigger" or "Run on every page the trigger matches") may also move the test to every page the trigger matches: a test's page applies on top of its trigger, so a trigger alone never widens it. Never tell the owner to remove the page binding by hand; this fix does it. Confirm with the user first: applying a fix creates an audience, trigger, or goal, changes the test's goals, or moves the test to other pages, and accepting finishes the test with the draft as it is.
resume_test
ChatGPTResume a paused or stopped test so it serves visitors again. Use this when the user explicitly asks to resume or restart a specific test. Only a paused or stopped test can be resumed, only one test may run per page and audience, and a stopped test that has already been replaced by a newer one cannot be resumed. If another test is running on the same page and audience, this returns a blocked result offering to stop it first. This makes the test live again, so it is confirmed with the user before it runs. Do not assume resume is available from a test's status alone. Check allowedNextActions on the test, and offer resume only when it is listed there.
retire_hypothesis
ChatGPTRetire a hypothesis as answered with "stop pursuing this." Use this when the user has concluded the idea is not worth testing further. The hypothesis remains visible as evidence with the reason attached. Retirement is terminal and cannot be undone. It clears any parked state, and no new test can be built from the retired hypothesis; create a follow-up if a new angle emerges. Prefer archive_hypothesis for noise that should disappear and park_hypothesis for ideas to revisit.
retry_website_onboarding
ChatGPTRetry failed website analysis as a new onboarding revision, crawling and capturing the customer website on the public internet. Existing website state remains the source of truth.
rollback_test
ChatGPTRoll a running or paused test back to an idle draft: it stops serving to visitors and its start time, progress, and interim outcome are reset, while its variations, changes, and review results are kept. Use this when the user wants to take a test off their site without recording a completed result, e.g. it launched too early or needs rework before a clean restart. This discards the test's collected run state. A test that already has a follow-up test cannot be rolled back. To merely suspend a test and keep its data, pause it instead.
run_analytics_sql
ChatGPTRun one read-only ClickHouse SELECT over this website's raw analytics: page loads, conversions, events and interactions. Use it for questions the other analytics tools cannot shape, such as breakdowns across several dimensions, funnels, paths, time of day, clicks on specific elements or links, or cohorts of visitors. Call get_analytics_sql_guide once before your first query in a conversation: it lists the pagent.* views you can read, their columns, the counting rules and worked examples. The data is already limited to this website; never filter on a website id. Prefer the dedicated tools when they answer the question: get_test_results for a test's uplift and probability to win (its statistics are not reproducible in SQL), get_analytics for the numbers the dashboard shows. If your SQL number differs from theirs, trust theirs and say why yours differs. A query that fails returns error.hint: what to change. Fix the SQL and retry; do not repeat the same query. At most maxRows rows come back; truncated: true means there were more, so aggregate or add LIMIT instead of asking for more rows. Values come back in column order; large integers can come back as strings.
search_entities
ChatGPTFind entities in this workspace by a fuzzy or partial description and get a working deep link to each. Use this first when the user refers to something without an exact name, e.g. "my collection-page test", "the pricing hypothesis", "the mobile audience", "the sale-badge trigger", or "the SKU list". - query: the words to match (required). Matched case-insensitively against names, page paths, hypothesis text and short names, guideline content, trigger descriptions, and list kinds. - types: optionally limit to some kinds (test, hypothesis, explorer, page, audience, guideline, trigger, list, exclusion_group). Omit to search all. Returns a flat list of matches, each with its entityType, id, human label, in-app url, and a short snippet. Page matches also return canonicalPath, isGlob, and exampleUrl. A fuzzy Page result is only a candidate: never treat a covering wildcard as equivalent to a requested literal path. If nothing matches, the list is empty: offer the closest results or ask for a more specific description, never invent an entity.
select_personas
ChatGPTSet which personas are active. This replaces the whole active set: pass every persona id that should be selected (personas not listed are deselected). To add one, include it alongside the currently selected ones from get_personas.
select_strategy
ChatGPTMake a strategy the active one. Exactly one strategy is active at a time, so this deselects whichever was active before. Use get_strategies to find the id.
send_to_review
ChatGPTSend an idle test into review so reviewers are assigned and notified. Without explicit reviewers it assigns the page's recommendation (the same reviewers as the last review on that page, or the configured defaults); pass reviewers to use specific people instead, including external reviewers invited by email via newGuestEmails. ALWAYS call get_reviewers first and state the reviewer set in your message, then call this. When get_reviewers reports a decidingGoalSuggestion, warn the user about it before sending. Tests created from a hypothesis wait as idle drafts until sent to review this way. This does not start the test; after the review completes the user still starts it. Use get_review afterwards to follow the review's progress.
set_page_audiences
ChatGPTSet which audiences a page targets. Order matters: the first is highest priority. This replaces the page's whole audience set, it does not add to it. Pass every audience the page should target, including ones already on it, or they are removed. Use list_audiences to see what a page targets today. The replacement is published to the SDK and can immediately change which visitors are eligible for running tests.
set_test_result
ChatGPTRecord the user's own result for a stopped test: a win, a loss, or inconclusive. Use this when the user says how they read a finished test, e.g. "count test 7 as a loss", or wants to undo their call and go back to pagent's verdict (result null). pagent decides a result only at its scheduled checks or at the maximum duration. The user's result wins over pagent's, which stays recorded, and hypotheses, reports and learnings show that the user decided. It never changes shipping: a loss can still be shipped, and a win does not have to be. Only a stopped test has a result to set. Confirm with the user first.
ship_test
ChatGPTMark a completed test as shipped: the user has implemented a variation permanently on their site. Use this when the user says they shipped, implemented, or rolled out a variation. Only a stopped test can be marked shipped. Shipping is the user's decision and does not depend on the result: a test that lost or was inconclusive can still be shipped when the user sees other advantages. This records the decision (and notifies per workspace settings); it does not change the site itself. To undo the marker later, use unship_test.
start_preview
ChatGPTStart a recorded preview of one variation of a test, to check it on the real website. Returns previewUrl. Open it in a browser you control, or give it to the user. On that page the pagent SDK applies the variation and keeps it applied as the visitor navigates wherever the test runs. It shows a preview bar and records page views, clicks, goal conversions, custom events and errors, such as a change it could not apply. Nothing reaches the test's results or analytics. To verify a variation: 1. Call start_preview with the test and the variation. 2. Open previewUrl in the browser. Check that each change get_test_changes lists is visible and looks right, then act like a visitor: click what the test's goals track and visit the pages they count. 3. Wait about 5 seconds after your last action, then call stop_preview with the sessionId. It ends the recording and returns the results. 4. Report from those results only: whether the variation was applied, which goals fired, and the errors. Give the test by id or by its number (e.g. 7). Give the variation by letter, label, id, or "control"; A is the control and B the first variation. Leave it out when the test has only one variation besides the control. entryUrl defaults to the page the test runs on; pass another page of the same website when needed. The website needs the pagent SDK installed. The preview stays on in that browser tab until it is exited from the preview bar or the tab is closed. Sessions expire 24 hours after they start.
start_test
ChatGPTStart a test so it goes live to real visitors. Use this when the user explicitly asks to start, launch, or run a specific test. Only idle, in-review, or queued tests can be started, and only one test may run per page and audience at a time. If another test is already running there, this returns a blocked result offering to queue this test or stop the running one instead. If the test still needs review, it reports that.
stop_preview
ChatGPTStop a recorded preview session started with start_preview and return what pagent recorded: whether the variation was applied, which of the test's goals fired, the errors the SDK reported, and the timeline. Call it once you have finished testing in the browser. A few seconds after the stop the session records nothing more, even if the browser tab is still open. The SDK sends page views and clicks every 5 seconds, so wait about 5 seconds after your last action before stopping. A batch already on its way when you stop is still recorded, and get_preview_results then shows it. Report only what the results say. A goal that did not fire was not triggered during this session. If applied is false although the page was open for more than a few seconds, the website is probably missing the pagent SDK or the page is not one the test targets. Stopping twice is harmless.
stop_test
ChatGPTStop a running test: it stops serving visitors and its final result is computed. Use this when the user explicitly asks to stop, end, or halt a specific test. Only a running test can be stopped. A stopped test is "stopped", not "paused". They are different states: a stopped test has a final result, a paused one does not. Stopping is not permanent: a stopped test can be resumed later unless a newer test has replaced it. If a test is queued behind it on the same page and audience, that one starts automatically. This ends a live test, so it is confirmed with the user before it runs. pagent only decides a result at its scheduled checks. A manual stop records the user's own result instead: ask whether they call it a win, a loss or inconclusive and pass it as result. Without one the test is recorded as inconclusive, decided by the user. Shipping is a separate decision. The result reports allowedNextActions, the lifecycle actions that would actually succeed afterwards. Offer only those.
submit_review_verdict
ChatGPTSubmit the user's own review verdict on a test's proposed changes. Use this ONLY when the user is an assigned reviewer on the test (get_review returns their mySubmission as PENDING) and they have told you their decision. Every proposed change needs a decision in one submission. Either pass approveAll: true when the user approves everything, or pass a verdict for EVERY modificationId that get_review listed under changes: approve, reject (needs rework), veto (must not ship), or remove (drop the change — only mandatory reviewers may use remove; optional reviewers should reject instead). A comment explaining why is required for reject and veto. Always call get_review first so the verdicts cover the real change list, and lay the decisions out in your message. Submitting is final for this review cycle and can complete the review and notify people. You can only ever submit the verdict of the user you are talking to, never on behalf of someone else.
unarchive_trigger
ChatGPTRestore an archived trigger to the active SDK payload. A running test that uses the trigger can start matching visitors immediately.
unpark_hypothesis
ChatGPTUnpark a previously parked hypothesis and restore it unchanged. This is idempotent: a hypothesis that is not parked is returned unchanged.
unship_test
ChatGPTRemove the shipped marker from a test that was previously marked as shipped, e.g. when the shipped change was reverted on the site or the marker was set by mistake. This only clears the record; it does not change the site.
update_audience
ChatGPTUpdate an audience's name, description, persona, or targeting rules. Name the audience to change, then supply the full rule tree you want it to end with: the rules you give replace the existing ones outright, they are not added to them. Read the current rules with get_audience first; its rules field is in exactly this shape, so edit that and send it back. Rules are a list joined by match (and/or); an entry is a condition or a nested group { match, conditions }, so "(google AND cpc) OR (bing AND cpc)" is match: or with one and-group per pair. Tests already running on this audience keep running, and the new rules take effect for visitors from then on.
update_click_goal
ChatGPTChange a click goal's CSS selector, page scope, name, or scope (test vs workspace) in place. Provide the goal id (from get_goals) and only the fields that change. The goal keeps its id, so tests that measure it and everything recorded under it stay attached; the SDK binds the new definition on the site's next config load. Use this to widen a goal to every page ('**'), to add a variation's rebuilt markup to the selector list, to fix a selector that stopped matching, or to promote a goal a test once picked into a workspace goal (scope 'WORKSPACE') so it is tracked all the time. Only click goals can be edited here; page-view goals use update_page_view_goal. Rules the user should hear: a changed selector or scope counts from the moment it is published, and clicks recorded under the old definition stay as they were. The edit is refused when another click goal already tracks the same selector on the same scope.
update_exclusion_group
ChatGPTRename or describe an exclusion, or change how it splits visitors (mode, scope, weights, priority order). Read it with get_exclusion_groups first. While a member runs (locked), mode, scope and priorities are frozen and running members' weights cannot change, so no visitor is moved between tests; say so instead of retrying.
update_goal_details
ChatGPTChange a conversion goal's description, or the name of an event or click goal, in place. Provide the goal id (from get_goals) and only the fields that change. Neither affects how the goal counts, so tests that measure it and everything recorded under it stay as they are. Describe what actually happens on the site when the goal converts; check the site's own code or ask the user rather than guessing from the label. A programmatic or page-view goal's name is the tag it is reported under and cannot be renamed here, and goals a JavaScript change provisioned keep the label the change gave them.
update_hypothesis
ChatGPTEdit a hypothesis's text, short name, notes, source, priority, owner, or labels. Use this when the user wants to revise an idea or organise the backlog. A hypothesis stays editable after tests have been created from it; the tests keep the brief they were built with. When the user is working on an existing saved hypothesis and asks to improve it or supplies information to strengthen it, update that hypothesis by default in the same turn instead of leaving only a chat draft or waiting for a second request to save. Read its current text and notes with get_hypotheses(hypothesisId) and use the resolved hypothesisId from the conversation or current hypothesis context; search or ask when the reference is ambiguous. Never use capture_hypothesis to create a duplicate revision. Asking before saving a new idea during brainstorming does not apply to these edits. Explicit instructions to only discuss, show a draft, or avoid edits take precedence; a request to explain or assess alone does not authorize a rewrite. For these improvements, set fieldsToChange to only the text and/or notes you deliberately change. Omit shortName, source, priority, ownerEmail, and labels unless the user asked to change them. Pass only the fields to change. fieldsToChange is an optional, nonempty field mask: when provided, only those fields are applied, and all other fields are ignored even if filled by the model. Supply a value for every selected field. Without a mask, existing callers retain partial-update behavior. Send null for notes or source to clear them. The short name is the few-word code name shown in lists; pagent generates one when the hypothesis is captured and again when the text changes, so only pass shortName when the user asks for a specific name (send null to have it regenerated). Priority ranks which idea gets the next test slot (urgent, high, medium, low; "none" clears it). New hypotheses have no priority by default; pagent automatically rates confidence only. Set, change, or clear priority only when the user explicitly asks for it or asks you to prioritize hypotheses. Otherwise omit priority, including when editing other fields. Owner takes a workspace member's email (as returned by get_hypotheses or list_organisation_members) or null to hand the idea back to pagent. Labels replace the whole label set by name; unknown names are created. To set an idea aside use park_hypothesis; to stop pursuing it use retire_hypothesis; to hide it use archive_hypothesis. The result includes the five-pillar evaluation of the saved hypothesis (as evaluate_hypothesis reports it), so there is no need to call evaluate_hypothesis afterwards. Act on its nextStep in the same reply: when pillars are missing, look them up in pagent's data as it describes before asking the user, rather than moving on. It is returned when the text or notes change.
update_keyword
ChatGPTUpdate a keyword's text and/or the pages it is linked to. Provide the keyword id; omit fields you are not changing. Passing pages replaces the linked set; omitting pages keeps the current links. Use get_keywords to find the id.
update_knowledge_section
ChatGPTChange a section of the website's knowledge docs: its title, its text, or whether it is a rule, fact or reference. Read the section with get_knowledge first and pass its id and version; to change its text, read it by sectionId so you have the whole text, as search results cut long texts short. The text you send replaces the whole current text. A design system section (colors, typography, spacing and shape, components, UI tone) has no editable text: its text is written from its design tokens, so change it with tokenChanges, a list of token path and value from get_knowledge read by sectionId, and send nothing else with it. Values are #rrggbb colors, pixel values like 16px, or a role alias like {color.action}; null removes a token. Changing a color can update the text of other design system sections that use it. If the section changed since you read it, this fails: read it again and redo the edit on the new text. Available only while knowledge docs are the website's main context system.
update_list
ChatGPTUpdate a trigger list's name or kind. This does not alter its entries.
update_list_entry
ChatGPTReplace one trigger list entry. Use get_list to find its id. If an active trigger references the list, the replacement can immediately change which visitors match running tests.
update_page_view_goal
ChatGPTUpdate a page-view goal's name or the page it counts. Provide the goal id; omit fields you are not changing. Use get_goals to find the id. Only page-view goals can be edited here.
update_persona
ChatGPTUpdate an existing persona. Provide the persona id and only the fields you want to change; unchanged fields keep their current value. Use get_personas first to find the id. You can also set selected to activate or deactivate the persona.
update_strategy
ChatGPTUpdate a strategy's name or description. Provide the strategy id and the fields to change; unchanged fields keep their current value. The active strategy cannot be edited in place, deselect it first. Use get_strategies to find the id.
update_trigger
ChatGPTUpdate a trigger and replace its entire condition rule. Read it with get_trigger first; omitted metadata stays unchanged, but rule is always replaced. The new rule retargets every test that uses the trigger, running tests included, as soon as it saves; prefer creating a new trigger for tests that have not started.
