@sentientui/mcp 0.15.0 → 0.17.0

package/AGENTS.md

@@ -33,7 +33,7 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 | `create_project` | Onboard a new user: creates a project + returns its `pk_` key. Needs an account login (OAuth) — refuses `sk_` project keys and demo tokens. Follow with `get_integration_guide` |
 | `get_project_stats` | Health status + 24h event/session volume |
 | `list_components` | Components + variant counts + impression totals |
-| `get_variant_performance` | CVR 7d vs prior 7d + momentum direction |
+| `get_variant_performance` | CVR current vs prior window + momentum (range/from/to params; default 7d) |
 | `get_persona_breakdown` | Cluster distribution + avg reliability per cluster |
 | `get_goal_funnel` | Goal hit counts + per-variant completion rates |
 | `list_guardrail_events` | Auto-paused variants (last 24h) |

package/README.md

@@ -88,11 +88,11 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 | `create_project` | Create a new project and return its `pk_` public key (account login required — not usable with an `sk_` project key or demo token) |
 | `get_project_stats` | Events, sessions, agent calls, and health status |
 | `list_components` | All adaptive components with variant counts |
-| `get_variant_performance` | CVR, momentum, and impressions per variant (7d vs prior 7d) |
+| `get_variant_performance` | CVR, momentum, and impressions per variant (windowed: range 7d/30d/90d/all or from/to; default 7d vs prior 7d) |
 | `get_insights` | AI-generated narrator observations and advisor recommendations |
 | `refresh_insights` | Trigger fresh AI insight generation |
 | `get_persona_breakdown` | Visitor cluster distribution with reliability scores |
-| `get_goal_funnel` | Goal hit counts and conversion rates per variant |
+| `get_goal_funnel` | Goal hit counts and conversion rates per variant (windowed; default 30d) |
 | `list_goals` | Defined goals (id, role, event, status) — includes goals with no conversions yet, so agents can wire a dashboard-defined goal into code |
 | `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
 | `get_layout_stats` | Per-persona section layout rankings and reward weights |

package/dist/{chunk-3RJUYHO7.js → chunk-2E5M5ESK.js}

@@ -199,7 +199,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -331,6 +335,44 @@ import { z as z2 } from "zod";
 // src/tools/common.ts
 import { z } from "zod";
 var projectIdSchema = z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = z.object({
+  range: z.string(),
+  start: z.string().nullable(),
+  end: z.string().nullable(),
+  timezone: z.string(),
+  bucketUnit: z.string(),
+  retentionDays: z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -345,6 +387,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -516,8 +564,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "List all adaptive components in a project with variant counts and impression totals. Counts cover all retained data by default; pass range or from/to for a window.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: z3.array(
           z3.object({
@@ -526,7 +574,8 @@ function registerComponentTools(server, client) {
             impressions: z3.number(),
             conversions: z3.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -534,16 +583,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -561,19 +611,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       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: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: z3.array(
           z3.object({
             variantId: z3.string(),
-            currentCvr: z3.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: z3.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: z3.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: z3.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: z3.number().describe("Change in percentage points"),
             momentum: z3.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -581,10 +632,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a = data.momentum) != null ? _a : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -596,7 +647,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -605,12 +657,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a2;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -624,8 +678,11 @@ var EMPTY_REASON_TEXT = {
   awaiting_profiles: "Still building visitor profiles before visitors can be grouped.",
   no_variants: "Nothing to compare yet \u2014 no adaptive component is running.",
   nothing_moved: "Enough data, and nothing moved this period. That is a result.",
-  job_never_ran: "The analysis job has not run yet.",
-  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently."
+  // The stale/never-ran texts name the remedy: an agent that is not told about
+  // refresh_insights has no way to know it can fix this itself.
+  job_never_ran: "The analysis job has not run yet. Call refresh_insights to run it now.",
+  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently. Call refresh_insights to regenerate them.",
+  data_unavailable: "The project data could not be read just now \u2014 nothing is wrong with the setup. Retry shortly."
 };
 function registerInsightTools(server, client) {
   server.registerTool(
@@ -649,7 +706,14 @@ function registerInsightTools(server, client) {
         observations: z4.array(z4.string()).describe("Headlines of measured findings"),
         recommendations: z4.array(z4.string()).describe("Headlines of interpreted findings (Growth tier)"),
         isStale: z4.boolean().describe("True when the analysis has not run recently"),
-        generatedAt: z4.string().nullable().describe("ISO timestamp, or null")
+        generatedAt: z4.string().nullable().describe("ISO timestamp, or null"),
+        nextUnlock: z4.object({
+          tier: z4.string(),
+          needs: z4.string(),
+          have: z4.number(),
+          need: z4.number(),
+          surface: z4.string().nullable()
+        }).nullable().describe("The nearest gap that would raise the confidence tier, when there is one")
       },
       annotations: {
         readOnlyHint: true,
@@ -658,7 +722,7 @@ function registerInsightTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
-      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/evidence-report`);
       const findings = (_a = data.findings) != null ? _a : [];
@@ -670,17 +734,23 @@ function registerInsightTools(server, client) {
       const emptyReason = (_d = data.emptyReason) != null ? _d : null;
       const lines = [];
       if (emptyReason) lines.push((_e = EMPTY_REASON_TEXT[emptyReason]) != null ? _e : emptyReason);
-      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved.");
+      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved. Call refresh_insights to regenerate them.");
       if ((_f = data.interpretation) == null ? void 0 : _f.locked) {
         lines.push(`${data.interpretation.count || "Some"} recommendations are available on the Growth plan.`);
       } else if (((_g = data.interpretation) == null ? void 0 : _g.emptyReason) && !emptyReason) {
         lines.push(`Recommendations: ${(_h = EMPTY_REASON_TEXT[data.interpretation.emptyReason]) != null ? _h : data.interpretation.emptyReason}`);
       }
       if (data.generatedAt) lines.push(`Generated: ${new Date(data.generatedAt).toUTCString()}`);
+      const nextUnlock = (_i = data.nextUnlock) != null ? _i : null;
+      if (nextUnlock) {
+        const remaining = nextUnlock.need - nextUnlock.have;
+        const where = nextUnlock.surface ? `On ${nextUnlock.surface}: ` : "";
+        lines.push(`${where}${remaining} more ${nextUnlock.needs} would unlock the next confidence level (${nextUnlock.tier}).`);
+      }
       if (measured.length) {
         lines.push("", "Findings:");
         for (const f of measured) {
-          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${Math.round(f.provenance.coverage * 100)}% of visitors` : "";
+          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${f.provenance.coverage < 5e-3 ? "under 1%" : `${Math.round(f.provenance.coverage * 100)}%`} of visitors` : "";
           lines.push(`- [${f.tier}] ${f.headline} (${f.provenance.sample} ${f.provenance.denominatorLabel}${cov})`);
         }
       }
@@ -692,7 +762,7 @@ function registerInsightTools(server, client) {
         content: [{ type: "text", text: lines.join("\n").trim() || "No findings yet." }],
         structuredContent: {
           status: findings.length ? "ok" : "empty",
-          reached: (_i = data.reached) != null ? _i : "observed",
+          reached: (_j = data.reached) != null ? _j : "observed",
           findings: findings.map((f) => ({
             tier: f.tier,
             kind: f.kind,
@@ -705,7 +775,8 @@ function registerInsightTools(server, client) {
           observations,
           recommendations,
           isStale,
-          generatedAt: (_j = data.generatedAt) != null ? _j : null
+          generatedAt: (_k = data.generatedAt) != null ? _k : null,
+          nextUnlock
         }
       };
     })
@@ -779,8 +850,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: z6.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -801,7 +872,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -809,11 +881,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a = data.currency) != null ? _a : "USD",
         goals: data.goals.map((g) => {
           var _a2, _b2, _c;
@@ -841,6 +914,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a2;
         return [
@@ -849,7 +923,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1693,8 +1768,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: z14.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: z14.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: z14.object({ crawler: z14.number(), api: z14.number(), browser: z14.number() }),
         engines: z14.array(
@@ -1712,9 +1791,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1802,7 +1886,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.15.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -78,6 +78,44 @@ var import_zod2 = require("zod");
 // src/tools/common.ts
 var import_zod = require("zod");
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: import_zod.z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: import_zod.z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: import_zod.z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = import_zod.z.object({
+  range: import_zod.z.string(),
+  start: import_zod.z.string().nullable(),
+  end: import_zod.z.string().nullable(),
+  timezone: import_zod.z.string(),
+  bucketUnit: import_zod.z.string(),
+  retentionDays: import_zod.z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: import_zod.z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -92,6 +130,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -393,7 +437,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -522,8 +570,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "List all adaptive components in a project with variant counts and impression totals. Counts cover all retained data by default; pass range or from/to for a window.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: import_zod3.z.array(
           import_zod3.z.object({
@@ -532,7 +580,8 @@ function registerComponentTools(server, client) {
             impressions: import_zod3.z.number(),
             conversions: import_zod3.z.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -540,16 +589,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -567,19 +617,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       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: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: import_zod3.z.array(
           import_zod3.z.object({
             variantId: import_zod3.z.string(),
-            currentCvr: import_zod3.z.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: import_zod3.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: import_zod3.z.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: import_zod3.z.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: import_zod3.z.number().describe("Change in percentage points"),
             momentum: import_zod3.z.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -587,10 +638,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a2, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a2 = data.momentum) != null ? _a2 : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -602,7 +653,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a3 = momentumMap.get(v.variantId)) != null ? _a3 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -611,12 +663,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a3;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a3 = momentumMap.get(v.variantId)) != null ? _a3 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -630,8 +684,11 @@ var EMPTY_REASON_TEXT = {
   awaiting_profiles: "Still building visitor profiles before visitors can be grouped.",
   no_variants: "Nothing to compare yet \u2014 no adaptive component is running.",
   nothing_moved: "Enough data, and nothing moved this period. That is a result.",
-  job_never_ran: "The analysis job has not run yet.",
-  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently."
+  // The stale/never-ran texts name the remedy: an agent that is not told about
+  // refresh_insights has no way to know it can fix this itself.
+  job_never_ran: "The analysis job has not run yet. Call refresh_insights to run it now.",
+  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently. Call refresh_insights to regenerate them.",
+  data_unavailable: "The project data could not be read just now \u2014 nothing is wrong with the setup. Retry shortly."
 };
 function registerInsightTools(server, client) {
   server.registerTool(
@@ -655,7 +712,14 @@ function registerInsightTools(server, client) {
         observations: import_zod4.z.array(import_zod4.z.string()).describe("Headlines of measured findings"),
         recommendations: import_zod4.z.array(import_zod4.z.string()).describe("Headlines of interpreted findings (Growth tier)"),
         isStale: import_zod4.z.boolean().describe("True when the analysis has not run recently"),
-        generatedAt: import_zod4.z.string().nullable().describe("ISO timestamp, or null")
+        generatedAt: import_zod4.z.string().nullable().describe("ISO timestamp, or null"),
+        nextUnlock: import_zod4.z.object({
+          tier: import_zod4.z.string(),
+          needs: import_zod4.z.string(),
+          have: import_zod4.z.number(),
+          need: import_zod4.z.number(),
+          surface: import_zod4.z.string().nullable()
+        }).nullable().describe("The nearest gap that would raise the confidence tier, when there is one")
       },
       annotations: {
         readOnlyHint: true,
@@ -664,7 +728,7 @@ function registerInsightTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
-      var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+      var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/evidence-report`);
       const findings = (_a2 = data.findings) != null ? _a2 : [];
@@ -676,17 +740,23 @@ function registerInsightTools(server, client) {
       const emptyReason = (_d = data.emptyReason) != null ? _d : null;
       const lines = [];
       if (emptyReason) lines.push((_e = EMPTY_REASON_TEXT[emptyReason]) != null ? _e : emptyReason);
-      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved.");
+      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved. Call refresh_insights to regenerate them.");
       if ((_f = data.interpretation) == null ? void 0 : _f.locked) {
         lines.push(`${data.interpretation.count || "Some"} recommendations are available on the Growth plan.`);
       } else if (((_g = data.interpretation) == null ? void 0 : _g.emptyReason) && !emptyReason) {
         lines.push(`Recommendations: ${(_h = EMPTY_REASON_TEXT[data.interpretation.emptyReason]) != null ? _h : data.interpretation.emptyReason}`);
       }
       if (data.generatedAt) lines.push(`Generated: ${new Date(data.generatedAt).toUTCString()}`);
+      const nextUnlock = (_i = data.nextUnlock) != null ? _i : null;
+      if (nextUnlock) {
+        const remaining = nextUnlock.need - nextUnlock.have;
+        const where = nextUnlock.surface ? `On ${nextUnlock.surface}: ` : "";
+        lines.push(`${where}${remaining} more ${nextUnlock.needs} would unlock the next confidence level (${nextUnlock.tier}).`);
+      }
       if (measured.length) {
         lines.push("", "Findings:");
         for (const f of measured) {
-          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${Math.round(f.provenance.coverage * 100)}% of visitors` : "";
+          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${f.provenance.coverage < 5e-3 ? "under 1%" : `${Math.round(f.provenance.coverage * 100)}%`} of visitors` : "";
           lines.push(`- [${f.tier}] ${f.headline} (${f.provenance.sample} ${f.provenance.denominatorLabel}${cov})`);
         }
       }
@@ -698,7 +768,7 @@ function registerInsightTools(server, client) {
         content: [{ type: "text", text: lines.join("\n").trim() || "No findings yet." }],
         structuredContent: {
           status: findings.length ? "ok" : "empty",
-          reached: (_i = data.reached) != null ? _i : "observed",
+          reached: (_j = data.reached) != null ? _j : "observed",
           findings: findings.map((f) => ({
             tier: f.tier,
             kind: f.kind,
@@ -711,7 +781,8 @@ function registerInsightTools(server, client) {
           observations,
           recommendations,
           isStale,
-          generatedAt: (_j = data.generatedAt) != null ? _j : null
+          generatedAt: (_k = data.generatedAt) != null ? _k : null,
+          nextUnlock
         }
       };
     })
@@ -785,8 +856,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -807,7 +878,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -815,11 +887,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a2, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a2 = data.currency) != null ? _a2 : "USD",
         goals: data.goals.map((g) => {
           var _a3, _b2, _c;
@@ -847,6 +920,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a3;
         return [
@@ -855,7 +929,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1699,8 +1774,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: import_zod14.z.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: import_zod14.z.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: import_zod14.z.object({ crawler: import_zod14.z.number(), api: import_zod14.z.number(), browser: import_zod14.z.number() }),
         engines: import_zod14.z.array(
@@ -1718,9 +1797,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1808,7 +1892,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.15.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ApiClient,
   createMcpServer
-} from "./chunk-3RJUYHO7.js";
+} from "./chunk-2E5M5ESK.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -102,6 +102,44 @@ var ApiClient = class {
 
 // src/tools/common.ts
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
+function rangeInputSchema(defaultRange) {
+  return {
+    range: import_zod.z.enum(["7d", "30d", "90d", "all"]).optional().describe(
+      `Calendar window in the project's reporting timezone (default ${defaultRange}). 'all' means all retained data \u2014 the plan's retention window bounds every lookback.`
+    ),
+    from: import_zod.z.string().optional().describe(
+      "Custom window start (YYYY-MM-DD; overrides range). Must be within the plan retention window."
+    ),
+    to: import_zod.z.string().optional().describe("Custom window end (YYYY-MM-DD, inclusive; default today).")
+  };
+}
+function rangeQuery(args) {
+  const p = new URLSearchParams();
+  if (args.from) {
+    p.set("from", args.from);
+    if (args.to) p.set("to", args.to);
+  } else if (args.range) {
+    p.set("range", args.range);
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+var windowOutputSchema = import_zod.z.object({
+  range: import_zod.z.string(),
+  start: import_zod.z.string().nullable(),
+  end: import_zod.z.string().nullable(),
+  timezone: import_zod.z.string(),
+  bucketUnit: import_zod.z.string(),
+  retentionDays: import_zod.z.number().describe("The plan's effective data retention in days"),
+  earliestAvailable: import_zod.z.string().describe("First date retention still holds data for (YYYY-MM-DD)")
+}).optional().describe("The window the server actually used for every count in this response");
+function windowLine(window) {
+  if (!window) return "";
+  if (window.start && window.end) {
+    return `Window: ${window.start.slice(0, 10)} to ${window.end.slice(0, 10)} (${window.timezone}, exclusive end)`;
+  }
+  return `Window: all retained data (${window.retentionDays}-day retention)`;
+}
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
     return extra[err.message];
@@ -116,6 +154,12 @@ function apiErrorGuidance(err, extra) {
     default:
       break;
   }
+  if (err.message === "range_out_of_retention") {
+    return "The requested window starts before this plan retains data \u2014 older events have been deleted by the retention purge and cannot be recovered. Ask for a more recent window, or upgrade the SentientUI plan for longer history (Growth keeps 180 days, Scale 365).";
+  }
+  if (err.message === "invalid_range") {
+    return "Invalid time window. Use range '7d', '30d', '90d' or 'all', or from/to as YYYY-MM-DD dates.";
+  }
   if (err.status === 402) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
@@ -417,7 +461,11 @@ var RENDER_JS = {
   "variant-performance": `
     window.__render = function(data){
       var variants = (data && data.variants) || [];
-      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, last 7 days vs prior 7';
+      var winText = 'current vs prior period';
+      if (data && data.window && data.window.start && data.window.end) {
+        winText = String(data.window.start).slice(0, 10) + ' to ' + String(data.window.end).slice(0, 10) + ' vs prior period';
+      }
+      el('sub').textContent = variants.length + ' variant' + (variants.length === 1 ? '' : 's') + ' \xB7 conversion, ' + winText;
       if (!variants.length) { showEmpty('No variant data available yet.'); return; }
       var max = variants.reduce(function(m,v){ return Math.max(m, v.currentCvr || 0); }, 0) || 1;
       var sorted = variants.slice().sort(function(a,b){ return (b.currentCvr||0) - (a.currentCvr||0); });
@@ -546,8 +594,8 @@ function registerComponentTools(server, client) {
     "list_components",
     {
       title: "List components",
-      description: "List all adaptive components in a project with variant counts and impression totals.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "List all adaptive components in a project with variant counts and impression totals. Counts cover all retained data by default; pass range or from/to for a window.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("all")),
       outputSchema: {
         components: import_zod3.z.array(
           import_zod3.z.object({
@@ -556,7 +604,8 @@ function registerComponentTools(server, client) {
             impressions: import_zod3.z.number(),
             conversions: import_zod3.z.number()
           })
-        ).describe("Adaptive components in the project (empty if none)")
+        ).describe("Adaptive components in the project (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -564,16 +613,17 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const { components } = await client.get(`/projects/${id}/components`);
+      const { components, window } = await client.get(`/projects/${id}/components${rangeQuery({ range, from, to })}`);
       const structuredContent = {
         components: components.map((c) => ({
           componentId: c.component_id,
           variantCount: c.variants.length,
           impressions: c.total_impressions,
           conversions: c.total_conversions
-        }))
+        })),
+        window
       };
       if (!components.length) {
         return {
@@ -591,19 +641,20 @@ function registerComponentTools(server, client) {
     "get_variant_performance",
     {
       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: projectIdSchema },
+      description: "Get CVR and momentum for all variants in a project over the selected window vs the immediately-preceding window of equal length (default: last 7 calendar days vs prior 7).",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("7d")),
       _meta: uiMeta("variant-performance"),
       outputSchema: {
         variants: import_zod3.z.array(
           import_zod3.z.object({
             variantId: import_zod3.z.string(),
-            currentCvr: import_zod3.z.number().describe("Conversion rate over the last 7 days (0-1)"),
-            priorCvr: import_zod3.z.number().describe("Conversion rate over the prior 7 days (0-1)"),
+            currentCvr: import_zod3.z.number().describe("Conversion rate over the selected window (0-1)"),
+            priorCvr: import_zod3.z.number().describe("Conversion rate over the preceding window (0-1)"),
             deltaPp: import_zod3.z.number().describe("Change in percentage points"),
             momentum: import_zod3.z.string().describe("Momentum direction: gaining, losing, or stable")
           })
-        ).describe("Per-variant performance (empty if no data yet)")
+        ).describe("Per-variant performance (empty if no data yet)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -611,10 +662,10 @@ function registerComponentTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b, _c;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/trends`);
+      const data = await client.get(`/projects/${id}/trends${rangeQuery({ range, from, to })}`);
       const momentumMap = new Map(((_a = data.momentum) != null ? _a : []).map((m) => [m.variantId, m.direction]));
       const structuredContent = {
         variants: ((_b = data.cvr) != null ? _b : []).map((v) => {
@@ -626,7 +677,8 @@ function registerComponentTools(server, client) {
             deltaPp: v.deltaPp,
             momentum: (_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"
           };
-        })
+        }),
+        window: data.window
       };
       if (!((_c = data.cvr) == null ? void 0 : _c.length)) {
         return {
@@ -635,12 +687,14 @@ function registerComponentTools(server, client) {
           _meta: uiMeta("variant-performance")
         };
       }
-      const text = data.cvr.map(
+      const lines = data.cvr.map(
         (v) => {
           var _a2;
           return `- ${v.variantId}: CVR ${(v.currentCvr * 100).toFixed(2)}% (prior ${(v.priorCvr * 100).toFixed(2)}%, ${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${(_a2 = momentumMap.get(v.variantId)) != null ? _a2 : "stable"})`;
         }
-      ).join("\n");
+      );
+      const win = windowLine(data.window);
+      const text = (win ? [win, ...lines] : lines).join("\n");
       return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("variant-performance") };
     })
   );
@@ -654,8 +708,11 @@ var EMPTY_REASON_TEXT = {
   awaiting_profiles: "Still building visitor profiles before visitors can be grouped.",
   no_variants: "Nothing to compare yet \u2014 no adaptive component is running.",
   nothing_moved: "Enough data, and nothing moved this period. That is a result.",
-  job_never_ran: "The analysis job has not run yet.",
-  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently."
+  // The stale/never-ran texts name the remedy: an agent that is not told about
+  // refresh_insights has no way to know it can fix this itself.
+  job_never_ran: "The analysis job has not run yet. Call refresh_insights to run it now.",
+  job_stale: "These numbers are out of date \u2014 the analysis job has not run recently. Call refresh_insights to regenerate them.",
+  data_unavailable: "The project data could not be read just now \u2014 nothing is wrong with the setup. Retry shortly."
 };
 function registerInsightTools(server, client) {
   server.registerTool(
@@ -679,7 +736,14 @@ function registerInsightTools(server, client) {
         observations: import_zod4.z.array(import_zod4.z.string()).describe("Headlines of measured findings"),
         recommendations: import_zod4.z.array(import_zod4.z.string()).describe("Headlines of interpreted findings (Growth tier)"),
         isStale: import_zod4.z.boolean().describe("True when the analysis has not run recently"),
-        generatedAt: import_zod4.z.string().nullable().describe("ISO timestamp, or null")
+        generatedAt: import_zod4.z.string().nullable().describe("ISO timestamp, or null"),
+        nextUnlock: import_zod4.z.object({
+          tier: import_zod4.z.string(),
+          needs: import_zod4.z.string(),
+          have: import_zod4.z.number(),
+          need: import_zod4.z.number(),
+          surface: import_zod4.z.string().nullable()
+        }).nullable().describe("The nearest gap that would raise the confidence tier, when there is one")
       },
       annotations: {
         readOnlyHint: true,
@@ -688,7 +752,7 @@ function registerInsightTools(server, client) {
       }
     },
     withApiErrorGuidance(async ({ projectId }) => {
-      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+      var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/evidence-report`);
       const findings = (_a = data.findings) != null ? _a : [];
@@ -700,17 +764,23 @@ function registerInsightTools(server, client) {
       const emptyReason = (_d = data.emptyReason) != null ? _d : null;
       const lines = [];
       if (emptyReason) lines.push((_e = EMPTY_REASON_TEXT[emptyReason]) != null ? _e : emptyReason);
-      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved.");
+      if (isStale) lines.push("\u26A0 The analysis job has not run recently, so these numbers may have moved. Call refresh_insights to regenerate them.");
       if ((_f = data.interpretation) == null ? void 0 : _f.locked) {
         lines.push(`${data.interpretation.count || "Some"} recommendations are available on the Growth plan.`);
       } else if (((_g = data.interpretation) == null ? void 0 : _g.emptyReason) && !emptyReason) {
         lines.push(`Recommendations: ${(_h = EMPTY_REASON_TEXT[data.interpretation.emptyReason]) != null ? _h : data.interpretation.emptyReason}`);
       }
       if (data.generatedAt) lines.push(`Generated: ${new Date(data.generatedAt).toUTCString()}`);
+      const nextUnlock = (_i = data.nextUnlock) != null ? _i : null;
+      if (nextUnlock) {
+        const remaining = nextUnlock.need - nextUnlock.have;
+        const where = nextUnlock.surface ? `On ${nextUnlock.surface}: ` : "";
+        lines.push(`${where}${remaining} more ${nextUnlock.needs} would unlock the next confidence level (${nextUnlock.tier}).`);
+      }
       if (measured.length) {
         lines.push("", "Findings:");
         for (const f of measured) {
-          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${Math.round(f.provenance.coverage * 100)}% of visitors` : "";
+          const cov = f.provenance.coverage !== null && f.provenance.coverage < 0.999 ? `, covering ${f.provenance.coverage < 5e-3 ? "under 1%" : `${Math.round(f.provenance.coverage * 100)}%`} of visitors` : "";
           lines.push(`- [${f.tier}] ${f.headline} (${f.provenance.sample} ${f.provenance.denominatorLabel}${cov})`);
         }
       }
@@ -722,7 +792,7 @@ function registerInsightTools(server, client) {
         content: [{ type: "text", text: lines.join("\n").trim() || "No findings yet." }],
         structuredContent: {
           status: findings.length ? "ok" : "empty",
-          reached: (_i = data.reached) != null ? _i : "observed",
+          reached: (_j = data.reached) != null ? _j : "observed",
           findings: findings.map((f) => ({
             tier: f.tier,
             kind: f.kind,
@@ -735,7 +805,8 @@ function registerInsightTools(server, client) {
           observations,
           recommendations,
           isStale,
-          generatedAt: (_j = data.generatedAt) != null ? _j : null
+          generatedAt: (_k = data.generatedAt) != null ? _k : null,
+          nextUnlock
         }
       };
     })
@@ -809,8 +880,8 @@ function registerGoalTools(server, client) {
     "get_goal_funnel",
     {
       title: "Goal funnel",
-      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Get goal hit counts, unique-session conversion rates, and per-variant breakdown (default window: last 30 calendar days). This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report.",
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
         currency: import_zod6.z.string().describe("Project display currency (ISO-4217) for the revenue fields"),
@@ -831,7 +902,8 @@ function registerGoalTools(server, client) {
               })
             ).describe("Per-variant breakdown")
           })
-        ).describe("Configured goals (empty if none)")
+        ).describe("Configured goals (empty if none)"),
+        window: windowOutputSchema
       },
       annotations: {
         readOnlyHint: true,
@@ -839,11 +911,12 @@ function registerGoalTools(server, client) {
         openWorldHint: false
       }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       var _a, _b;
       const id = encodeURIComponent(projectId);
-      const data = await client.get(`/projects/${id}/goals`);
+      const data = await client.get(`/projects/${id}/goals${rangeQuery({ range, from, to })}`);
       const structuredContent = {
+        window: data.window,
         currency: (_a = data.currency) != null ? _a : "USD",
         goals: data.goals.map((g) => {
           var _a2, _b2, _c;
@@ -871,6 +944,7 @@ function registerGoalTools(server, client) {
         };
       }
       const currency = (_b = data.currency) != null ? _b : "USD";
+      const win = windowLine(data.window);
       const lines = data.goals.flatMap((g) => {
         var _a2;
         return [
@@ -879,7 +953,8 @@ function registerGoalTools(server, client) {
           ""
         ];
       });
-      return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent, _meta: uiMeta("goal-funnel") };
+      const text = (win ? [win, "", ...lines] : lines).join("\n").trim();
+      return { content: [{ type: "text", text }], structuredContent, _meta: uiMeta("goal-funnel") };
     })
   );
   server.registerTool(
@@ -1723,8 +1798,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
-      inputSchema: { projectId: projectIdSchema },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        from: import_zod14.z.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
+        to: import_zod14.z.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
+      },
       outputSchema: {
         totals: import_zod14.z.object({ crawler: import_zod14.z.number(), api: import_zod14.z.number(), browser: import_zod14.z.number() }),
         engines: import_zod14.z.array(
@@ -1742,9 +1821,14 @@ function registerAgentTrafficTools(server, client) {
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId }) => {
+    withApiErrorGuidance(async ({ projectId, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const qs = new URLSearchParams();
+      if (from) qs.set("from", from);
+      if (to) qs.set("to", to);
+      const s = await client.get(
+        `/projects/${id}/agent-activity/summary${qs.size > 0 ? `?${qs.toString()}` : ""}`
+      );
       const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
@@ -1832,7 +1916,7 @@ function registerAgentTrafficTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.15.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.17.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-3RJUYHO7.js";
+} from "./chunk-2E5M5ESK.js";
 export {
   ApiClient,
   ApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",