@apex-inc/mcp-server 0.27.0 → 0.27.2

package/dist/tools.js

@@ -2,12 +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";
 import { notStartedExplanation, publishedExperimentLine, } from "./publish-communication-copy.js";
 import { activationLiveLine, shouldRefuseActivationWiring, } from "./activation-wiring.js";
-const APEX = "∧ Apex";
+const APEX = "Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
  *
@@ -57,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 —
@@ -440,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"),
@@ -467,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
@@ -791,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`,
@@ -940,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."),
         }),
@@ -1624,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. Also stamps the prediction onto the experiment's hypothesis when that link is missing. 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."),
@@ -1631,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;
@@ -1638,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) {
@@ -2726,17 +2802,13 @@ export const toolDefinitions = {
 
 Identical to the SDK's track() and the snippet's apex.track(). Use this to instrument events from agent workflows, CI pipelines, or IDE actions.
 
-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\`, \`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 })\`.
+The public Spec is one registry (\`APEX_EVENTS\`): \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`order_placed\`, \`in_app_purchase\`, \`user_signed_up\`, \`waitlist_joined\`, \`user_invited\`, \`user_invite_accepted\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`feature_used\`, \`ui_action\`. Field names are flat snake_case. Named in-product controls are \`ui_action\` with \`action\` + \`name\` + optional \`location\`. 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_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, but prefer canonical names from GET /api/spec/events so templates, journeys, and conversions wire without aliases. Full spec: https://docs.apex.inc/spec.
 
-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.
-
-Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*, fixed for this MCP process) and a timestamp, so they WILL count toward wiring detection (the same signal the Set up Apex page and get_wiring_status read). They are flagged as agent-fired (source: "mcp" in the event data + the x-apex-source header), so dashboards can distinguish them from real app traffic — but they are NOT test-mode events; fire them deliberately.`,
+Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*, fixed for this MCP process) and a timestamp, so they WILL count toward wiring detection. They are flagged as agent-fired (source: "mcp") — not test-mode. Fire them deliberately.`,
         schema: z.object({
-            event: z.string().describe("Event name — snake_case from APEX_EVENTS or APEX_PLATFORM_EVENTS (e.g. 'page_view', 'in_app_purchase', 'user_invitation_created'). Custom names are accepted but prefer canonical ones."),
+            event: z.string().describe("Event name — snake_case from the Apex Spec (e.g. 'page_view', 'user_signed_up', 'order_placed'). Custom names are accepted but prefer canonical ones."),
             properties: z.record(z.unknown()).optional().describe("Flat snake_case properties matching the spec entry for this event (e.g. { product_id: 'prod_abc', value: 29.99, currency: 'USD' })."),
         }),
         handler: async ({ event, properties }) => {
@@ -2773,7 +2845,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     send_server_event: {
         description: `${APEX} — Server Events API. Send a server-to-server event via the /api/v1/events endpoint (clientType: "server", batch cap 100, idempotency-key supported). Use this from agent workflows that simulate backend integrations (Stripe webhook flows, CRM-driven conversions, billing events) or to test the Server Events API end-to-end. Differs from track_event in that it stamps clientType: "server" and uses the v1 ingest contract.`,
         schema: z.object({
-            type: z.string().describe("Event type (e.g. 'purchase_completed', 'signup_completed', or any custom verb)"),
+            type: z.string().describe("Event type (e.g. 'order_placed', 'user_signed_up', or any custom verb)"),
             visitorId: z.string().optional().describe("Visitor ID to stitch back to a web/mobile session (apex_vid)"),
             email: z.string().optional().describe("Email to stitch by identity when no visitorId is known"),
             data: z.record(z.unknown()).optional().describe("Event payload (value, currency, order_id, …)"),
@@ -3100,7 +3172,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"])
@@ -3467,7 +3539,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)"),
@@ -3502,8 +3574,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             mergeData: z.record(z.string()).optional().describe("Template variables to merge (e.g. user_name, company)"),
         }),
         handler: async (args) => {
-            await apiPost(`/api/communications/${args.communicationId}/send`, {
-                recipientEmail: args.recipientEmail,
+            // `/send` was removed. The composer test route is the one-off send:
+            // workspace-admin, optional recipient override, mergeData substitution.
+            await apiPost(`/api/communications/${args.communicationId}/test`, {
+                recipient: args.recipientEmail,
                 mergeData: args.mergeData,
             });
             return { content: [{ type: "text", text: `Communication sent to ${args.recipientEmail}.` }] };
@@ -4052,18 +4126,40 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     set_journey_trigger: {
-        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass a triggerContractId — discover valid IDs with list_trigger_contracts (an invalid id is rejected with the list of options).`,
+        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass event_name (the Apex Spec event, e.g. user_signed_up). A trig-* contract id is storage-only — prefer the Spec name.`,
         schema: z.object({
             journeyId: z.string(),
-            triggerContractId: z.string().describe("The trigger contract id (event binding) to enroll on — see list_trigger_contracts."),
+            eventName: z.string().optional().describe("Apex Spec event name that enrolls subjects (e.g. user_signed_up). Preferred."),
+            triggerContractId: z.string().optional().describe("Storage id from list_trigger_contracts. Prefer event_name."),
         }),
-        handler: async ({ journeyId, triggerContractId }) => {
+        handler: async ({ journeyId, eventName, triggerContractId, }) => {
             try {
-                // Validate the contract id up front so a typo doesn't silently set a
-                // dead trigger that only fails at publish — enumerate valid options.
                 const cdata = await apiGet("/api/journeys/trigger-contracts");
                 const contracts = cdata.contracts ?? [];
-                if (contracts.length > 0 && !contracts.some((c) => c.id === triggerContractId)) {
+                let resolvedId = triggerContractId;
+                if (eventName) {
+                    const match = contracts.find((c) => c.eventName === eventName);
+                    if (match) {
+                        resolvedId = match.id;
+                    }
+                    else {
+                        const created = await apiPost("/api/journey-triggers", {
+                            eventName,
+                            fieldMappings: { end_user_id: "endUserId" },
+                            recipientInitiated: true,
+                        });
+                        resolvedId = created.id;
+                    }
+                }
+                if (!resolvedId) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Pass event_name (preferred) or triggerContractId.` }],
+                        isError: true,
+                    };
+                }
+                if (!eventName &&
+                    contracts.length > 0 &&
+                    !contracts.some((c) => c.id === resolvedId)) {
                     const opts = contracts
                         .map((c) => `${c.id}${c.eventName ? ` (${c.eventName})` : ""}`)
                         .join(", ");
@@ -4071,18 +4167,19 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                         content: [
                             {
                                 type: "text",
-                                text: `${APEX} Unknown triggerContractId "${triggerContractId}". Valid options: ${opts}`,
+                                text: `${APEX} Unknown triggerContractId "${resolvedId}". Valid options: ${opts}`,
                             },
                         ],
                         isError: true,
                     };
                 }
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
-                const steps = (j.steps ?? []).map((s) => s.type === "trigger" ? { ...s, trigger: { type: "event", triggerContractId } } : s);
+                const steps = (j.steps ?? []).map((s) => s.type === "trigger" ? { ...s, trigger: { type: "event", triggerContractId: resolvedId } } : s);
                 const updated = await apiPatch(`/api/journeys/${encodeURIComponent(journeyId)}`, { steps });
                 if (!tenantOk(updated.workspaceKey))
                     return tenantMismatch();
-                return { content: [{ type: "text", text: `${APEX} Trigger set to contract ${triggerContractId} on journey ${journeyId}. View it: ${journeyLink(journeyId)}` }] };
+                const label = eventName ? `${eventName} (${resolvedId})` : resolvedId;
+                return { content: [{ type: "text", text: `${APEX} Trigger set to ${label} on journey ${journeyId}. View it: ${journeyLink(journeyId)}` }] };
             }
             catch (err) {
                 return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
@@ -4831,7 +4928,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
     apex_test_event: {
         description: `${APEX} — Send a test event through the public ingestion endpoint and confirm it was accepted. The fastest way to verify event tracking works after installing the SDK.`,
         schema: z.object({
-            eventName: z.string().describe("Event name, e.g. signup_completed"),
+            eventName: z.string().describe("Event name, e.g. user_signed_up"),
             attributes: z.record(z.unknown()).optional().describe("Event attributes"),
             visitorId: z.string().optional().describe("Visitor id (default a test id)"),
         }),
@@ -5180,7 +5277,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
     // owned-event matcher managed on /dashboard/conversions). A Target is an
     // aggregate KPI number to hit by a date. "Goal" is retired as a noun.
     list_conversions: {
-        description: `${APEX} — List the workspace's Conversions (the owned-event definitions of valued actions, e.g. "Purchase", "Signup"). Call this when the user asks what conversions are defined, or before creating an experiment/journey that needs an objective. The one flagged primary drives default experiment objectives, funnel metrics, and scoring.`,
+        description: `${APEX} — List the workspace's Conversions (owned-event definitions of valued actions, e.g. "Purchase", "Signup"). Call this when the user asks what conversions are defined. The starred primary is a label for that Conversion — it does not pick the funnel stages and it is not the experiment default. Experiments name their own metric; the funnel follows the workspace conversion model.`,
         schema: z.object({}),
         handler: async () => {
             const conversions = await apiGet("/api/conversion-goals");
@@ -5207,7 +5304,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     create_conversion: {
-        description: `${APEX} — Define a new Conversion (an owned-event definition of a valued action). Most conversions are a custom_event with an eventName (e.g. "purchase", "signup") matching an Apex Spec event you send via track. Set isPrimary to make it the default objective for experiments and the headline funnel metric.`,
+        description: `${APEX} — Define a new Conversion (an owned-event definition of a valued action). Most conversions are a custom_event with an eventName (e.g. "order_placed", "user_signed_up") matching an Apex Spec event you send via track. isPrimary stars this Conversion as a label — it does not pick experiment defaults or drive the funnel.`,
         schema: z.object({
             name: z.string().describe('Human label, e.g. "Purchase" or "Signup"'),
             type: z
@@ -5259,7 +5356,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     set_primary_conversion: {
-        description: `${APEX} — Mark a Conversion as the primary one. Experiments without an explicit objective default to the primary conversion, and the headline funnel + scoring use it. Pass the conversion id from list_conversions.`,
+        description: `${APEX} — Mark a Conversion as the starred primary. That star labels the Conversion — it does not set experiment defaults or drive the funnel. Experiments name their own metric. Pass the conversion id from list_conversions.`,
         schema: z.object({
             conversionId: z.string().describe("The conversion id to promote (from list_conversions)."),
         }),