@sentientui/mcp 0.4.1 → 0.5.0

package/dist/{chunk-ZXI3OZKA.js → chunk-QH3RMHLM.js}

@@ -70,14 +70,29 @@ function createProjectGuidance(err) {
   }
 }
 function registerProjectTools(server, client) {
-  server.tool(
+  server.registerTool(
     "create_project",
-    "Create a NEW SentientUI project (onboarding). Returns the project id and its pk_ public key for the SDK. Requires an account login: this works when connected via OAuth (the hosted MCP URL) but NOT with a project-scoped sk_ server key or an anonymous demo token. After it succeeds, call get_integration_guide and help the user install @sentientui/react with the returned key.",
     {
-      name: z.string().min(1).describe("Human-readable project name"),
-      contextType: z.enum(["saas", "ecommerce", "marketing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
-      framework: z.enum(["next-app", "next-pages", "react", "core"]).optional().describe("Frontend framework, used to tailor setup; defaults to next-app"),
-      websiteUrl: z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
+      title: "Create project",
+      description: "Create a NEW SentientUI project (onboarding). Returns the project id and its pk_ public key for the SDK. Requires an account login: this works when connected via OAuth (the hosted MCP URL) but NOT with a project-scoped sk_ server key or an anonymous demo token. After it succeeds, call get_integration_guide and help the user install @sentientui/react with the returned key.",
+      inputSchema: {
+        name: z.string().min(1).describe("Human-readable project name"),
+        contextType: z.enum(["saas", "ecommerce", "marketing", "internal"]).optional().describe("What kind of product this is; defaults to saas"),
+        framework: z.enum(["next-app", "next-pages", "react", "core"]).optional().describe("Frontend framework, used to tailor setup; defaults to next-app"),
+        websiteUrl: z.string().optional().describe("Production site origin to allow-list so the SDK's events aren't origin-blocked on day one")
+      },
+      outputSchema: {
+        projectId: z.string().describe("The new project UUID"),
+        publicKey: z.string().describe("The pk_ public key to configure the SDK with"),
+        name: z.string().describe("The project name"),
+        contextType: z.string().describe("The resolved context type")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
     },
     async ({ name, contextType, framework, websiteUrl }) => {
       try {
@@ -87,15 +102,22 @@ function registerProjectTools(server, client) {
           framework,
           origin: websiteUrl
         });
+        const resolvedContextType = contextType ?? "saas";
         return {
           content: [{
             type: "text",
             text: [
-              `Created project "${name}" (id: ${created.id}, type: ${contextType ?? "saas"}).`,
+              `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
               `Public key: ${created.apiKey}`,
               `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
             ].join("\n")
-          }]
+          }],
+          structuredContent: {
+            projectId: created.id,
+            publicKey: created.apiKey,
+            name,
+            contextType: resolvedContextType
+          }
         };
       } catch (err) {
         if (err instanceof ApiError) {
@@ -108,22 +130,65 @@ function registerProjectTools(server, client) {
       }
     }
   );
-  server.tool(
+  server.registerTool(
     "list_projects",
-    "List all SentientUI projects for the authenticated account.",
-    {},
+    {
+      title: "List projects",
+      description: "List all SentientUI projects for the authenticated account.",
+      inputSchema: {},
+      outputSchema: {
+        projects: z.array(
+          z.object({
+            id: z.string().describe("Project UUID"),
+            name: z.string(),
+            contextType: z.string(),
+            createdAt: z.string().describe("ISO date (YYYY-MM-DD)")
+          })
+        ).describe("All projects for the account (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async () => {
       const projects = await client.get("/projects");
       const text = projects.length === 0 ? "No projects found." : projects.map(
         (p) => `- ${p.name} (id: ${p.id}, type: ${p.context_type}, created: ${p.created_at.slice(0, 10)})`
       ).join("\n");
-      return { content: [{ type: "text", text }] };
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+          projects: projects.map((p) => ({
+            id: p.id,
+            name: p.name,
+            contextType: p.context_type,
+            createdAt: p.created_at.slice(0, 10)
+          }))
+        }
+      };
     }
   );
-  server.tool(
+  server.registerTool(
     "get_project_stats",
-    "Get health stats for a project: event volume, session count, agent calls, and status.",
-    { projectId: projectIdSchema },
+    {
+      title: "Project health stats",
+      description: "Get health stats for a project: event volume, session count, agent calls, and status.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        status: z.string().describe("Overall project health status"),
+        events24h: z.number().describe("Events in the last 24 hours"),
+        sessions24h: z.number().describe("Sessions in the last 24 hours"),
+        agentCalls: z.number().describe("Total agent (MCP/API) calls"),
+        lastEventAt: z.string().nullable().describe("ISO timestamp of the last event, or null")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const stats = await client.get(`/projects/${id}/health`);
@@ -134,7 +199,16 @@ function registerProjectTools(server, client) {
         `Agent calls (total): ${stats.agentCalls}`,
         `Last event: ${stats.lastEventAt ?? "never"}`
       ].join("\n");
-      return { content: [{ type: "text", text }] };
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+          status: stats.status,
+          events24h: stats.events24h,
+          sessions24h: stats.sessions24h,
+          agentCalls: stats.agentCalls,
+          lastEventAt: stats.lastEventAt
+        }
+      };
     }
   );
 }
@@ -143,37 +217,97 @@ function registerProjectTools(server, client) {
 import { z as z2 } from "zod";
 var projectIdSchema2 = z2.string().uuid().describe("The project UUID");
 function registerComponentTools(server, client) {
-  server.tool(
+  server.registerTool(
     "list_components",
-    "List all adaptive components in a project with variant counts and impression totals.",
-    { projectId: projectIdSchema2 },
+    {
+      title: "List components",
+      description: "List all adaptive components in a project with variant counts and impression totals.",
+      inputSchema: { projectId: projectIdSchema2 },
+      outputSchema: {
+        components: z2.array(
+          z2.object({
+            componentId: z2.string(),
+            variantCount: z2.number(),
+            impressions: z2.number(),
+            conversions: z2.number()
+          })
+        ).describe("Adaptive components in the project (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const components = await client.get(`/projects/${id}/components`);
+      const structuredContent = {
+        components: components.map((c) => ({
+          componentId: c.component_id,
+          variantCount: c.variants.length,
+          impressions: c.total_impressions,
+          conversions: c.total_conversions
+        }))
+      };
       if (!components.length) {
-        return { content: [{ type: "text", text: "No components found for this project." }] };
+        return {
+          content: [{ type: "text", text: "No components found for this project." }],
+          structuredContent
+        };
       }
       const text = components.map(
         (c) => `- ${c.component_id}: ${c.variants.length} variants, ${c.total_impressions} impressions, ${c.total_conversions} conversions`
       ).join("\n");
-      return { content: [{ type: "text", text }] };
+      return { content: [{ type: "text", text }], structuredContent };
     }
   );
-  server.tool(
+  server.registerTool(
     "get_variant_performance",
-    "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
-    { projectId: projectIdSchema2 },
+    {
+      title: "Variant performance",
+      description: "Get CVR and momentum for all variants in a project over the last 7 days vs prior 7 days.",
+      inputSchema: { projectId: projectIdSchema2 },
+      outputSchema: {
+        variants: z2.array(
+          z2.object({
+            variantId: z2.string(),
+            currentCvr: z2.number().describe("Conversion rate over the last 7 days (0-1)"),
+            priorCvr: z2.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            deltaPp: z2.number().describe("Change in percentage points"),
+            momentum: z2.string().describe("Momentum direction: gaining, losing, or stable")
+          })
+        ).describe("Per-variant performance (empty if no data yet)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/trends`);
+      const momentumMap = new Map((data.momentum ?? []).map((m) => [m.variantId, m.direction]));
+      const structuredContent = {
+        variants: (data.cvr ?? []).map((v) => ({
+          variantId: v.variantId,
+          currentCvr: v.currentCvr,
+          priorCvr: v.priorCvr,
+          deltaPp: v.deltaPp,
+          momentum: momentumMap.get(v.variantId) ?? "stable"
+        }))
+      };
       if (!data.cvr?.length) {
-        return { content: [{ type: "text", text: "No variant data available yet." }] };
+        return {
+          content: [{ type: "text", text: "No variant data available yet." }],
+          structuredContent
+        };
       }
-      const momentumMap = new Map(data.momentum.map((m) => [m.variantId, m.direction]));
       const text = data.cvr.map(
         (v) => `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${momentumMap.get(v.variantId) ?? "stable"})`
       ).join("\n");
-      return { content: [{ type: "text", text }] };
+      return { content: [{ type: "text", text }], structuredContent };
     }
   );
 }
@@ -182,28 +316,63 @@ function registerComponentTools(server, client) {
 import { z as z3 } from "zod";
 var projectIdSchema3 = z3.string().uuid().describe("The project UUID");
 function registerInsightTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_insights",
-    "Get the latest AI-generated insights: narrator observations and (Growth tier) advisor recommendations.",
-    { projectId: projectIdSchema3 },
+    {
+      title: "Get insights",
+      description: "Get the latest AI-generated insights: narrator observations and (Growth tier) advisor recommendations.",
+      inputSchema: { projectId: projectIdSchema3 },
+      outputSchema: {
+        status: z3.enum(["ok", "empty"]).describe("Whether insights exist yet"),
+        observations: z3.array(z3.string()).describe("Narrator observations"),
+        recommendations: z3.array(z3.string()).describe("Advisor recommendations (Growth tier)"),
+        isStale: z3.boolean().describe("True when the insights are older than ~6h"),
+        generatedAt: z3.string().nullable().describe("ISO timestamp the insights were generated, or null")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/insights`);
       if (data.status === "empty") {
-        return { content: [{ type: "text", text: "No insights generated yet. Use refresh_insights to generate." }] };
+        return {
+          content: [{ type: "text", text: "No insights generated yet. Use refresh_insights to generate." }],
+          structuredContent: {
+            status: "empty",
+            observations: [],
+            recommendations: [],
+            isStale: false,
+            generatedAt: null
+          }
+        };
       }
+      const observations = data.narratorBullets ?? [];
+      const recommendations = data.advisorBullets ?? [];
       const lines = [];
       if (data.isStale) lines.push("\u26A0 Insights are stale (>6h old). Consider calling refresh_insights.");
       if (data.generatedAt) lines.push(`Generated: ${new Date(data.generatedAt).toUTCString()}`);
       lines.push("");
       lines.push("Observations:");
-      (data.narratorBullets ?? []).forEach((b) => lines.push(`- ${b}`));
-      if (data.advisorBullets?.length) {
+      observations.forEach((b) => lines.push(`- ${b}`));
+      if (recommendations.length) {
         lines.push("");
         lines.push("Recommendations:");
-        data.advisorBullets.forEach((b) => lines.push(`- ${b}`));
+        recommendations.forEach((b) => lines.push(`- ${b}`));
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: {
+          status: "ok",
+          observations,
+          recommendations,
+          isStale: data.isStale ?? false,
+          generatedAt: data.generatedAt ?? null
+        }
+      };
     }
   );
 }
@@ -212,15 +381,46 @@ function registerInsightTools(server, client) {
 import { z as z4 } from "zod";
 var projectIdSchema4 = z4.string().uuid().describe("The project UUID");
 function registerPersonaTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_persona_breakdown",
-    "Get the distribution of visitor persona clusters with session counts and reliability scores.",
-    { projectId: projectIdSchema4 },
+    {
+      title: "Persona breakdown",
+      description: "Get the distribution of visitor persona clusters with session counts and reliability scores.",
+      inputSchema: { projectId: projectIdSchema4 },
+      outputSchema: {
+        totalSessions: z4.number().describe("Total sessions across all clusters"),
+        clusters: z4.array(
+          z4.object({
+            label: z4.string(),
+            sessionCount: z4.number(),
+            sharePct: z4.number().describe("Share of total traffic (0-100)"),
+            reliability: z4.number().describe("Average cluster reliability (0-1)")
+          })
+        ).describe("Persona clusters (empty until enough visitor data)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/portraits`);
+      const structuredContent = {
+        totalSessions: data.totalSessions,
+        clusters: data.clusters.map((c) => ({
+          label: c.label,
+          sessionCount: c.sessionCount,
+          sharePct: data.totalSessions > 0 ? c.sessionCount / data.totalSessions * 100 : 0,
+          reliability: c.avgReliability
+        }))
+      };
       if (!data.clusters.length) {
-        return { content: [{ type: "text", text: "No persona clusters yet. More visitor data is needed." }] };
+        return {
+          content: [{ type: "text", text: "No persona clusters yet. More visitor data is needed." }],
+          structuredContent
+        };
       }
       const lines = [
         `Total sessions: ${data.totalSessions}`,
@@ -231,7 +431,7 @@ function registerPersonaTools(server, client) {
           return `- ${c.label}: ${c.sessionCount} sessions (${pct.toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`;
         })
       ];
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     }
   );
 }
@@ -240,22 +440,63 @@ function registerPersonaTools(server, client) {
 import { z as z5 } from "zod";
 var projectIdSchema5 = z5.string().uuid().describe("The project UUID");
 function registerGoalTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_goal_funnel",
-    "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
-    { projectId: projectIdSchema5 },
+    {
+      title: "Goal funnel",
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown.",
+      inputSchema: { projectId: projectIdSchema5 },
+      outputSchema: {
+        goals: z5.array(
+          z5.object({
+            goalName: z5.string(),
+            hits: z5.number(),
+            uniqueSessions: z5.number(),
+            conversionRate: z5.number().describe("Unique-session conversion rate (0-1)"),
+            variants: z5.array(
+              z5.object({
+                componentId: z5.string(),
+                variantId: z5.string(),
+                completionRate: z5.number().describe("Completion rate per assigned session (0-1)")
+              })
+            ).describe("Per-variant breakdown")
+          })
+        ).describe("Configured goals (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/goals`);
+      const structuredContent = {
+        goals: data.goals.map((g) => ({
+          goalName: g.goalName,
+          hits: g.hits,
+          uniqueSessions: g.uniqueSessions,
+          conversionRate: g.pct,
+          variants: g.variants.map((v) => ({
+            componentId: v.componentId,
+            variantId: v.variantId,
+            completionRate: v.completionRate
+          }))
+        }))
+      };
       if (!data.goals.length) {
-        return { content: [{ type: "text", text: "No goals configured for this project." }] };
+        return {
+          content: [{ type: "text", text: "No goals configured for this project." }],
+          structuredContent
+        };
       }
       const lines = data.goals.flatMap((g) => [
         `${g.goalName}: ${g.hits} hits, ${g.uniqueSessions} unique sessions, ${(g.pct * 100).toFixed(1)}% conversion`,
         ...g.variants.map((v) => `  ${v.componentId}/${v.variantId}: ${(v.completionRate * 100).toFixed(1)}% per assigned session`),
         ""
       ]);
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent };
     }
   );
 }
@@ -264,20 +505,47 @@ function registerGoalTools(server, client) {
 import { z as z6 } from "zod";
 var projectIdSchema6 = z6.string().uuid().describe("The project UUID");
 function registerGuardrailTools(server, client) {
-  server.tool(
+  server.registerTool(
     "list_guardrail_events",
-    "List variants currently paused by the guardrail in the last 24 hours.",
-    { projectId: projectIdSchema6 },
+    {
+      title: "List guardrail events",
+      description: "List variants currently paused by the guardrail in the last 24 hours.",
+      inputSchema: { projectId: projectIdSchema6 },
+      outputSchema: {
+        events: z6.array(
+          z6.object({
+            componentId: z6.string(),
+            variantIds: z6.array(z6.string()).describe("Variants paused by the guardrail"),
+            pausedAt: z6.string().nullable().describe("ISO timestamp the pause fired, or null")
+          })
+        ).describe("Guardrail events in the last 24h (empty if none)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/guardrail-events`);
+      const structuredContent = {
+        events: data.guardrailEvents.map((e) => ({
+          componentId: e.componentId,
+          variantIds: e.variantIds,
+          pausedAt: e.pausedAt
+        }))
+      };
       if (!data.guardrailEvents.length) {
-        return { content: [{ type: "text", text: "No active guardrail events in the last 24 hours." }] };
+        return {
+          content: [{ type: "text", text: "No active guardrail events in the last 24 hours." }],
+          structuredContent
+        };
       }
       const lines = data.guardrailEvents.map(
         (e) => `- ${e.componentId}: variants [${e.variantIds.join(", ")}] paused${e.pausedAt ? ` at ${e.pausedAt}` : ""}`
       );
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     }
   );
 }
@@ -286,20 +554,49 @@ function registerGuardrailTools(server, client) {
 import { z as z7 } from "zod";
 var projectIdSchema7 = z7.string().uuid().describe("The project UUID");
 function registerLayoutTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_layout_stats",
-    "Get per-persona section layout rankings and bandit reward weights.",
-    { projectId: projectIdSchema7 },
+    {
+      title: "Layout stats",
+      description: "Get per-persona section layout rankings and bandit reward weights.",
+      inputSchema: { projectId: projectIdSchema7 },
+      outputSchema: {
+        layouts: z7.array(
+          z7.object({
+            persona: z7.string(),
+            layoutOrder: z7.array(z7.string()).describe("Ranked section order for this persona"),
+            pulls: z7.number().describe("Number of times this arm was served"),
+            avgReward: z7.number().describe("Average bandit reward weight")
+          })
+        ).describe("Per-persona layout rankings (empty until enough sessions)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       const stats = await client.get(`/projects/${id}/layout-stats`);
+      const structuredContent = {
+        layouts: stats.map((s) => ({
+          persona: s.persona,
+          layoutOrder: s.layoutOrder,
+          pulls: s.pulls,
+          avgReward: s.avgReward
+        }))
+      };
       if (!stats.length) {
-        return { content: [{ type: "text", text: "No layout data yet. More visitor sessions are needed." }] };
+        return {
+          content: [{ type: "text", text: "No layout data yet. More visitor sessions are needed." }],
+          structuredContent
+        };
       }
       const text = stats.map(
         (s) => `- ${s.persona}: [${s.layoutOrder.join(" \u2192 ")}] (avg reward: ${s.avgReward.toFixed(2)}, ${s.pulls} pulls)`
       ).join("\n");
-      return { content: [{ type: "text", text }] };
+      return { content: [{ type: "text", text }], structuredContent };
     }
   );
 }
@@ -308,14 +605,30 @@ function registerLayoutTools(server, client) {
 import { z as z8 } from "zod";
 var projectIdSchema8 = z8.string().uuid().describe("The project UUID");
 function registerVariantWriteTools(server, client) {
-  server.tool(
+  server.registerTool(
     "create_variant",
-    "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
     {
-      projectId: projectIdSchema8,
-      componentId: z8.string().describe("The component ID to add a variant to"),
-      displayName: z8.string().describe("Human-readable name for the new variant"),
-      content: z8.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+      title: "Create managed variant",
+      description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
+      inputSchema: {
+        projectId: projectIdSchema8,
+        componentId: z8.string().describe("The component ID to add a variant to"),
+        displayName: z8.string().describe("Human-readable name for the new variant"),
+        content: z8.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+      },
+      outputSchema: {
+        variantId: z8.string().describe("The new variant ID"),
+        displayName: z8.string(),
+        componentId: z8.string(),
+        state: z8.literal("draft").describe("New managed variants start in draft state"),
+        hasContent: z8.boolean().describe("Whether text content was provided at creation")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
     },
     async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
@@ -328,17 +641,38 @@ function registerVariantWriteTools(server, client) {
         content: [{
           type: "text",
           text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is in draft state \u2014 activate it from the dashboard. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
-        }]
+        }],
+        structuredContent: {
+          variantId: result.variantId,
+          displayName: result.displayName,
+          componentId,
+          state: "draft",
+          hasContent: Boolean(content)
+        }
       };
     }
   );
-  server.tool(
+  server.registerTool(
     "pause_variant",
-    "Pause a variant, stopping traffic from being assigned to it.",
     {
-      projectId: projectIdSchema8,
-      componentId: z8.string().describe("The component ID"),
-      variantId: z8.string().describe("The variant ID to pause")
+      title: "Pause variant",
+      description: "Pause a variant, stopping traffic from being assigned to it.",
+      inputSchema: {
+        projectId: projectIdSchema8,
+        componentId: z8.string().describe("The component ID"),
+        variantId: z8.string().describe("The variant ID to pause")
+      },
+      outputSchema: {
+        variantId: z8.string(),
+        componentId: z8.string(),
+        paused: z8.literal(true).describe("The variant is now paused")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async ({ projectId, componentId, variantId }) => {
       const id = encodeURIComponent(projectId);
@@ -347,14 +681,28 @@ function registerVariantWriteTools(server, client) {
         content: [{
           type: "text",
           text: `Variant ${variantId} in component ${componentId} has been paused. No new traffic will be assigned to it.`
-        }]
+        }],
+        structuredContent: { variantId, componentId, paused: true }
       };
     }
   );
-  server.tool(
+  server.registerTool(
     "refresh_insights",
-    "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
-    { projectId: projectIdSchema8 },
+    {
+      title: "Refresh insights",
+      description: "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
+      inputSchema: { projectId: projectIdSchema8 },
+      outputSchema: {
+        projectId: z8.string(),
+        status: z8.literal("generating").describe("Generation has been triggered")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
     async ({ projectId }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/insights/refresh`);
@@ -362,7 +710,8 @@ function registerVariantWriteTools(server, client) {
         content: [{
           type: "text",
           text: `Insights are generating for project ${projectId}. Call get_insights in ~15 seconds to see the results.`
-        }]
+        }],
+        structuredContent: { projectId, status: "generating" }
       };
     }
   );
@@ -435,12 +784,28 @@ async function settled(p) {
   }
 }
 function registerVariantBriefTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_variant_brief",
-    "Get an insight-driven brief for creating a new CODE-NATIVE variant of a component. Returns current variant performance, audience, insights, a data-sufficiency assessment (with a best-practice fallback when there is no data yet), and step-by-step instructions for writing the variant in the customer's code. Use this instead of create_variant when the variant will live in the codebase.",
     {
-      projectId: projectIdSchema9,
-      componentId: z9.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+      title: "Variant brief",
+      description: "Get an insight-driven brief for creating a new CODE-NATIVE variant of a component. Returns current variant performance, audience, insights, a data-sufficiency assessment (with a best-practice fallback when there is no data yet), and step-by-step instructions for writing the variant in the customer's code. Use this instead of create_variant when the variant will live in the codebase.",
+      inputSchema: {
+        projectId: projectIdSchema9,
+        componentId: z9.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+      },
+      outputSchema: {
+        componentId: z9.string(),
+        contextType: z9.string().describe("The project's context type (or 'unknown')"),
+        dataState: z9.enum(["sufficient", "collecting", "empty"]).describe("Data-sufficiency assessment"),
+        existingVariantIds: z9.array(z9.string()).describe("Variant IDs already in use (do not reuse)"),
+        priors: z9.array(z9.string()).describe("Best-practice priors applied for this context type"),
+        markdown: z9.string().describe("The full variant brief in Markdown")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async ({ projectId, componentId }) => {
       const id = encodeURIComponent(projectId);
@@ -531,7 +896,18 @@ function registerVariantBriefTools(server, client) {
       lines.push("5. Commit, push, and deploy. Optionally enable shadow mode for this component first if you want to validate before serving real traffic.");
       lines.push("");
       lines.push("Make the change reflect the data sufficiency above: data-driven when SUFFICIENT, best-practice-led when COLLECTING or EMPTY.");
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      const markdown = lines.join("\n");
+      return {
+        content: [{ type: "text", text: markdown }],
+        structuredContent: {
+          componentId,
+          contextType,
+          dataState,
+          existingVariantIds,
+          priors: priorsFor(contextType),
+          markdown
+        }
+      };
     }
   );
 }
@@ -547,12 +923,26 @@ async function settled2(p) {
   }
 }
 function registerTestBriefTools(server, client) {
-  server.tool(
+  server.registerTool(
     "get_test_brief",
-    "Get a ready-to-paste test for a SentientUI-wrapped component, populated with the component's real variants and goals. This project uses @sentientui/react/testing. Use this so your tests force a specific variant/layout deterministically and never break when the optimizer serves a different version. Returns a React Testing Library example plus the URL-param recipe for E2E (Playwright/Cypress).",
     {
-      projectId: projectIdSchema10,
-      componentId: z10.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+      title: "Test brief",
+      description: "Get a ready-to-paste test for a SentientUI-wrapped component, populated with the component's real variants and goals. This project uses @sentientui/react/testing. Use this so your tests force a specific variant/layout deterministically and never break when the optimizer serves a different version. Returns a React Testing Library example plus the URL-param recipe for E2E (Playwright/Cypress).",
+      inputSchema: {
+        projectId: projectIdSchema10,
+        componentId: z10.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+      },
+      outputSchema: {
+        componentId: z10.string(),
+        forcedVariantId: z10.string().describe("The non-control variant the example forces"),
+        goalName: z10.string().describe("The goal the example asserts fires"),
+        markdown: z10.string().describe("The full test brief in Markdown")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async ({ projectId, componentId }) => {
       const id = encodeURIComponent(projectId);
@@ -616,12 +1006,17 @@ function registerTestBriefTools(server, client) {
       lines.push("```ts");
       lines.push(`await page.goto('/?sentient_variant=${componentId}:${forcedId}');`);
       lines.push("```");
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      const markdown = lines.join("\n");
+      return {
+        content: [{ type: "text", text: markdown }],
+        structuredContent: { componentId, forcedVariantId: forcedId, goalName, markdown }
+      };
     }
   );
 }
 
 // src/tools/integration-guide.ts
+import { z as z11 } from "zod";
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
@@ -689,11 +1084,25 @@ Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, perso
 deterministic outcomes so tests never depend on what the optimizer serves.
 `;
 function registerIntegrationGuideTools(server) {
-  server.tool(
+  server.registerTool(
     "get_integration_guide",
-    "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
-    {},
-    async () => ({ content: [{ type: "text", text: GUIDE }] })
+    {
+      title: "Integration guide",
+      description: "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
+      inputSchema: {},
+      outputSchema: {
+        guide: z11.string().describe("The full integration guide in Markdown")
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => ({
+      content: [{ type: "text", text: GUIDE }],
+      structuredContent: { guide: GUIDE }
+    })
   );
 }