@agent-native/core-corpus 0.200.0-nightly-20261002153252 → 0.200.0

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 11025
+- template files: 11031

package/corpus/templates/analytics/.agents/skills/gong/SKILL.md

@@ -12,13 +12,15 @@ dive that asks what happened in customer conversations.
 
 ## Actions
 
-- `gong-native-insights` — one provider-native qualitative synthesis operation
-  (`ask_account`, `ask_deal`, or `generate_brief`) through Gong's connected MCP.
-  Use it for themes, risks, summaries, and deck narrative when the native tools
-  are connected. One action invocation makes at most one Gong AI request; omit
-  `operation` to inspect its schemas without spending a credit request, and set
-  `allowCreditRequest=true` only for the one consolidated request you intend to
-  send. Paid calls also require a workspace owner to enable them once with
+- `gong-native-insights` — lists the connected provider-native qualitative
+  synthesis operations (`ask_account`, `ask_deal`, `generate_brief`) and their
+  schemas. It never calls Gong AI or spends a credit request.
+- `run-gong-native-insight` — sends one of those operations through Gong's
+  connected MCP. Use it for themes, risks, summaries, and deck narrative when
+  the native tools are connected. One invocation makes at most one Gong AI
+  request; set `allowCreditRequest=true` only for the one consolidated request
+  you intend to send, and each paid request asks for approval. Paid calls also
+  require a workspace owner to enable them once with
   `configure-gong-native-insights`; the policy defaults off and disabling it
   never blocks the raw evidence path.
 - `account-deep-dive` — first choice for named account/deal deep dives that
@@ -39,7 +41,7 @@ native/indexed search can answer the question.
 
 ## Route Synthesis and Evidence Separately
 
-- Use `gong-native-insights` for qualitative synthesis where Gong may retrieve
+- Use `run-gong-native-insight` for qualitative synthesis where Gong may retrieve
   and analyze evidence internally. Its result is provider synthesis: coverage
   is unknown and raw transcript evidence is unavailable.
 - Use `gong-calls` or `provider-corpus-job` for quotes, exact counts, transcript

package/corpus/templates/analytics/CHANGELOG.md

@@ -3,15 +3,28 @@
 All notable user-facing changes to Agent-Native Analytics are documented here. Open it any
 time from the command menu (Cmd+K → "What's new") or from Settings.
 
+## 2026-10-02
+
+### Improved
+
+- Retention reports now compare returns from paid and untagged signups.
+
 ## 2026-10-01
 
 ### Improved
 
+- Clear all resets every Sessions filter in one click.
+- The first-party retention chart now splits 1-7d return into paid and untagged signups, and a Chat Readiness at Prompt panel shows whether AI was ready and how many prompts got no reply.
 - Error issues in Monitoring link straight to the chat thread that failed, and one underlying error now stays a single issue instead of splitting after each deploy
 - The observability settings tab is now labeled Observability.
 
 ## 2026-09-30
 
+### Added
+
+- External agents connected over MCP can read dashboards, saved analyses, the data dictionary, blog articles and provider data directly, without handing the question to the Analytics agent.
+- With the Sessions triage Lab on, filter sessions by events they did or didn't send, see app events and failed actions on replay timelines, and browse an event catalog.
+
 ### Improved
 
 - Removed excess spacing above the sidebar footer

package/corpus/templates/analytics/actions/account-deep-dive.ts

@@ -417,6 +417,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   grounding: true,
   run: async (args) => {

package/corpus/templates/analytics/actions/bigquery.ts

@@ -127,6 +127,7 @@ export default defineAction({
     sql: z.string().describe("SQL query to execute"),
   }),
   readOnly: true,
+  mcpTool: false,
   toolCallable: true,
   grounding: true,
   run: async (args, context?: ActionRunContext) => {

package/corpus/templates/analytics/actions/builder-blog-articles.ts

@@ -216,6 +216,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   grounding: true,
   run: async (args, context) => {
     return listBuilderBlogArticles(args, context);

package/corpus/templates/analytics/actions/configure-gong-native-insights.ts

@@ -5,7 +5,7 @@ import { writeGongNativeInsightsPolicy } from "../server/lib/gong-native-policy"
 
 export default defineAction({
   description:
-    "Enable or disable paid Gong native semantic operations for the current workspace. Enabling this permits individually authorized gong-native-insights calls to consume Gong credits; it does not send a Gong request by itself. Disable it to fail closed for every semantic request while keeping raw Gong evidence actions available.",
+    "Enable or disable paid Gong native semantic operations for the current workspace. Enabling this permits individually authorized run-gong-native-insight calls to consume Gong credits; it does not send a Gong request by itself. Disable it to fail closed for every semantic request while keeping raw Gong evidence actions available.",
   schema: z.object({
     enabled: z
       .boolean()

package/corpus/templates/analytics/actions/create-session-replay-agent-link.ts

@@ -28,4 +28,5 @@ export default defineAction({
     });
   },
   readOnly: true,
+  mcpTool: false,
 });

package/corpus/templates/analytics/actions/data-source-status.ts

@@ -96,6 +96,7 @@ export default defineAction({
       ),
   }),
   http: { method: "GET" },
+  mcpTool: true,
   run: async (args) => {
     const ctx = tryRequestCredentialContext();
     if (!ctx) {

package/corpus/templates/analytics/actions/db-admin-federated-read.ts

@@ -22,6 +22,7 @@ export default defineAction({
   },
   http: { method: "POST" },
   readOnly: true,
+  mcpTool: false,
   grounding: true,
   run: async (args, ctx) => {
     const admin = await requireDbAdminContextFromRequest(ctx);

package/corpus/templates/analytics/actions/get-analysis.ts

@@ -14,7 +14,8 @@ import {
 } from "../server/lib/dashboards-store";
 
 export default defineAction({
-  description: "Get a saved ad-hoc analysis by ID, including its full results.",
+  description:
+    "Get a saved ad-hoc analysis by ID, including its question, data sources, and full results. Use list-analyses to find IDs.",
   schema: z.object({
     id: z.string().describe("The analysis ID"),
     reviewPreview: z
@@ -31,6 +32,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   mcpApp: {
     compactCatalog: true,

package/corpus/templates/analytics/actions/get-data-program.ts

@@ -19,6 +19,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   run: async (args) => {
     const ctx = getCredentialContext();
     if (!ctx) throw new Error("No authenticated context for get-data-program.");

package/corpus/templates/analytics/actions/get-error-issue.ts

@@ -28,6 +28,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   grounding: true,
   run: async (args) => {

package/corpus/templates/analytics/actions/get-first-party-analytics-health.ts

@@ -79,6 +79,7 @@ export default defineAction({
   outputSchema: healthSchema,
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async () => {
     const scope = resolveScope();

package/corpus/templates/analytics/actions/get-session-replay-summary.ts

@@ -21,6 +21,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   grounding: true,
   run: async (args) => {

package/corpus/templates/analytics/actions/get-session-replay-timeline.ts

@@ -31,6 +31,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   grounding: true,
   run: async (args) => {

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -44,6 +44,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   mcpApp: {
     compactCatalog: true,

package/corpus/templates/analytics/actions/gong-calls.ts

@@ -487,12 +487,13 @@ function normalizeGongDate(
 
 export default defineAction({
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   maxResultChars: 100_000,
   description:
-    "Query bounded Gong sales-call evidence. Pass --users for the user list, --transcript for one transcript, or --company for a bounded search by company/domain/person/email. Without --company, the action lists calls in the date window; set exhaustive=true only for a small bounded cohort of fewer than 500 records, not a broad org-wide export. For account-level transcript mention questions, transcriptQuery performs a case-insensitive local scan after batched transcript retrieval and returns coverage counts plus snippets; it is not Gong's server-side keyword search. Use includeTranscripts=true for bounded qualitative context. For broad keyword, tracker, cross-account, or absence-sensitive work, use provider-api-catalog/provider-api-docs, stage the raw Gong API response, then use query-staged-dataset or a Data Program; use provider-corpus-job only when raw transcript bodies are required.",
+    "Query bounded Gong sales-call evidence. Pass --users for the user list, --transcript for one transcript, or --company for a bounded call search; without --company, lists calls in the date window. For broad keyword, tracker, cross-account, or absence-sensitive work, stage the raw Gong API response via provider-api-catalog/provider-api-docs/provider-api-request, then use query-staged-dataset or a Data Program; use provider-corpus-job only for durable scans that require raw transcript bodies.",
   schema: z.object({
-    users: cliBoolean.optional().describe("Set to true to list Gong users"),
+    users: cliBoolean.optional().describe("List Gong users"),
     transcript: z.string().optional().describe("Call ID to get transcript"),
     rawTranscript: cliBoolean
       .optional()
@@ -514,7 +515,7 @@ export default defineAction({
       .max(200)
       .optional()
       .describe(
-        "Maximum number of calls to return for call searches (default 8, max 200). Use 5-8 for quick checks, 20-50 for thorough account analysis, 100-200 for large-scale coverage.",
+        "Max calls to return (default 8). Use 5-8 for quick checks, 20-50 for thorough account analysis, 100-200 for large-scale coverage.",
       ),
     includeTranscripts: cliBoolean
       .optional()
@@ -528,7 +529,7 @@ export default defineAction({
       .max(MAX_GONG_TRANSCRIPT_LIMIT)
       .optional()
       .describe(
-        "Number of matching calls to load transcripts for when includeTranscripts=true (default 3, max 50). Use 3-5 for a first pass; increase to 10-20+ for thorough account analysis.",
+        "Matching calls to load transcripts for when includeTranscripts=true (default 3). Use 3-5 for a first pass, 10-20+ for thorough account analysis.",
       ),
     transcriptMaxChars: z.coerce
       .number()
@@ -537,13 +538,13 @@ export default defineAction({
       .max(MAX_TRANSCRIPT_MAX_CHARS)
       .optional()
       .describe(
-        "Maximum transcript characters to return per call (default 8000, max 100000). Batched results also share a 60000-character aggregate excerpt budget. Use the default for analysis; raise it only when the user asks for more quoted detail.",
+        "Max transcript characters per call (default 8000). Batched results also share a 60000-character aggregate excerpt budget. Use the default for analysis; raise it only when the user asks for more quoted detail.",
       ),
     transcriptQuery: z
       .string()
       .optional()
       .describe(
-        "Case-insensitive phrase to search inside matching call transcripts after batched retrieval. Use only for bounded account/call searches where the matching set is already small. For broad cohort or exhaustive absence research, use the raw Gong API tracker/staging path plus query-staged-dataset or a Data Program, or provider-corpus-job when raw transcript bodies are required. Returns coverage counts and short snippets only, not full transcripts.",
+        "Case-insensitive phrase for a local scan of matching call transcripts after batched retrieval; not Gong's server-side keyword search. Use only for bounded account-level mention questions where the matching call set is already small. Returns coverage counts and short snippets, not full transcripts.",
       ),
     transcriptScanLimit: z.coerce
       .number()
@@ -552,24 +553,24 @@ export default defineAction({
       .max(MAX_TRANSCRIPT_SCAN_LIMIT)
       .optional()
       .describe(
-        "Maximum number of matching calls whose transcripts should be fetched and searched when transcriptQuery is set (default 50, max 200). Combine with exhaustive=true and after/before for defensible bounded coverage.",
+        "Max matching calls whose transcripts are fetched and searched when transcriptQuery is set (default 50). Combine with exhaustive=true and after/before for defensible bounded coverage.",
       ),
     exhaustive: cliBoolean
       .optional()
       .describe(
-        "Return EVERY matching call in the window instead of stopping at `limit`; without company, return every call page only for a small bounded cohort of fewer than 500 records. Cohorts at or above 500 fail closed with guidance to use provider-api-request staging and query-staged-dataset or a Data Program. By default this is metadata-only. With includeTranscripts=true, transcripts are fetched in batches and explicit coverage is returned. For broad or absence-sensitive work, prefer the raw Gong API tracker/staging path plus query-staged-dataset or a Data Program; use provider-corpus-job for durable raw-transcript scans. Always bound this with after/before or a small days window.",
+        "Return EVERY matching call in the window instead of stopping at `limit`. Without company, use only for a small bounded cohort of fewer than 500 records, not a broad org-wide export. Cohorts at or above 500 fail closed with staging guidance. Metadata-only unless includeTranscripts=true, which fetches transcripts in batches and returns explicit coverage. Always bound this with after/before or a small days window.",
       ),
     after: z
       .string()
       .optional()
       .describe(
-        "Only include calls on/after this date (ISO yyyy-mm-dd or full timestamp), e.g. a deal's closed-won date. Sets the window start and overrides `days` for the start bound.",
+        "Only include calls on/after this date (ISO yyyy-mm-dd or full timestamp), e.g. a deal's closed-won date. Overrides `days` for the window start.",
       ),
     before: z
       .string()
       .optional()
       .describe(
-        "Only include calls on/before this date (ISO yyyy-mm-dd or full timestamp). Sets the window end.",
+        "Only include calls on/before this date (ISO yyyy-mm-dd or full timestamp).",
       ),
   }),
   http: { method: "GET" },

package/corpus/templates/analytics/actions/gong-native-insights.ts

@@ -1,167 +1,50 @@
 import { defineAction } from "@agent-native/core/action";
-import {
-  callMcpTool,
-  listVisibleMcpTools,
-  type AppMcpTool,
-} from "@agent-native/core/mcp-client";
 import { z } from "zod";
 
-import { readGongNativeInsightsPolicy } from "../server/lib/gong-native-policy";
-
-const GONG_NATIVE_OPERATIONS = [
-  "ask_account",
-  "ask_deal",
-  "generate_brief",
-] as const;
-
-type GongNativeOperation = (typeof GONG_NATIVE_OPERATIONS)[number];
-
-function operationName(value: string): string {
-  return value.trim().toLowerCase().replace(/-/g, "_");
-}
-
-function gongNativeTools(tools: AppMcpTool[]): AppMcpTool[] {
-  const names = new Set<string>(GONG_NATIVE_OPERATIONS);
-  return tools.filter((tool) => names.has(operationName(tool.name)));
-}
-
-function selectTool(
-  tools: AppMcpTool[],
-  operation: GongNativeOperation,
-): AppMcpTool | null {
-  const matches = tools.filter(
-    (tool) => operationName(tool.name) === operation,
-  );
-  if (matches.length === 1) return matches[0];
-  const gongNamed = matches.filter((tool) => /gong/i.test(tool.serverId));
-  return gongNamed.length === 1 ? gongNamed[0] : null;
-}
+import {
+  gongNativeOperationName,
+  listGongNativeTools,
+} from "../server/lib/gong-native-operations";
 
 export default defineAction({
   description:
-    "Use Gong's official MCP semantic operations for one bounded qualitative synthesis request. Omit operation to inspect the connected schemas without spending Gong credits. Paid calls fail closed unless configure-gong-native-insights has enabled them for this workspace and this invocation sets allowCreditRequest=true. With operation, pass one consolidated arguments object; each invocation independently consumes Gong credits. Use this only for themes, risks, summaries, and deck narrative. For transcripts, quotes, counts, source records, or absence/exhaustive claims use gong-calls or the provider corpus evidence path instead.",
-  schema: z.object({
-    operation: z
-      .enum(GONG_NATIVE_OPERATIONS)
-      .optional()
-      .describe(
-        "Official Gong MCP operation. Omit to list the currently connected operation schemas without calling Gong AI.",
-      ),
-    allowCreditRequest: z
-      .boolean()
-      .default(false)
-      .describe(
-        "Explicitly authorize this one Gong semantic request. Leave false while inspecting schemas or when the workspace should not spend Gong credits.",
-      ),
-    arguments: z
-      .record(z.string(), z.unknown())
-      .default({})
-      .describe(
-        "Arguments passed unchanged to the connected Gong MCP operation. Consolidate related questions into one request and narrow the entity/date scope.",
-      ),
-  }),
+    "List the Gong native semantic operations (ask_account, ask_deal, generate_brief) connected in this request scope, with their input schemas. This never calls Gong AI or consumes Gong credits. To send one paid qualitative synthesis request, call run-gong-native-insight with the chosen operation. For transcripts, quotes, counts, source records, or absence/exhaustive claims use gong-calls or the provider corpus evidence path instead.",
+  // Paid execution moved to run-gong-native-insight. Reject its arguments here
+  // instead of silently returning a listing to an older caller.
+  schema: z.strictObject(
+    {},
+    {
+      error: (issue) =>
+        issue.code === "unrecognized_keys"
+          ? `gong-native-insights only lists operations and takes no arguments (got ${issue.keys.join(", ")}). Send a paid Gong request with run-gong-native-insight.`
+          : undefined,
+    },
+  ),
   readOnly: true,
   parallelSafe: true,
-  needsApproval: ({ operation, allowCreditRequest }) =>
-    Boolean(operation && allowCreditRequest),
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   http: false,
-  grounding: true,
-  run: async ({ operation, allowCreditRequest, arguments: args }) => {
-    const tools = gongNativeTools(await listVisibleMcpTools());
-    if (!operation) {
-      return {
-        connected: tools.length > 0,
-        creditRequests: 0,
-        creditUnit: "request",
-        evidenceMode: "provider-synthesis",
-        rawEvidenceAvailable: false,
-        operations: tools.map((tool) => ({
-          operation: operationName(tool.name),
-          serverId: tool.serverId,
-          description: tool.description,
-          inputSchema: tool.inputSchema,
-        })),
-        evidenceFallbackAction: "gong-calls",
-        guidance:
-          tools.length > 0
-            ? "Choose one operation and make one consolidated, narrowly scoped request. Inspecting this catalog did not call Gong AI or consume a Gong credit request."
-            : "No official Gong semantic MCP operations are connected in this request scope. Use gong-calls for bounded evidence, or connect Gong MCP before using the synthesis path.",
-      };
-    }
-
-    if (!allowCreditRequest) {
-      return {
-        connected: tools.length > 0,
-        operation,
-        blocked: true,
-        creditRequests: 0,
-        creditUnit: "request",
-        evidenceMode: "provider-synthesis",
-        rawEvidenceAvailable: false,
-        evidenceFallbackAction: "gong-calls",
-        guidance:
-          "This Gong semantic request was not sent. Set allowCreditRequest=true only after choosing one consolidated, narrowly scoped request; use gong-calls for evidence retrieval without Gong AI synthesis.",
-      };
-    }
-
-    const policy = await readGongNativeInsightsPolicy();
-    if (!policy.enabled) {
-      return {
-        connected: tools.length > 0,
-        operation,
-        blocked: true,
-        blockedBy: "workspace-policy",
-        policy,
-        creditRequests: 0,
-        creditUnit: "request",
-        evidenceMode: "provider-synthesis",
-        rawEvidenceAvailable: false,
-        evidenceFallbackAction: "gong-calls",
-        guidance:
-          "This Gong semantic request was not sent because paid native insights are disabled for this workspace. An authorized user can enable them with configure-gong-native-insights; use gong-calls for evidence retrieval in the meantime.",
-      };
-    }
-
-    const tool = selectTool(tools, operation);
-    if (!tool) {
-      return {
-        connected: tools.length > 0,
-        operation,
-        creditRequests: 0,
-        creditUnit: "request",
-        evidenceMode: "provider-synthesis",
-        rawEvidenceAvailable: false,
-        error:
-          tools.length === 0
-            ? "No official Gong semantic MCP operations are connected in this request scope."
-            : `The ${operation} operation is missing or ambiguous across connected MCP servers.`,
-        availableOperations: tools.map((candidate) => ({
-          operation: operationName(candidate.name),
-          serverId: candidate.serverId,
-        })),
-        evidenceFallbackAction: "gong-calls",
-      };
-    }
-
-    const startedAt = Date.now();
-    const result = await callMcpTool(tool.serverId, tool.name, args);
+  run: async () => {
+    const tools = await listGongNativeTools();
     return {
-      connected: true,
-      source: "gong-native-mcp",
-      operation,
-      creditRequests: 1,
+      connected: tools.length > 0,
+      creditRequests: 0,
       creditUnit: "request",
-      durationMs: Date.now() - startedAt,
       evidenceMode: "provider-synthesis",
-      synthesisOnly: true,
       rawEvidenceAvailable: false,
-      coverageComplete: false,
-      coverageUnknown: true,
-      result,
+      operations: tools.map((tool) => ({
+        operation: gongNativeOperationName(tool.name),
+        serverId: tool.serverId,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+      executionAction: "run-gong-native-insight",
       evidenceFallbackAction: "gong-calls",
       guidance:
-        "Treat this as Gong-generated qualitative synthesis, not transcript evidence. Do not use it for verbatim quotes, exact counts, source-record claims, or proof of absence; route those to gong-calls or the provider corpus evidence path.",
+        tools.length > 0
+          ? "Choose one operation and send one consolidated, narrowly scoped request with run-gong-native-insight. Inspecting this catalog did not call Gong AI or consume a Gong credit request."
+          : "No official Gong semantic MCP operations are connected in this request scope. Use gong-calls for bounded evidence, or connect Gong MCP before using the synthesis path.",
     };
   },
 });

package/corpus/templates/analytics/actions/hubspot-deals.ts

@@ -426,51 +426,50 @@ function buildGuidance(options: {
 
 export default defineAction({
   readOnly: true,
+  mcpTool: true,
   description:
-    "Get HubSpot deals with normalized stage, pipeline, owner, forecast, and NBM fields. This is a bounded deal analytics shortcut, not the full HubSpot capability surface. Use query for a specific customer/deal/account deep dive. For cohorts like products field = Publish, closed-won, pipeline = New Business, or close date in a range, use the structured product, pipeline, closedStatus, closedDateFrom, and closedDateTo filters instead of query when the answer is the deal list itself. If the cohort feeds a cross-source join, transcript/message/ticket search, exhaustive absence check, or downstream code/corpus workflow, prefer provider-api-catalog/provider-api-request with provider = hubspot and stageAs so the cohort is available as a staged dataset. Both paths are bounded: at most limit deals are returned (default 25, max 200). HubSpot search returns a total but no server-side aggregates and cannot page past 10,000 matches for one query; compute metrics on filtered/projected rows, and split larger cohorts into non-overlapping date windows while reporting coverage. The structured-filter path returns total as the matched count and a truncated flag; page with offset (or narrow filters) instead of expecting the whole cohort in one call, since a full enriched cohort can be several MB and overruns extension and context budgets. For non-deal CRM records use hubspot-records; for arbitrary HubSpot endpoints, filters, associations, batch APIs, or payloads use provider-api-catalog/provider-api-docs/provider-api-request with provider = hubspot.",
+    "Get HubSpot deals with normalized stage, pipeline, owner, forecast, and NBM fields. This is a bounded deal analytics shortcut, not the full HubSpot capability surface. Use query for a specific customer/deal/account deep dive. For cohorts, use the structured product, pipeline, closedStatus, closedDateFrom, and closedDateTo filters instead of query when the answer is the deal list itself. If the cohort feeds a cross-source join, transcript/message/ticket search, exhaustive absence check, or downstream code/corpus workflow, prefer provider-api-request with provider = hubspot and stageAs so the cohort is available as a staged dataset. HubSpot search returns a total but no server-side aggregates and cannot page past 10,000 matches for one query; compute metrics on filtered/projected rows, and split larger cohorts into non-overlapping date windows while reporting coverage. The structured-filter path also returns a truncated flag; page with offset (or narrow filters) instead of expecting the whole cohort in one call, since a full enriched cohort can be several MB and overruns extension and context budgets. For non-deal CRM records use hubspot-records; for arbitrary HubSpot endpoints, filters, associations, batch APIs, or payloads use provider-api-catalog/provider-api-docs/provider-api-request with provider = hubspot.",
   schema: z.object({
     properties: StringListSchema.describe(
-      "Optional comma-separated extra HubSpot deal property names to include.",
+      "Comma-separated extra HubSpot deal property names to include.",
     ),
     owner: z
       .string()
       .optional()
-      .describe("Optional owner name filter, case-insensitive."),
+      .describe("Owner name filter, case-insensitive."),
     product: z
       .string()
       .optional()
-      .describe(
-        "Optional structured filter for the HubSpot deals products field, e.g. Publish. Do not put product-field filters in query.",
-      ),
+      .describe("Filter on the HubSpot deals products field, e.g. Publish."),
     productMatch: TextMatchSchema.default("token").describe(
-      "How to match the products field: token for multi-select values, contains for substring, exact for exact full-field match.",
+      "How to match the products field: token for multi-select values, contains for substring, exact for full-field match.",
     ),
     pipeline: z
       .string()
       .optional()
       .describe(
-        "Optional structured filter for HubSpot deal pipeline id or label, case-insensitive contains match, e.g. New Business.",
+        "Deal pipeline id or label, case-insensitive contains match, e.g. New Business.",
       ),
     closedStatus: ClosedStatusSchema.default("any").describe(
-      "Optional structured stage filter based on normalized HubSpot pipeline stage metadata.",
+      "Stage filter based on normalized HubSpot pipeline stage metadata.",
     ),
     closedDateFrom: z
       .string()
       .optional()
       .describe(
-        "Optional inclusive close-date lower bound for deals, YYYY-MM-DD or ISO date/time.",
+        "Inclusive close-date lower bound, YYYY-MM-DD or ISO date/time.",
       ),
     closedDateTo: z
       .string()
       .optional()
       .describe(
-        "Optional inclusive close-date upper bound for deals, YYYY-MM-DD or ISO date/time.",
+        "Inclusive close-date upper bound, YYYY-MM-DD or ISO date/time.",
       ),
     query: z
       .string()
       .optional()
       .describe(
-        "Optional HubSpot full-text deal search query, such as a company name, deal name, domain, or keyword. Use for customer/deal deep dives. Do not use query as a substitute for field-specific product, pipeline, stage, or date filters.",
+        "HubSpot full-text deal search, such as a company name, deal name, domain, or keyword. Not a substitute for the product, pipeline, stage, or date filters.",
       ),
     limit: z.coerce
       .number()
@@ -479,7 +478,7 @@ export default defineAction({
       .max(200)
       .default(25)
       .describe(
-        "Maximum deals to return. Applies to BOTH full-text query results and structured-filter cohorts. The structured-filter path returns at most this many enriched deals (use total for the true matched count and offset to page).",
+        "Maximum deals to return on BOTH the full-text query and structured-filter paths. Use total for the true matched count.",
       ),
     offset: z.coerce
       .number()
@@ -488,12 +487,12 @@ export default defineAction({
       .max(HUBSPOT_SEARCH_RESULT_CAP - 1)
       .default(0)
       .describe(
-        "Number of structured-filter results to skip before returning limit deals. Use for paging through a large cohort; ignored when query is provided.",
+        "Structured-filter results to skip when paging; ignored when query is provided.",
       ),
     after: z
       .string()
       .optional()
-      .describe("Optional HubSpot pagination cursor for query results."),
+      .describe("HubSpot pagination cursor for query results."),
   }),
   http: { method: "GET" },
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },

package/corpus/templates/analytics/actions/hubspot-metrics.ts

@@ -9,8 +9,9 @@ import {
 
 export default defineAction({
   readOnly: true,
+  mcpTool: true,
   description:
-    "Get computed HubSpot sales metrics: win rate, ACV, pipeline value, etc.",
+    "Get computed HubSpot sales metrics such as win rate, ACV, and pipeline value, aggregated from deals in the configured metrics pipelines.",
   schema: z.object({}),
   http: { method: "GET" },
   grounding: true,

package/corpus/templates/analytics/actions/hubspot-pipelines.ts

@@ -5,7 +5,9 @@ import { getDealPipelines, getVisiblePipelines } from "../server/lib/hubspot";
 
 export default defineAction({
   readOnly: true,
-  description: "Get HubSpot deal pipelines and their stages.",
+  mcpTool: true,
+  description:
+    "Get the visible HubSpot deal pipelines and their stages. Pass a pipeline ID or label to hubspot-deals to filter deals.",
   schema: z.object({}),
   http: { method: "GET" },
   grounding: true,

package/corpus/templates/analytics/actions/hubspot-records.ts

@@ -17,6 +17,7 @@ const StringListSchema = z.preprocess((value) => {
 
 export default defineAction({
   readOnly: true,
+  mcpTool: true,
   description:
     "Search or list HubSpot CRM records across contacts, companies, deals, and tickets. Use this for HubSpot data that is not just deal pipeline metrics. This is a convenience reader; for unsupported object types, associations, custom filters, batch APIs, pagination modes, or any HubSpot endpoint this does not model, use provider-api-catalog/provider-api-docs/provider-api-request with provider = hubspot.",
   schema: z.object({

package/corpus/templates/analytics/actions/list-analyses.ts

@@ -16,6 +16,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   link: () => ({
     url: buildDeepLink({ app: "analytics", view: "analyses" }),

package/corpus/templates/analytics/actions/list-dashboard-folders.ts

@@ -8,10 +8,12 @@ import { z } from "zod";
 import { listDashboardFolders } from "../server/lib/dashboard-folders-store";
 
 export default defineAction({
-  description: "List dashboard folders accessible to the current user.",
+  description:
+    "List the dashboard folders the current user can access. Use list-sql-dashboards to list the dashboards themselves.",
   schema: z.object({}),
   http: { method: "GET" },
   readOnly: true,
+  mcpTool: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async () => {
     const email = getRequestUserEmail();