@apex-inc/mcp-server 0.26.0 → 0.27.1

package/dist/tools.js

@@ -2,10 +2,13 @@ import { z } from "zod";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { apiGet, apiPost, apiPatch, apiPut, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
+import { collectHosts, evaluateTargetUrl } from "./workspace-target-url.js";
 import { resolveExperimentHypothesis } from "./experiment-copy.js";
 import { controlGateGuidanceFor } from "./control-gate-guidance.js";
 import { getPersonLabel, lowerPerson } from "./person-label.js";
-const APEX = "∧ Apex";
+import { notStartedExplanation, publishedExperimentLine, } from "./publish-communication-copy.js";
+import { activationLiveLine, shouldRefuseActivationWiring, } from "./activation-wiring.js";
+const APEX = "Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
  *
@@ -55,6 +58,55 @@ function titleCaseEvent(event) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
+function activeWorkspaceSiteUrl() {
+    const ctx = getUserContext();
+    const key = getActiveWorkspace();
+    if (!ctx || !key)
+        return null;
+    for (const org of ctx.orgs) {
+        const match = org.workspaces.find((w) => w.workspaceKey === key);
+        if (match?.url)
+            return match.url;
+    }
+    return null;
+}
+async function assertTargetUrlForActiveWorkspace(targetUrl) {
+    const namedSites = [];
+    let workspaceUrl = activeWorkspaceSiteUrl();
+    let catalogUnreadable = false;
+    try {
+        const env = await apiGet("/api/workspace/environments");
+        namedSites.push(...(env.data.production_hosts ?? []), ...(env.data.beta_hosts ?? []));
+        for (const row of env.data.known_hosts ?? []) {
+            namedSites.push(typeof row === "string" ? row : row.hostname ?? "");
+        }
+        if (env.data.workspace_url)
+            workspaceUrl = env.data.workspace_url;
+    }
+    catch {
+        catalogUnreadable = true;
+    }
+    let analyticsHosts = [];
+    try {
+        const json = await apiGet("/api/analytics/hostnames?limit=100");
+        analyticsHosts = json.data ?? [];
+    }
+    catch {
+        /* analytics is a supplement, not the source of truth */
+    }
+    const allowed = collectHosts({
+        analyticsHosts,
+        namedSites,
+        workspaceUrl,
+    });
+    if (allowed.length === 0 && catalogUnreadable) {
+        return {
+            ok: false,
+            message: "Could not load this workspace's sites (list_workspace_environments failed). Name the site with set_workspace_environments before setting target_url. Do not guess a brand domain or a sibling workspace's site.",
+        };
+    }
+    return evaluateTargetUrl(targetUrl, allowed);
+}
 /**
  * Query string for the pack report windows: relative (`days` / `months`)
  * or explicit `start` + `end` (YYYY-MM-DD, both required together —
@@ -81,28 +133,6 @@ function appUrl(path) {
     const base = process.env.APEX_URL || process.env.APEX_API_URL || "http://localhost:3001";
     return `${base.replace(/\/$/, "")}${path}`;
 }
-/**
- * Why publishing a comm with variants didn't start an experiment.
- *
- * Each of these is a missing precondition the user can actually fix, so the
- * agent is told what to do rather than that "nothing happened."
- */
-function notStartedExplanation(reason) {
-    switch (reason) {
-        case "no_host":
-            return "The variants were published but no experiment started: no published journey sends this communication, so there's no traffic to measure. Add it to a journey and publish that journey.";
-        case "no_goal":
-            return "The variants were published but no experiment started: the journey sending this communication has no goal event, so there's nothing to optimize toward. Set the journey's goal event first.";
-        case "ambiguous_host":
-            return "The variants were published but no experiment started: more than one published journey sends this communication. Re-issue publish_communication with host_journey_id.";
-        case "conflict":
-            return "The variants were published but no experiment started: another experiment already holds this communication. End it, then publish again.";
-        case "no_variants":
-            return "";
-        default:
-            return "The variants were published but the experiment could not be started. Check the communication in the dashboard.";
-    }
-}
 function journeyLink(id) {
     return appUrl(`/dashboard/communications/journeys/${id}`);
 }
@@ -460,7 +490,7 @@ export const toolDefinitions = {
         description: `${APEX} — Create an experiment record. Returns a structured recipe for the AI agent to implement. The agent makes the actual code changes using useApexVariant hook — Apex never generates code. Always call with preview=true first so the user sees a summary.`,
         schema: z.object({
             name: z.string().describe("Experiment name"),
-            targetUrl: z.string().describe("URL of the page to test (include #anchor for section targeting)"),
+            targetUrl: z.string().describe("URL of the page to test on the ACTIVE workspace (include #anchor for section targeting). Must be a host this workspace has actually sent events from — never guess a brand domain or a sibling workspace's site."),
             controlContent: z.string().describe("The current content that the control shows"),
             variantContent: z.string().describe("The new content for the variant"),
             targetComponent: z.string().optional().describe("Component or file path where the change should be made"),
@@ -487,6 +517,13 @@ export const toolDefinitions = {
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
         }),
         handler: async (args) => {
+            const targetCheck = await assertTargetUrlForActiveWorkspace(args.targetUrl);
+            if (!targetCheck.ok) {
+                return {
+                    content: [{ type: "text", text: `${APEX} ${targetCheck.message}` }],
+                    isError: true,
+                };
+            }
             const split = args.trafficSplit ?? 50;
             // MCP experiments are ALWAYS code-native (SDK). Client-side snippet /
             // runtime-DOM experiments are intentionally NOT offered here (founder
@@ -811,12 +848,16 @@ export const toolDefinitions = {
                 `2. Install the hook package: npm i @apex-inc/react`,
                 `3. Add: import { useApexVariant } from "@apex-inc/react"`,
                 `4. In the component, add: const variant = useApexVariant("${exp.id}")  // fires experiment_exposure automatically`,
+                `   Next.js App Router: pass the request search string so the first HTML matches the preview URL: useApexVariant("${exp.id}", { search }). Without it the server renders control and the arm only appears after hydrate.`,
                 `5. Wrap the target content in a conditional (fall back to control on null/error):`,
                 `   {variant === "variant_a" || variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
-                `6. Screenshots for the dashboard:`,
-                `   - Public web page: Apex auto-captures on create — nothing to do.`,
-                `   - localhost / auth-gated: capture BOTH arms, then call attach_experiment_asset({experimentId, variantKey, imageBase64}).`,
-                `7. Show the user the diff and ask them to preview at: ${previewUrl}`,
+                `6. Screenshots for the dashboard — REQUIRED before you tell the user the draft is ready:`,
+                `   - This is an SDK experiment. The variant exists only in local code until it ships.`,
+                `   - Apex does NOT auto-capture a public URL on create (that page does not have the variant yet, and a guessed host shows the wrong site on both arms).`,
+                `   - Capture BOTH arms on localhost with ?_apex_preview=control|variant_a&_apex_exp=${exp.id}, then call attach_experiment_asset({experimentId, variantKey, imageBase64}) for each arm.`,
+                `   - After the code is deployed, recapture_experiment_screenshots refreshes the live host.`,
+                `7. Show the user the diff. Dashboard "View live" links are built from target_url (not a hardcoded host). Preview the variant at: ${previewUrl}`,
+                `   If the merchant is QA'ing on localhost, the dashboard rewrites Apex app hosts to this origin so the unpublished variant is visible.`,
                 `8. After preview approval, commit and push`,
                 `9. Call track_deployment with the experiment ID and commit SHA`,
                 `10. Call activate_experiment (with the user's go-ahead). If the code isn't live yet, the`,
@@ -960,7 +1001,7 @@ export const toolDefinitions = {
         },
     },
     recapture_experiment_screenshots: {
-        description: `${APEX} — Re-run the hosted screenshot capture for a WEB experiment's arms (renders the target URL for control + variant and stores the images shown on the dashboard). Use when screenshots are missing or stale — e.g. the page changed, or an earlier capture failed. Web experiments only (mobile arms capture on-device via the SDK).`,
+        description: `${APEX} — Re-run the hosted screenshot capture for a WEB experiment's arms (renders the target URL for control + variant and stores the images shown on the dashboard). Use after the variant is deployed. For unpublished SDK / Cursor drafts, attach localhost shots with attach_experiment_asset instead — hosted recapture of a public URL will be refused.`,
         schema: z.object({
             experimentId: z.string().describe("The experiment ID to re-capture screenshots for."),
         }),
@@ -1066,7 +1107,7 @@ export const toolDefinitions = {
         },
     },
     activate_experiment: {
-        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Before flipping to running, this verifies BOTH arms are producing \`experiment_exposure\` events (wiring check). Code-wired (SDK-hook) experiments may be activated before their code ships: the server holds them in \`pending_deployment\` ("Waiting on deploy") and starts on the first exposure. Snippet experiments are applied by the Apex snippet at runtime, so they also don't need pre-activation exposures — they launch and wiring is verified afterward. Only wired experiments that genuinely can't self-start are refused unless force is true. Ask the user to confirm before calling.`,
+        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Before flipping to running, this verifies BOTH arms are producing \`experiment_exposure\` events (wiring check). Code-wired (SDK-hook) experiments may be activated before their code ships: the server holds them in \`pending_deployment\` ("Waiting on deploy") and starts on the first exposure. Snippet experiments and journey_arm message tests do not need pre-activation exposures — journey traffic starts on the next send once running. Only wired web experiments that genuinely can't self-start are refused unless force is true. Ask the user to confirm before calling.`,
         schema: z.object({
             experimentId: z.string().describe("The experiment ID to activate"),
             force: z
@@ -1091,11 +1132,7 @@ export const toolDefinitions = {
             // the experiment ONCE IT'S RUNNING, so it can't have pre-activation
             // exposures — blocking on them is a chicken-and-egg. Both are safe to
             // launch "early"; wiring is verified AFTER via verify_experiment_wiring.
-            if (wiring &&
-                !wiring.bothArmsLive &&
-                force !== true &&
-                !wiring.sdkMode &&
-                !wiring.snippetMode) {
+            if (wiring && shouldRefuseActivationWiring(wiring, force)) {
                 const armLines = wiring.perArm.map(formatArmLine);
                 const zeroArms = wiring.perArm
                     .filter((a) => a.exposures === 0)
@@ -1194,9 +1231,11 @@ export const toolDefinitions = {
             // PATCH returns a minimal/legacy body — re-read the unified record to
             // derive the live traffic split from the allocation weights.
             let controlPct = 50;
+            let liveSurface = exp.surface;
             try {
                 const unified = await apiGet(`/api/experiments/${experimentId}?unified=true`);
                 controlPct = controlPctOf(unified);
+                liveSurface = unified.surface ?? liveSurface;
             }
             catch { /* fall back to 50/50 in the message */ }
             // Surface why the wiring gate didn't block: either it couldn't be
@@ -1235,7 +1274,7 @@ export const toolDefinitions = {
                             `  Traffic is being split ${controlPct}% / ${100 - controlPct}%`,
                             ``,
                             ...notes,
-                            `  Visitors will now see either the control or variant.`,
+                            `  ${activationLiveLine(liveSurface)}`,
                             `  Results will appear in the dashboard and via get_results.`,
                             ``,
                             `${"═".repeat(40)}`,
@@ -1646,6 +1685,8 @@ export const toolDefinitions = {
             name: z.string().optional().describe("Rename (cosmetic; editable anytime)."),
             surface: z.enum(["web", "mobile"]).optional().describe("Correct the surface — editable only on a draft with 0 exposures (web↔mobile)."),
             hypothesis: z.string().optional().describe("Edit the hypothesis — draft only (pre-registration)."),
+            targetUrl: z.string().optional().describe("Retarget a DRAFT to a URL on the ACTIVE workspace. Same host rules as create_experiment."),
+            predictionId: z.string().optional().describe("Attach a minted prediction id (from log_prediction) to this draft. Required before activation."),
             primaryMetricEvent: z.string().optional().describe("Change the primary metric's canonical event — draft only."),
             primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional(),
             guardrailEvent: z.string().optional().describe("Replace the guardrail with this canonical protective event — draft only."),
@@ -1653,6 +1694,15 @@ export const toolDefinitions = {
             runtimeDays: z.number().int().min(1).max(365).optional().describe("Set how long to run the experiment, in days (the decision window Apex force-concludes at). Draft only — part of the pre-registration; freezes at launch (fork to change it)."),
         }),
         handler: async (args) => {
+            if (args.targetUrl) {
+                const targetCheck = await assertTargetUrlForActiveWorkspace(args.targetUrl);
+                if (!targetCheck.ok) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} ${targetCheck.message}` }],
+                        isError: true,
+                    };
+                }
+            }
             const body = { id: args.experimentId };
             if (args.name !== undefined)
                 body.name = args.name;
@@ -1660,6 +1710,10 @@ export const toolDefinitions = {
                 body.surface = args.surface;
             if (args.hypothesis !== undefined)
                 body.hypothesis = args.hypothesis;
+            if (args.targetUrl !== undefined)
+                body.targetUrl = args.targetUrl;
+            if (args.predictionId !== undefined)
+                body.predictionId = args.predictionId;
             // evaluationWindow patch — the API merges it, so setting one of
             // minPerVariant / durationDays never clobbers the other.
             if (args.minSamplePerArm !== undefined || args.runtimeDays !== undefined) {
@@ -1746,7 +1800,15 @@ export const toolDefinitions = {
                     content: [
                         {
                             type: "text",
-                            text: `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}). Edit it with update_experiment, then activate.`,
+                            text: [
+                                `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}).`,
+                                ``,
+                                `A copy gets a new id. The page still asks the old one until you replace it.`,
+                                `  Find:    const variant = useApexVariant("${experimentId}");`,
+                                `  Replace: const variant = useApexVariant("${forked.id}");`,
+                                `Deploy that change, then activate.`,
+                                `Preview still works via _apex_exp. A normal visit shows control until the new id is shipped.`,
+                            ].join("\n"),
                         },
                     ],
                 };
@@ -2742,9 +2804,9 @@ Identical to the SDK's track() and the snippet's apex.track(). Use this to instr
 
 The Apex Spec ships two peer registries:
 
-\u2022 **App events** (\`APEX_EVENTS\`) — the canonical SDK vocabulary the customer's app fires. Names you'll commonly use here: \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`in_app_purchase\`, \`purchase_refunded\`, \`subscription_event\`, \`user_signed_up\`, \`user_signed_in\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`click\`, \`search\`, \`share\`, \`content_view\`, \`goal_conversion\`, \`email_opened\`, \`email_clicked\`, \`push_opened\`, \`in_app_message_seen\`, \`deep_link_open\`. Field names are flat snake_case (e.g. \`product_id\`, \`order_id\`, \`value\`, \`currency\`).
+\u2022 **App events** (\`APEX_EVENTS\`) — the canonical SDK vocabulary the customer's app fires. Names you'll commonly use here: \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`in_app_purchase\`, \`purchase_refunded\`, \`subscription_event\`, \`user_signed_up\`, \`user_signed_in\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`click\`, \`ui_action\`, \`search\`, \`share\`, \`content_view\`, \`goal_conversion\`, \`email_opened\`, \`email_clicked\`, \`push_opened\`, \`in_app_message_seen\`, \`deep_link_open\`. Field names are flat snake_case (e.g. \`product_id\`, \`order_id\`, \`value\`, \`currency\`). Named in-product controls (buttons, tabs, widget chrome) are \`ui_action\` with \`action\` + \`name\` + optional \`location\` — do not invent one event per button. SDK helper: \`trackUiAction({ action, name, location })\`.
 
-\u2022 **Platform events** (\`APEX_PLATFORM_EVENTS\`) — events Apex's own dashboard fires as merchants use it. Names: \`user_invitation_created\`, \`user_invitation_accepted\`, \`developer_invite_sent\`, \`integration_connected\`, \`integration_sync_completed\`, \`integration_sync_failed\`, \`experiment_launched\`, \`experiment_significant\`, \`experiment_concluded\`, \`experiment_promoted\`, \`portfolio_access_requested\`, \`portfolio_access_approved\`, \`portfolio_access_rejected\`, \`portfolio_share_accepted\`, \`subscription_upgraded\`, \`subscription_downgraded\`, \`tier_limit_approaching\`, \`anomaly_detected\`, \`weekly_digest_scheduled\`, \`cognito_verification_code\`, \`user_signup\`. Use these when an agent is acting *as* the Apex platform (admin tooling, dashboard automation), not as the customer's product.
+\u2022 **Platform events** (\`APEX_PLATFORM_EVENTS\`) — events Apex's own dashboard fires as merchants use it. Names: \`user_invitation_created\`, \`user_invitation_accepted\`, \`developer_invite_sent\`, \`integration_selected\`, \`integration_connected\`, \`setup_step_continued\`, \`integration_sync_completed\`, \`integration_sync_failed\`, \`experiment_launched\`, \`experiment_significant\`, \`experiment_concluded\`, \`experiment_promoted\`, \`portfolio_access_requested\`, \`portfolio_access_approved\`, \`portfolio_access_rejected\`, \`portfolio_share_accepted\`, \`subscription_upgraded\`, \`subscription_downgraded\`, \`tier_limit_approaching\`, \`anomaly_detected\`, \`weekly_digest_scheduled\`, \`cognito_verification_code\`, \`user_signup\`. Use these when an agent is acting *as* the Apex platform (admin tooling, dashboard automation), not as the customer's product.
 
 Custom event names are accepted (the spec is open by default), but agents should prefer canonical names from one of the two registries so the event flows directly into the catalog templates, the journey trigger system, and the conversion-goal helpers without manual wiring. The full spec lives at https://docs.apex.inc/spec.
 
@@ -3114,7 +3176,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     list_communications: {
-        description: "List the workspace's communication templates (email / inbox / web push / mobile push) with the fields you need to CHOOSE one — for a journey send step, a broadcast, or a transactional send. Returns per template: title, version, status, pipeline, channels, subject, a one-line body preview so you can disambiguate similar titles without opening each one, and controlState. Pipeline is 'transactional' (bypasses opt-out — needs a recipient-initiated trigger) or 'marketing' (consent-gated). Filter by pipeline, channel, or a search string. This is the programmatic equivalent of the dashboard's communication picker.\n\ncontrolState tells you what the Control currently IS, and therefore what editing it will cost: 'winner' (won an experiment, unedited — editing needs an explicit intent), 'winner_edited' (won, then changed since), 'in_experiment' (frozen, an experiment is measuring it right now), 'no_winner' (an experiment ran and settled without one), 'none' (never experimented on, edit freely).",
+        description: "List the workspace's communication templates (email / inbox / web push / mobile push) with the fields you need to CHOOSE one — for a journey send step, a broadcast, or a transactional send. Returns per template: title, version, status, pipeline, channels, subject, a one-line body preview so you can disambiguate similar titles without opening each one, and controlState. Pipeline is 'transactional' (bypasses opt-out — needs a recipient-initiated trigger) or 'marketing' (consent-gated). Filter by pipeline, channel, or a search string. This is the programmatic equivalent of the dashboard's communication picker.\n\ncontrolState tells you what the Control currently IS, and therefore what editing it will cost: 'winner' (won an experiment, unedited — editing needs an explicit intent), 'winner_edited' (won, then changed since), 'in_experiment' (frozen, an experiment is measuring it right now), 'no_winner' (an experiment ran and settled without one), 'none' (never experimented on). A live letter with no champion is still editable; Publish asks replace vs compete. A champion or a running test: do not edit Control — add a variant, then compete.",
         schema: z.object({
             pipeline: z
                 .enum(["transactional", "marketing"])
@@ -3341,13 +3403,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     publish_communication: {
-        description: "Publish a communication's draft as the live version — this is what makes an edit reach recipients. Editing only saves a draft.\n\nIf the communication has variants, publishing STARTS the experiment that measures them against the control. That is the point of authoring a variant: a variant that is never published is measured by nothing.\n\nTwo conflicts need a decision rather than a retry. `ambiguous_experiment_host` means several published journeys send this communication, so Apex cannot tell where the experiment belongs — the candidates are returned; ask the user and re-issue with host_journey_id. `comm_already_in_experiment` means one is already running; end it first.",
+        description: "Publish a communication's draft as the live version — this is what makes an edit reach recipients. Editing only saves a draft.\n\nCompete (or publishing a letter that already has variants) creates a prefilled DRAFT experiment. It does not start the test. After the user reviews the draft, call activate_experiment to begin it. Replace publishes the letter for everyone and never creates an experiment.\n\nOptional overrides: hypothesis, belief_id, confidence, duration_days.\n\nTwo conflicts need a decision rather than a retry. `ambiguous_experiment_host` means several published journeys send this communication — the candidates are returned; ask the user and re-issue with host_journey_id. `comm_already_in_experiment` means one is already running; end it first.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to publish"),
             intent: z
                 .enum(["compete", "replace"])
                 .optional()
-                .describe('How to apply the draft when the Control is protected. "compete" = the current content keeps sending and your draft runs against it as an experiment (safe default). "replace" = your draft becomes what everyone receives, superseding any prior win. Required only when the comm won an experiment or is live in a published journey.'),
+                .describe('How to apply the draft when the Control is protected. "compete" = the current content keeps sending and your draft becomes a filled-in experiment draft (then activate_experiment). "replace" = your draft becomes what everyone receives. Required only when the comm won an experiment or is live in a published journey.'),
             confirmLiveExperiment: z
                 .boolean()
                 .optional()
@@ -3356,6 +3418,22 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .string()
                 .optional()
                 .describe("Which published journey hosts the experiment. Only needed after a 409 ambiguous_experiment_host, using one of the returned candidate ids."),
+            hypothesis: z
+                .string()
+                .optional()
+                .describe("Override the Suggested hypothesis on the draft experiment."),
+            beliefId: z
+                .string()
+                .optional()
+                .describe("Link the draft experiment to an existing belief."),
+            confidence: z
+                .number()
+                .optional()
+                .describe("Override the prefilled confidence (percent)."),
+            durationDays: z
+                .number()
+                .optional()
+                .describe("Override the prefilled decision window in days."),
         }),
         handler: async (args) => {
             const body = {};
@@ -3365,6 +3443,14 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 body.confirmLiveExperiment = true;
             if (args.hostJourneyId)
                 body.hostJourneyId = args.hostJourneyId;
+            if (args.hypothesis)
+                body.hypothesis = args.hypothesis;
+            if (args.beliefId)
+                body.beliefId = args.beliefId;
+            if (typeof args.confidence === "number")
+                body.confidence = args.confidence;
+            if (typeof args.durationDays === "number")
+                body.durationDays = args.durationDays;
             try {
                 const data = await apiPost(`/api/communications/${args.communicationId}/publish`, body);
                 const lines = [];
@@ -3378,7 +3464,11 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                     lines.push(`${data.repinned.length} send step(s) moved to the new version.`);
                 }
                 if (data.experiment) {
-                    lines.push(`Experiment started: ${data.experiment.id}. Watch it at ${appUrl(`/dashboard/experiments/${data.experiment.id}`)}`);
+                    lines.push(publishedExperimentLine({
+                        id: data.experiment.id,
+                        status: data.experiment.status ?? "draft",
+                        url: appUrl(`/dashboard/experiments/${data.experiment.id}`),
+                    }));
                 }
                 else if (data.experimentNotStarted) {
                     lines.push(notStartedExplanation(data.experimentNotStarted));
@@ -3453,7 +3543,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     add_communication_variant: {
-        description: "Add a content variant (Variant A, B, …) to a communication. Clones the current Control into a new column so you can run a content experiment. Does not change what recipients get until you publish. Theme look is inherited; do not set per-block align here.",
+        description: "Add a content variant (Variant A, B, …) to a communication. Clones the current Control into a new column so you can run a content experiment. When the letter is a champion, this is how you author a challenger — do not edit Control. Does not change what recipients get until you publish. Theme look is inherited; do not set per-block align here.",
         schema: z.object({
             communicationId: z.string().describe("The communication to add a variant to"),
             label: z.string().optional().describe("Optional column label (e.g. Variant A)"),
@@ -3496,7 +3586,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     create_comm_experiment: {
-        description: "A/B test a communication's subject, body, or CTA. Creates an experiment with variants that split traffic using Thompson Sampling.",
+        description: "Legacy helper. Prefer the composer loop: edit_communication or add_communication_variant, then publish_communication (compete creates a prefilled draft), then activate_experiment to start the test. Do not teach this as the default.",
         schema: z.object({
             communicationId: z.string().describe("The communication to experiment on"),
             splitLevel: z.enum(["subject", "body", "cta", "full"]).describe("What to vary between variants"),