@langwatch/mcp-server 0.6.1 → 0.7.0

package/src/tools/format-dataset-mutation.ts

@@ -0,0 +1,25 @@
+import type { DatasetMutationResponse } from "../langwatch-api-datasets.js";
+import { escapeMarkdown } from "../utils/escape-markdown.js";
+
+/**
+ * Formats the common detail lines for a dataset mutation response
+ * (name, slug, id, and column types).
+ *
+ * Used by both create-dataset and update-dataset handlers to avoid
+ * duplicating the formatting logic.
+ */
+export function formatDatasetMutationDetails(
+  result: DatasetMutationResponse,
+): string[] {
+  const lines: string[] = [];
+  lines.push(`**Name**: ${escapeMarkdown(result.name)}`);
+  lines.push(`**Slug**: ${escapeMarkdown(result.slug)}`);
+  lines.push(`**ID**: ${escapeMarkdown(result.id)}`);
+  if (Array.isArray(result.columnTypes) && result.columnTypes.length > 0) {
+    const colNames = result.columnTypes
+      .map((c) => `${escapeMarkdown(c.name)} (${escapeMarkdown(c.type)})`)
+      .join(", ");
+    lines.push(`**Columns**: ${colNames}`);
+  }
+  return lines;
+}

package/src/tools/get-agent.ts

@@ -0,0 +1,21 @@
+import { getAgent as apiGetAgent } from "../langwatch-api-agents.js";
+
+export async function handleGetAgent(params: { id: string }): Promise<string> {
+  const agent = await apiGetAgent(params.id);
+
+  const lines: string[] = [];
+  lines.push(`# ${agent.name}\n`);
+  lines.push(`**ID**: ${agent.id}`);
+  lines.push(`**Type**: ${agent.type}`);
+  lines.push(`**Created**: ${agent.createdAt}`);
+  lines.push(`**Updated**: ${agent.updatedAt}`);
+
+  if (agent.config && Object.keys(agent.config).length > 0) {
+    lines.push("\n## Config\n");
+    lines.push("```json");
+    lines.push(JSON.stringify(agent.config, null, 2));
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/get-analytics.ts

@@ -1,6 +1,20 @@
+import type { AnalyticsBucket } from "../langwatch-api.js";
 import { getAnalyticsTimeseries as apiGetAnalytics } from "../langwatch-api.js";
 import { parseRelativeDate } from "../utils/date-parsing.js";
 
+type GroupedData = Record<string, Record<string, number>>;
+
+function getGroupedData(
+  bucket: AnalyticsBucket,
+  groupBy: string,
+): GroupedData | undefined {
+  const data = bucket[groupBy];
+  if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+    return data as GroupedData;
+  }
+  return undefined;
+}
+
 /**
  * Handles the get_analytics MCP tool invocation.
  *
@@ -49,17 +63,30 @@ export async function handleGetAnalytics(params: {
   const currentPeriod = result.currentPeriod ?? [];
   if (currentPeriod.length === 0) {
     lines.push("No data available for this period.");
+  } else if (
+    params.groupBy &&
+    currentPeriod.some((b) => getGroupedData(b, params.groupBy!) !== undefined)
+  ) {
+    lines.push("| Date | Group | Value |");
+    lines.push("|------|-------|-------|");
+    for (const bucket of currentPeriod) {
+      const groups = getGroupedData(bucket, params.groupBy);
+      if (!groups) continue;
+      for (const [groupKey, metrics] of Object.entries(groups)) {
+        const value =
+          Object.values(metrics).find((v) => typeof v === "number") ?? "N/A";
+        lines.push(`| ${bucket.date} | ${groupKey} | ${value} |`);
+      }
+    }
   } else {
     lines.push("| Date | Value |");
     lines.push("|------|-------|");
     for (const bucket of currentPeriod) {
-      const date = bucket.date;
-      // Find the metric value - it's typically keyed by index
       const value =
         Object.entries(bucket).find(
           ([k]) => k !== "date" && typeof bucket[k] === "number"
         )?.[1] ?? "N/A";
-      lines.push(`| ${date} | ${value} |`);
+      lines.push(`| ${bucket.date} | ${value} |`);
     }
   }
 

package/src/tools/get-dashboard.ts

@@ -0,0 +1,22 @@
+import { getDashboard as apiGetDashboard } from "../langwatch-api-dashboards.js";
+
+export async function handleGetDashboard(params: { id: string }): Promise<string> {
+  const dashboard = await apiGetDashboard(params.id);
+
+  const lines: string[] = [];
+  lines.push(`# ${dashboard.name}\n`);
+  lines.push(`**ID**: ${dashboard.id}`);
+  lines.push(`**Order**: ${dashboard.order}`);
+  lines.push(`**Graphs**: ${Array.isArray(dashboard.graphs) ? dashboard.graphs.length : 0}`);
+  lines.push(`**Created**: ${dashboard.createdAt}`);
+  lines.push(`**Updated**: ${dashboard.updatedAt}`);
+
+  if (Array.isArray(dashboard.graphs) && dashboard.graphs.length > 0) {
+    lines.push("\n## Graphs\n");
+    lines.push("```json");
+    lines.push(JSON.stringify(dashboard.graphs, null, 2));
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/get-dataset.ts

@@ -0,0 +1,63 @@
+import {
+  getDataset as apiGetDataset,
+  type DatasetDetailResponse,
+} from "../langwatch-api-datasets.js";
+import { escapeMarkdown } from "../utils/escape-markdown.js";
+
+/**
+ * Formats a dataset detail response into AI-readable markdown.
+ *
+ * Exported for unit testing.
+ */
+export function formatDatasetResponse(
+  dataset: DatasetDetailResponse,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Dataset: ${escapeMarkdown(dataset.name)}\n`);
+  lines.push(`**Slug**: ${escapeMarkdown(dataset.slug)}`);
+  lines.push(`**ID**: ${escapeMarkdown(dataset.id)}`);
+
+  // Column table
+  if (
+    Array.isArray(dataset.columnTypes) &&
+    dataset.columnTypes.length > 0
+  ) {
+    lines.push("\n## Columns\n");
+    lines.push("| Name | Type |");
+    lines.push("|------|------|");
+    for (const col of dataset.columnTypes) {
+      lines.push(`| ${escapeMarkdown(col.name)} | ${escapeMarkdown(col.type)} |`);
+    }
+  }
+
+  // Record preview
+  if (Array.isArray(dataset.data) && dataset.data.length > 0) {
+    lines.push(`\n## Records (${dataset.data.length} shown)\n`);
+    for (const record of dataset.data) {
+      lines.push(`**${escapeMarkdown(record.id)}**: ${escapeMarkdown(JSON.stringify(record.entry))}`);
+    }
+  } else {
+    lines.push("\nNo records in this dataset.");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Handles the platform_get_dataset MCP tool invocation.
+ *
+ * Retrieves a specific dataset by slug or ID and formats it as
+ * AI-readable markdown or raw JSON.
+ */
+export async function handleGetDataset(params: {
+  slugOrId: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const dataset = await apiGetDataset(params.slugOrId);
+
+  if (params.format === "json") {
+    return JSON.stringify(dataset, null, 2);
+  }
+
+  return formatDatasetResponse(dataset);
+}

package/src/tools/get-prompt.ts

@@ -9,8 +9,9 @@ import { getPrompt as apiGetPrompt } from "../langwatch-api.js";
 export async function handleGetPrompt(params: {
   idOrHandle: string;
   version?: number;
+  tag?: string;
 }): Promise<string> {
-  const prompt = await apiGetPrompt(params.idOrHandle, params.version);
+  const prompt = await apiGetPrompt(params.idOrHandle, { version: params.version, tag: params.tag });
 
   const lines: string[] = [];
   lines.push(

package/src/tools/get-simulation-run.ts

@@ -0,0 +1,60 @@
+import { getSimulationRun as apiGetSimulationRun } from "../langwatch-api-simulation-runs.js";
+
+/**
+ * Handles the platform_get_simulation_run MCP tool invocation.
+ */
+export async function handleGetSimulationRun(params: {
+  scenarioRunId: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const run = await apiGetSimulationRun(params.scenarioRunId);
+
+  if (params.format === "json") {
+    return JSON.stringify(run, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Simulation Run: ${run.name ?? run.scenarioRunId}\n`);
+  lines.push(`**Run ID**: ${run.scenarioRunId}`);
+  lines.push(`**Scenario ID**: ${run.scenarioId}`);
+  lines.push(`**Batch ID**: ${run.batchRunId}`);
+  lines.push(`**Status**: ${run.status}`);
+
+  const duration = run.durationInMs > 0 ? `${(run.durationInMs / 1000).toFixed(1)}s` : "—";
+  lines.push(`**Duration**: ${duration}`);
+  if (run.totalCost) {
+    lines.push(`**Cost**: $${run.totalCost.toFixed(4)}`);
+  }
+  lines.push(`**Started**: ${new Date(run.timestamp).toISOString()}`);
+
+  if (run.results) {
+    lines.push("\n## Results");
+    if (run.results.verdict) {
+      lines.push(`**Verdict**: ${run.results.verdict}`);
+    }
+    if (run.results.reasoning) {
+      lines.push(`**Reasoning**: ${run.results.reasoning}`);
+    }
+    if (run.results.metCriteria && run.results.metCriteria.length > 0) {
+      lines.push(`**Met Criteria**: ${run.results.metCriteria.join(", ")}`);
+    }
+    if (run.results.unmetCriteria && run.results.unmetCriteria.length > 0) {
+      lines.push(`**Unmet Criteria**: ${run.results.unmetCriteria.join(", ")}`);
+    }
+    if (run.results.error) {
+      lines.push(`**Error**: ${run.results.error}`);
+    }
+  }
+
+  if (run.messages && run.messages.length > 0) {
+    lines.push("\n## Conversation");
+    for (const msg of run.messages) {
+      const content = msg.content.length > 300
+        ? msg.content.slice(0, 300) + "..."
+        : msg.content;
+      lines.push(`**[${msg.role}]**: ${content}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/tools/get-suite.ts

@@ -0,0 +1,47 @@
+import { getSuite as apiGetSuite } from "../langwatch-api-suites.js";
+
+/**
+ * Handles the platform_get_suite MCP tool invocation.
+ */
+export async function handleGetSuite(params: {
+  id: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const suite = await apiGetSuite(params.id);
+
+  if (params.format === "json") {
+    return JSON.stringify(suite, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Suite: ${suite.name}\n`);
+  lines.push(`**ID**: ${suite.id}`);
+  lines.push(`**Slug**: ${suite.slug}`);
+  lines.push(`**Description**: ${suite.description ?? "—"}`);
+  lines.push(`**Repeat Count**: ${suite.repeatCount}`);
+  lines.push(`**Created**: ${suite.createdAt}`);
+  lines.push(`**Updated**: ${suite.updatedAt}`);
+
+  if (suite.labels.length > 0) {
+    lines.push(`**Labels**: ${suite.labels.join(", ")}`);
+  }
+
+  lines.push("\n## Scenarios");
+  for (const id of suite.scenarioIds) {
+    lines.push(`- ${id}`);
+  }
+
+  lines.push("\n## Targets");
+  for (const t of suite.targets) {
+    lines.push(`- ${t.type}:${t.referenceId}`);
+  }
+
+  const totalJobs = suite.scenarioIds.length * suite.targets.length * suite.repeatCount;
+  lines.push(`\n**Total jobs per run**: ${totalJobs}`);
+
+  lines.push(
+    "\n> Use `platform_run_suite` to trigger a run, or `platform_update_suite` to modify."
+  );
+
+  return lines.join("\n");
+}

package/src/tools/get-workflow.ts

@@ -0,0 +1,17 @@
+import { getWorkflow as apiGetWorkflow } from "../langwatch-api-workflows.js";
+
+export async function handleGetWorkflow(params: { id: string }): Promise<string> {
+  const workflow = await apiGetWorkflow(params.id);
+
+  const lines: string[] = [];
+  lines.push(`# ${workflow.name}\n`);
+  lines.push(`**ID**: ${workflow.id}`);
+  if (workflow.description) lines.push(`**Description**: ${workflow.description}`);
+  if (workflow.icon) lines.push(`**Icon**: ${workflow.icon}`);
+  lines.push(`**Evaluator**: ${workflow.isEvaluator ? "yes" : "no"}`);
+  lines.push(`**Component**: ${workflow.isComponent ? "yes" : "no"}`);
+  lines.push(`**Created**: ${workflow.createdAt}`);
+  lines.push(`**Updated**: ${workflow.updatedAt}`);
+
+  return lines.join("\n");
+}

package/src/tools/list-agents.ts

@@ -0,0 +1,27 @@
+import { listAgents as apiListAgents } from "../langwatch-api-agents.js";
+
+export async function handleListAgents(): Promise<string> {
+  const result = await apiListAgents({ limit: 100 });
+  const agents = result.data;
+
+  if (!Array.isArray(agents) || agents.length === 0) {
+    return "No agents found in this project.\n\n> Tip: Use `platform_create_agent` to create your first agent.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Agents (${result.pagination.total} total)\n`);
+
+  for (const a of agents) {
+    lines.push(`## ${a.name}`);
+    lines.push(`**ID**: ${a.id}`);
+    lines.push(`**Type**: ${a.type}`);
+    lines.push(`**Updated**: ${a.updatedAt}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_agent` with the ID to see full agent details including config.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-annotations.ts

@@ -0,0 +1,33 @@
+import {
+  listAnnotations as apiListAnnotations,
+  getAnnotationsByTrace as apiGetByTrace,
+} from "../langwatch-api-annotations.js";
+
+export async function handleListAnnotations(params: {
+  traceId?: string;
+}): Promise<string> {
+  const annotations = params.traceId
+    ? await apiGetByTrace(params.traceId)
+    : await apiListAnnotations();
+
+  if (!Array.isArray(annotations) || annotations.length === 0) {
+    return params.traceId
+      ? `No annotations found for trace "${params.traceId}".\n\n> Tip: Use \`platform_create_annotation\` to annotate a trace.`
+      : "No annotations found in this project.\n\n> Tip: Use `platform_create_annotation` to annotate a trace.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Annotations (${annotations.length} total)\n`);
+
+  for (const a of annotations) {
+    const rating = a.isThumbsUp === true ? "👍" : a.isThumbsUp === false ? "👎" : "—";
+    lines.push(`## Annotation ${a.id ?? "—"}`);
+    lines.push(`**Trace ID**: ${a.traceId ?? "—"}`);
+    lines.push(`**Rating**: ${rating}`);
+    if (a.comment) lines.push(`**Comment**: ${a.comment}`);
+    if (a.email) lines.push(`**By**: ${a.email}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/list-dashboards.ts

@@ -0,0 +1,27 @@
+import { listDashboards as apiListDashboards } from "../langwatch-api-dashboards.js";
+
+export async function handleListDashboards(): Promise<string> {
+  const result = await apiListDashboards();
+  const dashboards = result.data;
+
+  if (!Array.isArray(dashboards) || dashboards.length === 0) {
+    return "No dashboards found in this project.\n\n> Tip: Use `platform_create_dashboard` to create a new dashboard.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Dashboards (${dashboards.length} total)\n`);
+
+  for (const d of dashboards) {
+    lines.push(`## ${d.name}`);
+    lines.push(`**ID**: ${d.id}`);
+    lines.push(`**Graphs**: ${d.graphCount}`);
+    lines.push(`**Updated**: ${d.updatedAt}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_dashboard` with the ID to see dashboard details including graphs.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-dataset-records.ts

@@ -0,0 +1,46 @@
+import {
+  listDatasetRecords as apiListDatasetRecords,
+} from "../langwatch-api-datasets.js";
+import { escapeMarkdown } from "../utils/escape-markdown.js";
+
+/**
+ * Handles the platform_list_dataset_records MCP tool invocation.
+ *
+ * Lists records in a dataset with pagination support.
+ */
+export async function handleListDatasetRecords(params: {
+  slugOrId: string;
+  page?: number;
+  limit?: number;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const response = await apiListDatasetRecords({
+    slugOrId: params.slugOrId,
+    page: params.page,
+    limit: params.limit,
+  });
+
+  if (params.format === "json") {
+    return JSON.stringify(response, null, 2);
+  }
+
+  const { data: records, pagination } = response;
+
+  if (records.length === 0) {
+    return "No records found in this dataset.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Records (page ${pagination.page} of ${pagination.totalPages}, ${pagination.total} total)\n`);
+
+  for (const record of records) {
+    lines.push(`**${escapeMarkdown(record.id)}**: ${escapeMarkdown(JSON.stringify(record.entry))}`);
+  }
+
+  if (pagination.page < pagination.totalPages) {
+    lines.push("");
+    lines.push(`> Use \`platform_list_dataset_records\` with \`page: ${pagination.page + 1}\` to see the next page.`);
+  }
+
+  return lines.join("\n");
+}

package/src/tools/list-datasets.ts

@@ -0,0 +1,80 @@
+import {
+  listDatasets as apiListDatasets,
+  type DatasetSummary,
+} from "../langwatch-api-datasets.js";
+import { escapeMarkdown } from "../utils/escape-markdown.js";
+
+/**
+ * Fetches all datasets by paginating through the API until every page
+ * has been retrieved.
+ *
+ * Returns the accumulated dataset summaries along with the total count
+ * reported by the server.
+ */
+async function fetchAllDatasets(): Promise<{
+  datasets: DatasetSummary[];
+  total: number;
+}> {
+  const PAGE_SIZE = 100;
+  const datasets: DatasetSummary[] = [];
+  let page = 1;
+  let total = 0;
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- loop until break
+  while (true) {
+    const response = await apiListDatasets({ page, limit: PAGE_SIZE });
+    total = response.pagination.total;
+    datasets.push(...response.data);
+
+    if (datasets.length >= total || response.data.length === 0) {
+      break;
+    }
+    page++;
+  }
+
+  return { datasets, total };
+}
+
+/**
+ * Handles the platform_list_datasets MCP tool invocation.
+ *
+ * Lists all datasets in the LangWatch project, formatted as an
+ * AI-readable digest or raw JSON.
+ */
+export async function handleListDatasets(params: {
+  format?: "digest" | "json";
+} = {}): Promise<string> {
+  if (params.format === "json") {
+    const { datasets, total } = await fetchAllDatasets();
+    return JSON.stringify({ data: datasets, total }, null, 2);
+  }
+
+  const { datasets, total } = await fetchAllDatasets();
+
+  if (datasets.length === 0) {
+    return "No datasets found in this project.\n\n> Tip: Use `platform_create_dataset` to create your first dataset.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Datasets (${total} total)\n`);
+
+  for (const ds of datasets) {
+    lines.push(`## ${escapeMarkdown(ds.name)}`);
+    lines.push(`**Slug**: ${escapeMarkdown(ds.slug)}`);
+    lines.push(`**ID**: ${ds.id}`);
+    if (Array.isArray(ds.columnTypes) && ds.columnTypes.length > 0) {
+      const colNames = ds.columnTypes.map((c) => c.name).join(", ");
+      lines.push(`**Columns**: ${colNames}`);
+    }
+    lines.push(
+      `**Records**: ${ds.recordCount ?? "unknown"}`,
+    );
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_dataset` with the slug to see full dataset details and records.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-prompt-tags.ts

@@ -0,0 +1,21 @@
+import { listPromptTags as apiListPromptTags } from "../langwatch-api.js";
+
+export async function handleListPromptTags(): Promise<string> {
+  const tags = (await apiListPromptTags()) as Array<{
+    id: string;
+    name: string;
+    createdAt?: string;
+  }>;
+
+  if (!tags || tags.length === 0) {
+    return "No prompt tags found. The `latest` tag is always available.";
+  }
+
+  const lines: string[] = [];
+  lines.push("# Prompt Tags\n");
+  for (const tag of tags) {
+    const created = tag.createdAt ? ` (created ${tag.createdAt})` : "";
+    lines.push(`- **${tag.name}**${created}`);
+  }
+  return lines.join("\n");
+}

package/src/tools/list-simulation-runs.ts

@@ -0,0 +1,49 @@
+import { listSimulationRuns as apiListSimulationRuns } from "../langwatch-api-simulation-runs.js";
+
+/**
+ * Handles the platform_list_simulation_runs MCP tool invocation.
+ */
+export async function handleListSimulationRuns(params: {
+  scenarioSetId?: string;
+  batchRunId?: string;
+  limit?: number;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const result = await apiListSimulationRuns({
+    scenarioSetId: params.scenarioSetId,
+    batchRunId: params.batchRunId,
+    limit: params.limit,
+  });
+
+  if (params.format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+
+  const { runs } = result;
+
+  if (runs.length === 0) {
+    return "No simulation runs found.\n\n> Run a suite first with `platform_run_suite` to create simulation runs.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Simulation Runs (${runs.length} results${result.hasMore ? ", more available" : ""})\n`);
+
+  for (const run of runs) {
+    const statusIcon = run.status === "SUCCESS" ? "pass" : run.status === "FAILED" ? "FAIL" : run.status;
+    const duration = run.durationInMs > 0 ? `${(run.durationInMs / 1000).toFixed(1)}s` : "—";
+    const verdict = run.results?.verdict ?? "";
+
+    lines.push(`## ${run.name ?? run.scenarioId} — ${statusIcon}${verdict ? ` (${verdict})` : ""}`);
+    lines.push(`**Run ID**: ${run.scenarioRunId}`);
+    lines.push(`**Batch**: ${run.batchRunId}`);
+    lines.push(`**Duration**: ${duration}`);
+    if (run.totalCost) {
+      lines.push(`**Cost**: $${run.totalCost.toFixed(4)}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("> Use `platform_get_simulation_run` with a run ID to see full details (messages, results).");
+
+  return lines.join("\n");
+}

package/src/tools/list-suites.ts

@@ -0,0 +1,43 @@
+import { listSuites as apiListSuites } from "../langwatch-api-suites.js";
+
+/**
+ * Handles the platform_list_suites MCP tool invocation.
+ */
+export async function handleListSuites(params: {
+  format?: "digest" | "json";
+}): Promise<string> {
+  const suites = await apiListSuites();
+
+  if (params.format === "json") {
+    return JSON.stringify(suites, null, 2);
+  }
+
+  if (!Array.isArray(suites) || suites.length === 0) {
+    return "No suites (run plans) found in this project.\n\n> Tip: Use `platform_create_suite` to create your first suite.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Suites / Run Plans (${suites.length} total)\n`);
+
+  for (const s of suites) {
+    lines.push(`## ${s.name}`);
+    lines.push(`**ID**: ${s.id}`);
+    lines.push(`**Slug**: ${s.slug}`);
+    lines.push(`**Scenarios**: ${s.scenarioIds.length}`);
+    lines.push(`**Targets**: ${s.targets.length} (${s.targets.map((t) => `${t.type}:${t.referenceId}`).join(", ")})`);
+    lines.push(`**Repeat**: ${s.repeatCount}x`);
+    if (s.description) {
+      lines.push(`**Description**: ${s.description}`);
+    }
+    if (Array.isArray(s.labels) && s.labels.length > 0) {
+      lines.push(`**Labels**: ${s.labels.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_suite` with the ID to see full details, or `platform_run_suite` to trigger execution."
+  );
+
+  return lines.join("\n");
+}