@apex-inc/mcp-server 0.22.2 → 0.23.1

package/dist/tools.js

@@ -3,6 +3,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
 import { resolveExperimentHypothesis } from "./experiment-copy.js";
+import { controlGateGuidanceFor } from "./control-gate-guidance.js";
+import { getPersonLabel, lowerPerson } from "./person-label.js";
 const APEX = "∧ Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -79,6 +81,28 @@ 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}`);
 }
@@ -1834,7 +1858,7 @@ export const toolDefinitions = {
         },
     },
     get_channel_economics: {
-        description: `${APEX} — "Where should my next dollar go?" Per acquisition channel (raw first-touch): gross-margin-adjusted LTV:CAC, payback months, CAC, and customers, split into Acquisition (paid) vs Leverage (owned/organic, no spend). Computed from real contacts + spend + revenue — metrics with missing inputs are shown as "—", never fabricated. Free intelligence; the verdict is never gated.`,
+        description: `${APEX} — "Where should my next dollar go?" Per acquisition channel (raw first-touch): LTGP:CAC (lifetime gross profit over CAC) where the merchant reports product cost, LTV:CAC (lifetime revenue over CAC) everywhere else, plus payback months, CAC, and customers, split into Acquisition (paid) vs Leverage (owned/organic, no spend). Computed from real contacts + spend + revenue — metrics with missing inputs are shown as "—", never fabricated. Free intelligence; the verdict is never gated.`,
         schema: z.object({
             days: z
                 .union([z.number(), z.literal("all")])
@@ -1868,12 +1892,20 @@ export const toolDefinitions = {
             })[slug] ?? slug.charAt(0).toUpperCase() + slug.slice(1);
             const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
             const ratio = (r) => (r == null ? "—" : `${r.toFixed(2)}x`);
-            const ranked = [...channels].sort((a, b) => (b.ltvCacRatio ?? -1) - (a.ltvCacRatio ?? -1));
+            // Each channel is ranked on its best available multiple. Both are real
+            // metrics — LTGP:CAC nets out cost of goods, LTV:CAC doesn't — so the
+            // line names which one it printed rather than dropping the number.
+            const best = (c) => c.ltgpCac ?? c.ltvCac;
+            const metric = (c) => c.ltgpCac !== null ? "LTGP:CAC" : "LTV:CAC";
+            const ranked = [...channels].sort((a, b) => (best(b) ?? -1) - (best(a) ?? -1));
             const acquisition = ranked.filter((c) => c.spend !== null && c.spend > 0);
             const leverage = ranked.filter((c) => c.spend === null || c.spend === 0);
-            const fmt = (c) => `  • ${label(c.channel)}: ${ratio(c.ltvCacRatio)} LTV:CAC · payback ${c.paybackMonths != null ? `${c.paybackMonths}mo` : "—"} · CAC ${money(c.cac)} · ${c.customers.toLocaleString()} customers`;
+            // The merchant reads this back on a screen that says "Leads" or
+            // "Clients" if that's their vertical — say the same word they do.
+            const person = lowerPerson(await getPersonLabel());
+            const fmt = (c) => `  • ${label(c.channel)}: ${ratio(best(c))} ${metric(c)} · payback ${c.paybackMonths != null ? `${c.paybackMonths}mo` : "—"} · CAC ${money(c.cac)} · ${c.customers.toLocaleString()} ${person.plural}`;
             const lines = [
-                `${APEX} Channel economics — gross-margin LTV:CAC`,
+                `${APEX} Channel economics — LTGP:CAC where product cost is reported, LTV:CAC otherwise`,
                 "═".repeat(40),
             ];
             if (res.data?.needsReferee) {
@@ -1885,11 +1917,9 @@ export const toolDefinitions = {
             if (leverage.length > 0) {
                 lines.push("Leverage (owned / organic):", ...leverage.map(fmt), "");
             }
-            lines.push("3-5x LTV:CAC is healthy; <1x loses margin on every customer; >5x is likely underinvested.");
-            if (res.data?.grossMarginFromDefault) {
-                lines.push(`(Using a default ${res.data.grossMargin != null
-                    ? `${Math.round(res.data.grossMargin * 100)}%`
-                    : ""} gross margin — set your real margin in workspace settings to sharpen this.)`);
+            lines.push(`3-5x is healthy; <1x loses money on every ${person.label}; >5x is likely underinvested.`);
+            if (ranked.some((c) => c.ltgpCac === null && c.ltvCac !== null)) {
+                lines.push(`(Channels above marked LTV:CAC are measured on revenue. Send product.unit_cost on purchase events and Apex reports LTGP:CAC for them too — the same read with cost of goods netted out.)`);
             }
             return { content: [{ type: "text", text: lines.join("\n") }] };
         },
@@ -1996,7 +2026,7 @@ export const toolDefinitions = {
     get_ecommerce_product_sales: {
         description: `${APEX} — E-commerce product sales: top products by revenue with the per-product view → add-to-cart → purchase funnel and refund counts. Products need a product_id on commerce events; never-wired signals are reported as unwired, not zero.`,
         schema: z.object({
-            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
             start: z
                 .string()
                 .optional()
@@ -2036,7 +2066,7 @@ export const toolDefinitions = {
     get_ecommerce_returns: {
         description: `${APEX} — E-commerce returns & refunds: refund rate (money back, order basis), return rate (goods back — separate metric, never summed), reason breakdown, refund cycle time, AOV, and repeat purchase. Refund data lands automatically from Stripe; return_requested / return_completed events power the goods-back story.`,
         schema: z.object({
-            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
             start: z
                 .string()
                 .optional()
@@ -2076,7 +2106,7 @@ export const toolDefinitions = {
     get_marketplace_metrics: {
         description: `${APEX} — Marketplace health across six pillars: liquidity (search→transaction, match rate, zero-result searches, unfulfilled demand), supply & demand balance, economics (GMV vs the take — fee_amount is the platform's revenue, GMV never inflates LTV), buyer retention, trust rates, and concentration risk. Sliceable by category / geo / price_band (low-volume slices are suppressed for privacy). Metrics whose events aren't wired come back as unwired hints, never fabricated zeros.`,
         schema: z.object({
-            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
             start: z
                 .string()
                 .optional()
@@ -2634,7 +2664,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     identify_user: {
-        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email/lead. Pass avatarUrl (a canonical attribute) to give the Contact a profile photo that renders across Apex — Customers list, detail page, and Live Customers widget.`,
+        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email. Pass avatarUrl (a canonical attribute) to give the Contact a profile photo that renders across Apex — the people list, detail page, and Live widget. The workspace's own word for a person (Customer / Lead / Client / User, from its vertical) is what its dashboard shows; use that word when reporting back.`,
         schema: z.object({
             email: z.string().describe("User email address"),
             name: z.string().optional().describe("User name"),
@@ -2649,10 +2679,11 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
                 metadata: { name, company, avatar_url: avatarUrl, ...metadata, source: "mcp" },
             });
+            const person = lowerPerson(await getPersonLabel());
             return {
                 content: [{
                         type: "text",
-                        text: `Identity stitched: ${email}${name ? ` (${name})` : ""}${company ? ` at ${company}` : ""}\nA lead record has been created/linked in Apex.`,
+                        text: `Identity stitched: ${email}${name ? ` (${name})` : ""}${company ? ` at ${company}` : ""}\nA ${person.label} record has been created/linked in Apex.`,
                     }],
             };
         },
@@ -2916,7 +2947,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, and a one-line body preview so you can disambiguate similar titles without opening each one. 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.",
+        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).",
         schema: z.object({
             pipeline: z
                 .enum(["transactional", "marketing"])
@@ -2960,6 +2991,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                         : ["email"],
                     subject: typeof content.subject === "string" ? content.subject : "",
                     bodyPreview: String(bodyPreview),
+                    controlState: typeof comm.controlState === "string" ? comm.controlState : "none",
                     triggerEventId: typeof comm.triggerEventId === "string"
                         ? comm.triggerEventId
                         : "",
@@ -2988,7 +3020,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 const preview = r.bodyPreview
                     ? `\n  ${r.bodyPreview.slice(0, 120)}`
                     : "";
-                return `• ${r.title} (v${r.version}) — ${r.pipeline} — ${r.channels.join("/")} — ${r.status}\n  subject: ${r.subject || "(none)"}${preview}\n  id: ${r.id}`;
+                const control = r.controlState && r.controlState !== "none"
+                    ? ` — control: ${r.controlState}`
+                    : "";
+                return `• ${r.title} (v${r.version}) — ${r.pipeline} — ${r.channels.join("/")} — ${r.status}${control}\n  subject: ${r.subject || "(none)"}${preview}\n  id: ${r.id}`;
             })
                 .join("\n\n");
             return {
@@ -3002,13 +3037,21 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     edit_communication: {
-        description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update. For blank/builder comms, the headline/body/ctaLabel/ctaUrl slots are synced into the rendered email body — verify with preview_communication.",
+        description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update. For blank/builder comms, the headline/body/ctaLabel/ctaUrl slots are synced into the rendered email body — verify with preview_communication.\n\nA communication's Control is protected when it won an experiment or a published journey is sending it. Editing it then requires `intent`: \"compete\" adds your edit as a variant and measures it against the current content (nothing changes for recipients yet); \"replace\" makes your edit what everyone receives and supersedes any prior win. WHEN IN DOUBT, USE \"compete\" — it is recoverable, \"replace\" discards a measured result permanently. The server returns 409 intent_required with both options if you omit it.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to update"),
             subject: z.string().optional().describe("New email subject line"),
             slots: z.record(z.string()).optional().describe("Content overrides: headline, body, ctaLabel, ctaUrl. These now sync into the rendered email body (not just metadata)."),
             channels: z.array(z.string()).optional().describe("Channels: email, in_app_push, mobile_push"),
             status: z.enum(["draft", "active", "paused"]).optional().describe("Communication status"),
+            intent: z
+                .enum(["compete", "replace"])
+                .optional()
+                .describe('How to apply the edit when the Control is protected. "compete" = add it as a variant and run it as an experiment against the current content (safe default; the current content keeps sending). "replace" = update what everyone receives, superseding any prior win. Required only when the comm won an experiment or is live in a published journey.'),
+            confirmLiveExperiment: z
+                .boolean()
+                .optional()
+                .describe("Edit a communication that is the treatment in a RUNNING experiment. This marks that experiment invalid and excludes its result from the belief graph. Only pass true when the user has explicitly accepted losing the experiment."),
         }),
         handler: async (args) => {
             const body = {};
@@ -3016,6 +3059,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 body.status = args.status;
             if (args.channels)
                 body.channels = args.channels;
+            if (args.intent)
+                body.intent = args.intent;
+            if (args.confirmLiveExperiment)
+                body.confirmLiveExperiment = true;
             const content = {};
             if (args.subject)
                 content.subject = args.subject;
@@ -3023,8 +3070,94 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 content.slots = args.slots;
             if (Object.keys(content).length)
                 body.content = content;
-            const data = await apiPatch(`/api/communications/${args.communicationId}`, body);
-            return { content: [{ type: "text", text: `Communication updated.\n\n${JSON.stringify(data, null, 2)}` }] };
+            try {
+                const data = await apiPatch(`/api/communications/${args.communicationId}`, body);
+                // The comm may be protected without the edit being blocked (draft saves
+                // defer the question to publish). Carry the server's advisory through
+                // so the agent knows a decision is coming rather than meeting it later.
+                const advisory = typeof data?.controlAdvisory === "string"
+                    ? `\n\n${data.controlAdvisory}`
+                    : "";
+                return { content: [{ type: "text", text: `Communication updated.${advisory}\n\n${JSON.stringify(data, null, 2)}` }] };
+            }
+            catch (err) {
+                const guidance = controlGateGuidanceFor(err, {
+                    toolName: "edit_communication",
+                    communicationId: args.communicationId,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: guidance ?? `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    },
+    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.",
+        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.'),
+            confirmLiveExperiment: z
+                .boolean()
+                .optional()
+                .describe("Publish over a communication that is the treatment in a RUNNING experiment. Marks that experiment invalid and excludes its result from the belief graph. Only pass true when the user has explicitly accepted losing the experiment."),
+            hostJourneyId: z
+                .string()
+                .optional()
+                .describe("Which published journey hosts the experiment. Only needed after a 409 ambiguous_experiment_host, using one of the returned candidate ids."),
+        }),
+        handler: async (args) => {
+            const body = {};
+            if (args.intent)
+                body.intent = args.intent;
+            if (args.confirmLiveExperiment)
+                body.confirmLiveExperiment = true;
+            if (args.hostJourneyId)
+                body.hostJourneyId = args.hostJourneyId;
+            try {
+                const data = await apiPost(`/api/communications/${args.communicationId}/publish`, body);
+                const lines = [];
+                if (data.published === false) {
+                    lines.push("Nothing to publish — no unpublished changes.");
+                }
+                else {
+                    lines.push(`Published version ${data.version ?? "?"}.`);
+                }
+                if (data.repinned?.length) {
+                    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}`)}`);
+                }
+                else if (data.experimentNotStarted) {
+                    lines.push(notStartedExplanation(data.experimentNotStarted));
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            catch (err) {
+                const guidance = controlGateGuidanceFor(err, {
+                    toolName: "publish_communication",
+                    communicationId: args.communicationId,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: guidance ??
+                                `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
         },
     },
     preview_communication: {
@@ -4238,6 +4371,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             }
             const json = await apiGet(`/api/workspaces/${encodeURIComponent(workspaceKey)}/readiness`);
             const d = json.data;
+            const person = lowerPerson(await getPersonLabel());
             const eventLines = d.events.map((e) => `- ${e.name}: ${e.tier} (${e.count.toLocaleString()} events, platforms: ${e.platforms.join("/") || "—"})${e.observedFields?.length ? ` — fields seen: ${e.observedFields.join(", ")}` : ""}`);
             const traitLines = d.traits.map((t) => `- ${t.name}: ${t.present ? "arriving" : "not seen"}${t.inferredType ? ` (${t.inferredType})` : ""}`);
             const sourceLines = d.sources.map((s) => `- ${s.name} (${s.kind}): ${s.status}${s.lastSeenAt ? ` — last event ${s.lastSeenAt}` : ""}`);
@@ -4249,7 +4383,9 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             ];
             const milestones = [
                 d.milestones.firstEventAt ? `First event: ${d.milestones.firstEventAt}` : "First event: not yet",
-                d.milestones.firstIdentifiedAt ? `First identified customer: ${d.milestones.firstIdentifiedAt}` : "First identified customer: not yet",
+                d.milestones.firstIdentifiedAt
+                    ? `First identified ${person.label}: ${d.milestones.firstIdentifiedAt}`
+                    : `First identified ${person.label}: not yet`,
             ];
             return {
                 content: [{
@@ -4404,11 +4540,23 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         description: `${APEX} — One-shot health check of every connected integration (last sync, status). Use before adding a feature that depends on a connector.`,
         schema: z.object({}),
         handler: async () => {
-            const connectors = await apiGet("/api/connectors");
+            // GET /api/integrations is the connector LIST. `/api/connectors/*` only
+            // has per-type auth + callback routes, so the old path 404'd and this
+            // tool reported "No connected integrations" for every workspace.
+            const connectors = await apiGet("/api/integrations");
             const list = Array.isArray(connectors) ? connectors : [];
             const connected = list.filter((c) => c.isConnected || c.status === "connected");
             if (connected.length === 0) {
-                return { content: [{ type: "text", text: "No connected integrations." }] };
+                // Say which of the two it is. `apiGet` throws on a failed call, so
+                // reaching here means the list really came back and really was empty.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No connected integrations (the workspace returned ${list.length} available connector${list.length === 1 ? "" : "s"}, none connected).`,
+                        },
+                    ],
+                };
             }
             const lines = connected.map((c) => `- ${c.name ?? c.type}: ${c.status ?? "connected"}${c.lastSyncAt ? ` (last sync ${c.lastSyncAt})` : ""}`);
             return { content: [{ type: "text", text: `# Integration health\n${lines.join("\n")}` }] };
@@ -4436,20 +4584,35 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         }),
         handler: async (args) => {
             const apexAuthed = Boolean(getActiveWorkspace());
+            /**
+             * "unknown" is a distinct state from false. These checks used to collapse
+             * a failed API call into "not installed", so a 404 (this tool called a
+             * path that never existed until 2026-08-03), an expired key, and a
+             * genuinely uninstalled GitHub App were indistinguishable — and the
+             * agent would tell the developer to install an app they already had.
+             */
             let githubAppInstalled = false;
             let currentRepoWritable = false;
+            const checkErrors = [];
+            const note = (what, err) => checkErrors.push(`${what}: ${err instanceof Error ? err.message : String(err)}`);
             try {
-                const connectors = await apiGet("/api/connectors");
+                const connectors = await apiGet("/api/integrations");
                 const list = Array.isArray(connectors) ? connectors : [];
                 githubAppInstalled = list.some((c) => c.type === "github" && (c.isConnected || c.status === "connected"));
             }
-            catch { /* unauth or unreachable */ }
-            if (args.repo && githubAppInstalled) {
+            catch (err) {
+                githubAppInstalled = "unknown";
+                note("GitHub App check failed", err);
+            }
+            if (args.repo && githubAppInstalled !== false) {
                 try {
                     const auto = await apiGet("/api/graduation-pipeline/automation");
                     currentRepoWritable = (auto.data?.writeRepos ?? []).includes(args.repo);
                 }
-                catch { /* ignore */ }
+                catch (err) {
+                    currentRepoWritable = "unknown";
+                    note("Repo write opt-in check failed", err);
+                }
             }
             const readiness = {
                 apexAuthed,
@@ -4457,7 +4620,13 @@ _Suggest the next step the user should tackle based on what's incomplete in the
                 currentRepoWritable,
                 // The agent verifies these locally (presence of @apex-inc/sdk + repo access).
                 sdkInstalled: "check-locally",
-                currentRepoAuthorized: githubAppInstalled ? "check-locally" : false,
+                currentRepoAuthorized: githubAppInstalled === false ? false : "check-locally",
+                ...(checkErrors.length > 0
+                    ? {
+                        checkErrors,
+                        guidance: "A check that failed is NOT a check that came back negative. Report the error to the developer and resolve it before telling them anything is missing or unconfigured.",
+                    }
+                    : {}),
             };
             return { content: [{ type: "text", text: JSON.stringify(readiness, null, 2) }] };
         },