@langwatch/mcp-server 1.0.0 → 2.1.0

package/src/tools/format-suite-details.ts

@@ -0,0 +1,96 @@
+import type {
+  EvaluatorAttachmentWire,
+  ScenarioMapping,
+  SuiteField,
+} from "../schemas/suite-fields.js";
+
+/**
+ * The digest lines for a suite's fields, the evaluators attached to a suite
+ * or a plan, and the evaluator results on a finished run. Shared by every
+ * tool that prints one of them.
+ */
+
+/** A mapping as one short path: `scenario.fields.golden_sql` or `"literal"`. */
+export function describeMapping(mapping: ScenarioMapping): string {
+  return mapping.type === "value"
+    ? JSON.stringify(mapping.value)
+    : `${mapping.sourceId}.${mapping.path.join(".")}`;
+}
+
+export function formatSuiteFields(fields: SuiteField[] | undefined): string[] {
+  if (!fields || fields.length === 0) return [];
+  return [
+    "\n## Fields",
+    ...fields.map((field) => `- ${field.identifier} (${field.type})`),
+  ];
+}
+
+export function formatEvaluatorAttachments(
+  evaluators: EvaluatorAttachmentWire[] | undefined,
+): string[] {
+  if (!evaluators || evaluators.length === 0) return [];
+  const lines = ["\n## Evaluators"];
+  for (const attachment of evaluators) {
+    const gate = attachment.required ? "required" : "reports only";
+    lines.push(`- ${attachment.evaluatorId} (${gate}, attachment ${attachment.id})`);
+    for (const [input, mapping] of Object.entries(attachment.mappings)) {
+      lines.push(`  - ${input}: ${describeMapping(mapping)}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * The status the platform reports while a run's evaluators have not been
+ * recorded yet. The conversation is over and the judge has decided, but a
+ * required evaluator can still turn the run red, so a caller must not read
+ * the verdict as final.
+ */
+export const PENDING_EVALUATION_STATUS = "PENDING_EVALUATION";
+
+/** How a run's status reads in a digest. */
+export function formatRunStatus(status: string): string {
+  if (status === PENDING_EVALUATION_STATUS) return "evaluating";
+  if (status === "SUCCESS") return "pass";
+  if (status === "FAILED") return "FAIL";
+  return status;
+}
+
+/**
+ * The line that warns a caller off a run's verdict while its evaluators are
+ * still to be recorded, or nothing when they already are.
+ */
+export function pendingEvaluationNote(status: string): string[] {
+  if (status !== PENDING_EVALUATION_STATUS) return [];
+  return [
+    "> The evaluators attached to this run have not been recorded yet. A required one may still fail it, so read the verdict again once the status changes.",
+  ];
+}
+
+/** One evaluator's result on a finished run. */
+export interface SimulationRunEvaluation {
+  evaluatorId: string;
+  name: string;
+  status: "passed" | "failed" | "scored" | "skipped" | "error";
+  required: boolean;
+  passed?: boolean;
+  score?: number;
+  label?: string;
+  details?: string;
+}
+
+export function formatEvaluations(
+  evaluations: SimulationRunEvaluation[] | undefined,
+): string[] {
+  if (!evaluations || evaluations.length === 0) return [];
+  const lines = ["\n## Evaluators"];
+  for (const evaluation of evaluations) {
+    const parts: string[] = [evaluation.status];
+    if (evaluation.score !== undefined) parts.push(`score ${evaluation.score}`);
+    if (evaluation.label !== undefined) parts.push(evaluation.label);
+    if (evaluation.required) parts.push("required");
+    lines.push(`- **${evaluation.name}**: ${parts.join(", ")}`);
+    if (evaluation.details) lines.push(`  ${evaluation.details}`);
+  }
+  return lines;
+}

package/src/tools/get-agent.ts

@@ -1,15 +1,57 @@
-import { getAgent as apiGetAgent } from "../langwatch-api-agents.js";
+import { getAgent as apiGetAgent, type AgentParameterSpec } from "../langwatch-api-agents.js";
 
-export async function handleGetAgent(params: { id: string }): Promise<string> {
-  const agent = await apiGetAgent(params.id);
+export const describeParameter = ({
+  name,
+  type,
+  options,
+  default: defaultValue,
+  description,
+  required,
+}: AgentParameterSpec): string => {
+  const parts: string[] = [type];
+  if (options?.length) parts.push(`one of ${options.join(", ")}`);
+  if (defaultValue !== undefined) parts.push(`default ${JSON.stringify(defaultValue)}`);
+  if (required) parts.push("required");
+  const suffix = description ? `: ${description}` : "";
+  return `- **${name}** (${parts.join(", ")})${suffix}`;
+};
+
+/**
+ * Handles the platform_get_agent MCP tool invocation.
+ *
+ * @see specs/mcp-server/agent-tools.feature
+ */
+export async function handleGetAgent({ id }: { id: string }): Promise<string> {
+  const agent = await apiGetAgent(id);
 
   const lines: string[] = [];
   lines.push(`# ${agent.name}\n`);
   lines.push(`**ID**: ${agent.id}`);
   lines.push(`**Type**: ${agent.type}`);
+  if (agent.environment) lines.push(`**Environment**: ${agent.environment}`);
+  if (agent.status) lines.push(`**Status**: ${agent.status}`);
+  if (agent.owner?.name) lines.push(`**Owner**: ${agent.owner.name}`);
+  else if (agent.hostLabel) lines.push(`**Host**: ${agent.hostLabel}`);
+  if (agent.selectable === false) {
+    lines.push("**Run**: only its owner can run this agent");
+  }
+  if (agent.lastSeenAt) lines.push(`**Last seen**: ${agent.lastSeenAt}`);
   lines.push(`**Created**: ${agent.createdAt}`);
   lines.push(`**Updated**: ${agent.updatedAt}`);
 
+  if (agent.parameters && agent.parameters.length > 0) {
+    lines.push("\n## Parameters\n");
+    for (const parameter of agent.parameters) lines.push(describeParameter(parameter));
+  }
+
+  if (agent.instances && agent.instances.length > 0) {
+    lines.push(`\n## Instances (${agent.instances.length})\n`);
+    for (const instance of agent.instances) {
+      const label = instance.label ? ` (${instance.label})` : "";
+      lines.push(`- ${instance.hostname || instance.id}${label}, connected ${instance.connectedAt}`);
+    }
+  }
+
   if (agent.config && Object.keys(agent.config).length > 0) {
     lines.push("\n## Config\n");
     lines.push("```json");

package/src/tools/get-prompt.ts

@@ -1,53 +1,137 @@
 import { getPrompt as apiGetPrompt } from "../langwatch-api.js";
 
+interface DeploymentTag {
+  name: string;
+  versionId?: string;
+}
+
+/**
+ * Normalizes one tag entry from the API. The API returns tag objects
+ * ({ name, versionId }); plain strings are tolerated so a shape drift can
+ * never crash the tool.
+ */
+function normalizeTag(tag: unknown): DeploymentTag | undefined {
+  if (typeof tag === "string") return { name: tag };
+  if (tag && typeof tag === "object" && "name" in tag) {
+    const candidate = tag as { name: unknown; versionId?: unknown };
+    if (typeof candidate.name === "string") {
+      return {
+        name: candidate.name,
+        versionId:
+          typeof candidate.versionId === "string"
+            ? candidate.versionId
+            : undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
 /**
  * Handles the platform_get_prompt MCP tool invocation.
  *
- * Retrieves a specific prompt by ID or handle and formats it as
- * AI-readable markdown, including messages, model config, and version history.
+ * Retrieves a specific prompt by ID or handle. The API returns the requested
+ * version's data flattened to the top level (version, versionId, model,
+ * messages, inputs/outputs, parameters, tags). Defaults to an AI-readable
+ * markdown digest; `format: "json"` instead returns the raw API payload
+ * verbatim.
  */
 export async function handleGetPrompt(params: {
   idOrHandle: string;
   version?: number;
   tag?: string;
+  format?: "digest" | "json";
 }): Promise<string> {
-  const prompt = await apiGetPrompt(params.idOrHandle, { version: params.version, tag: params.tag });
+  const prompt = await apiGetPrompt(params.idOrHandle, {
+    version: params.version,
+    tag: params.tag,
+  });
+
+  if (params.format === "json") {
+    return JSON.stringify(prompt, null, 2);
+  }
 
   const lines: string[] = [];
-  lines.push(
-    `# Prompt: ${prompt.name || prompt.handle || prompt.id}\n`
-  );
+  lines.push(`# Prompt: ${prompt.name || prompt.handle || prompt.id}\n`);
 
   if (prompt.handle) lines.push(`**Handle**: ${prompt.handle}`);
   if (prompt.id) lines.push(`**ID**: ${prompt.id}`);
-  if (prompt.latestVersionNumber != null)
-    lines.push(`**Latest Version**: v${prompt.latestVersionNumber}`);
+  if (prompt.version != null) lines.push(`**Version**: v${prompt.version}`);
+  if (prompt.versionId) lines.push(`**Version ID**: ${prompt.versionId}`);
+  if (prompt.commitMessage) lines.push(`**Commit**: ${prompt.commitMessage}`);
+  if (prompt.model) lines.push(`**Model**: ${prompt.model}`);
+  if (prompt.temperature != null)
+    lines.push(`**Temperature**: ${prompt.temperature}`);
+  if (prompt.maxTokens != null)
+    lines.push(`**Max Tokens**: ${prompt.maxTokens}`);
+  if (prompt.responseFormat)
+    lines.push(`**Response Format**: ${JSON.stringify(prompt.responseFormat)}`);
+
+  // Renders a field list of any shape the API may return: an array of
+  // { identifier, type } entries (inputs/outputs), an object map of
+  // name -> value (parameters), or absent/empty (no heading at all).
+  const renderFieldList = ({
+    heading,
+    fields,
+  }: {
+    heading: string;
+    fields: unknown;
+  }) => {
+    const entries: string[] = [];
+    if (Array.isArray(fields)) {
+      for (const field of fields) {
+        if (field && typeof field === "object" && "identifier" in field) {
+          const typed = field as { identifier: unknown; type?: unknown };
+          entries.push(
+            `- **${String(typed.identifier)}**: ${String(typed.type ?? "unknown")}`
+          );
+        } else {
+          entries.push(`- ${JSON.stringify(field)}`);
+        }
+      }
+    } else if (fields && typeof fields === "object") {
+      for (const [key, value] of Object.entries(fields)) {
+        entries.push(`- **${key}**: ${JSON.stringify(value)}`);
+      }
+    }
+    if (entries.length === 0) return;
+    lines.push(`\n**${heading}**`);
+    lines.push(...entries);
+  };
 
-  // Show model config
-  const version = prompt.versions?.[0] ?? prompt;
-  if (version.model) lines.push(`**Model**: ${version.model}`);
+  renderFieldList({ heading: "Parameters", fields: prompt.parameters });
+  renderFieldList({ heading: "Inputs", fields: prompt.inputs });
+  renderFieldList({ heading: "Outputs", fields: prompt.outputs });
 
-  // Show messages
-  const messages = version.messages || prompt.prompt || [];
+  const messages = prompt.messages;
   if (Array.isArray(messages) && messages.length > 0) {
     lines.push("\n## Messages");
     for (const msg of messages) {
       lines.push(`\n### ${msg.role}`);
       lines.push(msg.content);
     }
+  } else if (typeof prompt.prompt === "string" && prompt.prompt.length > 0) {
+    lines.push("\n## Messages");
+    lines.push("\n### system");
+    lines.push(prompt.prompt);
   }
 
-  // Show version history
-  if (prompt.versions && prompt.versions.length > 0) {
-    lines.push("\n## Version History");
-    for (const v of prompt.versions.slice(0, 10)) {
-      const versionNum = v.version ?? "?";
-      const commitMsg = v.commitMessage || "No message";
-      lines.push(`- **v${versionNum}**: ${commitMsg}`);
-    }
-    if (prompt.versions.length > 10) {
-      lines.push(`... and ${prompt.versions.length - 10} more versions`);
-    }
+  // Deployments: every non-"latest" tag on the prompt, each shown with the
+  // version it currently points to. Always rendered, even when empty, so an
+  // empty section is never mistaken for "not checked" — and a tag pointing
+  // at another version is listed truthfully against that version instead of
+  // being implied undeployed.
+  lines.push("\n## Deployments");
+  const tags = Array.isArray(prompt.tags) ? prompt.tags : [];
+  for (const rawTag of tags) {
+    const tag = normalizeTag(rawTag);
+    if (!tag || tag.name === "latest") continue;
+    const target = tag.versionId ?? "unknown version";
+    const marker =
+      tag.versionId && tag.versionId === prompt.versionId
+        ? " (this version)"
+        : "";
+    lines.push(`- ${tag.name} → ${target}${marker}`);
   }
 
   return lines.join("\n");

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

@@ -0,0 +1,62 @@
+import { getRunPlan as apiGetRunPlan } from "../langwatch-api-run-plans.js";
+import { describeRunPlanScope } from "./format-run-plan.js";
+import { formatEvaluatorAttachments } from "./format-suite-details.js";
+
+/**
+ * Handles the platform_get_run_plan MCP tool invocation.
+ */
+export async function handleGetRunPlan(params: {
+  id: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const plan = await apiGetRunPlan(params.id);
+
+  if (params.format === "json") {
+    return JSON.stringify(plan, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Run Plan: ${plan.name}\n`);
+  lines.push(`**ID**: ${plan.id}`);
+  lines.push(`**Slug**: ${plan.slug}`);
+  lines.push(`**Covers**: ${describeRunPlanScope(plan.scope, plan.scenarioIds)}`);
+  lines.push(`**Repeat**: ${plan.repeatCount}x`);
+  lines.push(`**Simulator model**: ${plan.simulatorModel ?? "project default"}`);
+  lines.push(`**Judge model**: ${plan.judgeModel ?? "project default"}`);
+  if (plan.labels.length > 0) {
+    lines.push(`**Labels**: ${plan.labels.join(", ")}`);
+  }
+  if (plan.archivedAt) {
+    lines.push(`**Archived**: ${plan.archivedAt}`);
+  }
+  lines.push(`**Created**: ${plan.createdAt}`);
+  lines.push(`**Updated**: ${plan.updatedAt}`);
+
+  lines.push("\n## Targets");
+  for (const target of plan.targets) {
+    // The parameters are part of the target's identity, so a plan that
+    // compares one agent on two models reads as two lines that differ.
+    const overrides = Object.entries(target.runParameters ?? {})
+      .map(([name, value]) => `${name}=${String(value)}`)
+      .join(", ");
+    lines.push(
+      `- ${target.type}:${target.referenceId}${overrides ? ` (${overrides})` : ""}`,
+    );
+  }
+
+  if (plan.scenarioIds.length > 0) {
+    lines.push("\n## Scenarios");
+    for (const id of plan.scenarioIds) {
+      lines.push(`- ${id}`);
+    }
+  }
+
+  lines.push(...formatEvaluatorAttachments(plan.evaluators));
+
+  lines.push(`\n**View**: ${plan.platformUrl}`);
+  lines.push(
+    "\n> Use `platform_rerun_run_plan` to run this configuration again, or `platform_run_plan` with this name to replace it.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/get-scenario.ts

@@ -1,4 +1,5 @@
 import { getScenario as apiGetScenario } from "../langwatch-api-scenarios.js";
+import { formatScenarioFields } from "./format-scenario.js";
 
 /**
  * Handles the get_scenario MCP tool invocation.
@@ -32,5 +33,7 @@ export async function handleGetScenario(params: {
     lines.push(`\n**Labels**: ${scenario.labels.join(", ")}`);
   }
 
+  lines.push(...formatScenarioFields(scenario.fields));
+
   return lines.join("\n");
 }

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

@@ -1,4 +1,8 @@
 import { getSimulationRun as apiGetSimulationRun } from "../langwatch-api-simulation-runs.js";
+import {
+  formatEvaluations,
+  pendingEvaluationNote,
+} from "./format-suite-details.js";
 
 /**
  * Handles the platform_get_simulation_run MCP tool invocation.
@@ -19,6 +23,7 @@ export async function handleGetSimulationRun(params: {
   lines.push(`**Scenario ID**: ${run.scenarioId}`);
   lines.push(`**Batch ID**: ${run.batchRunId}`);
   lines.push(`**Status**: ${run.status}`);
+  lines.push(...pendingEvaluationNote(run.status));
 
   const duration = run.durationInMs > 0 ? `${(run.durationInMs / 1000).toFixed(1)}s` : "—";
   lines.push(`**Duration**: ${duration}`);
@@ -26,6 +31,9 @@ export async function handleGetSimulationRun(params: {
     lines.push(`**Cost**: $${run.totalCost.toFixed(4)}`);
   }
   lines.push(`**Started**: ${new Date(run.timestamp).toISOString()}`);
+  if (run.note) {
+    lines.push(`**Note**: ${run.note}`);
+  }
 
   if (run.results) {
     lines.push("\n## Results");
@@ -44,6 +52,7 @@ export async function handleGetSimulationRun(params: {
     if (run.results.error) {
       lines.push(`**Error**: ${run.results.error}`);
     }
+    lines.push(...formatEvaluations(run.results.evaluations));
   }
 
   if (run.messages && run.messages.length > 0) {

package/src/tools/get-test-suite.ts

@@ -0,0 +1,49 @@
+import { getTestSuite as apiGetTestSuite } from "../langwatch-api-test-suites.js";
+import {
+  formatEvaluatorAttachments,
+  formatSuiteFields,
+} from "./format-suite-details.js";
+
+/**
+ * Handles the platform_get_test_suite MCP tool invocation.
+ */
+export async function handleGetTestSuite(params: {
+  id: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const suite = await apiGetTestSuite(params.id);
+
+  if (params.format === "json") {
+    return JSON.stringify(suite, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Test Suite: ${suite.name}\n`);
+  lines.push(`**ID**: ${suite.id}`);
+  lines.push(`**Slug**: ${suite.slug}`);
+  lines.push(`**Scenarios**: ${suite.scenarioCount}`);
+  if (suite.archivedAt) {
+    lines.push(`**Archived**: ${suite.archivedAt}`);
+  }
+  lines.push(`**Created**: ${suite.createdAt}`);
+  lines.push(`**Updated**: ${suite.updatedAt}`);
+
+  lines.push(...formatSuiteFields(suite.fields));
+  lines.push(...formatEvaluatorAttachments(suite.evaluators));
+
+  lines.push("\n## Scenarios");
+  if (suite.scenarios.length === 0) {
+    lines.push("None filed yet.");
+  } else {
+    for (const scenario of suite.scenarios) {
+      lines.push(`- ${scenario.name} (${scenario.id})`);
+    }
+  }
+
+  lines.push(`\n**View**: ${suite.platformUrl}`);
+  lines.push(
+    "\n> Use `platform_run_test_suite` to run every scenario of this suite against a target.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-agents.ts

@@ -1,11 +1,20 @@
-import { listAgents as apiListAgents } from "../langwatch-api-agents.js";
+import { listAgents as apiListAgents, type AgentSummary } from "../langwatch-api-agents.js";
 
+/** Who a personal or host-scoped agent belongs to, empty for a shared one. */
+export const agentOwnerLabel = (agent: AgentSummary): string =>
+  agent.owner?.name ?? agent.hostLabel ?? "";
+
+/**
+ * Handles the platform_list_agents MCP tool invocation.
+ *
+ * @see specs/mcp-server/agent-tools.feature
+ */
 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.";
+    return "No agents found in this project.\n\n> Tip: connect one from code with `connectAgent` (TypeScript, `langwatch/agent`) or `connect_agent` (Python), or use `platform_create_agent` for an HTTP agent.";
   }
 
   const lines: string[] = [];
@@ -15,12 +24,20 @@ export async function handleListAgents(): Promise<string> {
     lines.push(`## ${a.name}`);
     lines.push(`**ID**: ${a.id}`);
     lines.push(`**Type**: ${a.type}`);
+    if (a.environment) lines.push(`**Environment**: ${a.environment}`);
+    if (a.status) lines.push(`**Status**: ${a.status}`);
+    if (a.instances) lines.push(`**Instances**: ${a.instances.length}`);
+    const owner = agentOwnerLabel(a);
+    if (owner) lines.push(`**Owner**: ${owner}`);
+    if (a.selectable === false) {
+      lines.push("**Run**: only its owner can run this agent");
+    }
     lines.push(`**Updated**: ${a.updatedAt}`);
     lines.push("");
   }
 
   lines.push(
-    "> Use `platform_get_agent` with the ID to see full agent details including config.",
+    "> Use `platform_get_agent` with the ID to see full agent details including parameters, instances and config.",
   );
 
   return lines.join("\n");

package/src/tools/list-run-plans.ts

@@ -0,0 +1,47 @@
+import { listRunPlans as apiListRunPlans } from "../langwatch-api-run-plans.js";
+import { describeRunPlanScope } from "./format-run-plan.js";
+
+/**
+ * Handles the platform_list_run_plans MCP tool invocation.
+ */
+export async function handleListRunPlans(params: {
+  includeArchived?: boolean;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const plans = await apiListRunPlans({
+    includeArchived: params.includeArchived,
+  });
+
+  if (params.format === "json") {
+    return JSON.stringify(plans, null, 2);
+  }
+
+  if (!Array.isArray(plans) || plans.length === 0) {
+    return "No run plans found in this project.\n\n> Tip: Use `platform_run_plan` to start one. A run plan is created the first time you run its name.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Run Plans (${plans.length} total)\n`);
+
+  for (const plan of plans) {
+    lines.push(`## ${plan.name}${plan.archivedAt ? " (archived)" : ""}`);
+    lines.push(`**ID**: ${plan.id}`);
+    lines.push(`**Covers**: ${describeRunPlanScope(plan.scope, plan.scenarioIds)}`);
+    lines.push(
+      `**Targets**: ${plan.targets.length} (${plan.targets
+        .map((t) => `${t.type}:${t.referenceId}`)
+        .join(", ")})`,
+    );
+    lines.push(`**Repeat**: ${plan.repeatCount}x`);
+    if (plan.labels.length > 0) {
+      lines.push(`**Labels**: ${plan.labels.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_run_plan` with the ID for the full configuration, or `platform_rerun_run_plan` to run it again.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-scenarios.ts

@@ -7,16 +7,26 @@ import { listScenarios as apiListScenarios } from "../langwatch-api-scenarios.js
  * AI-readable digest or raw JSON.
  */
 export async function handleListScenarios(params: {
+  testSuiteId?: string;
   format?: "digest" | "json";
 }): Promise<string> {
-  const scenarios = await apiListScenarios();
+  const all = await apiListScenarios();
+
+  // The REST list takes no test suite query, so the filter runs here on the
+  // testSuiteId every scenario already carries in the response.
+  const scenarios =
+    params.testSuiteId !== undefined && Array.isArray(all)
+      ? all.filter((s) => s.testSuiteId === params.testSuiteId)
+      : all;
 
   if (params.format === "json") {
     return JSON.stringify(scenarios, null, 2);
   }
 
   if (!Array.isArray(scenarios) || scenarios.length === 0) {
-    return "No scenarios found in this project.\n\n> Tip: Use `platform_create_scenario` to create your first scenario.";
+    return params.testSuiteId !== undefined
+      ? `No scenarios found in test suite ${params.testSuiteId}.\n\n> Tip: Use \`platform_create_scenario\` with testSuiteId \`${params.testSuiteId}\` to file one there.`
+      : "No scenarios found in this project.\n\n> Tip: Use `platform_create_scenario` to create your first scenario.";
   }
 
   const lines: string[] = [];

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

@@ -1,4 +1,5 @@
 import { listSimulationRuns as apiListSimulationRuns } from "../langwatch-api-simulation-runs.js";
+import { formatRunStatus } from "./format-suite-details.js";
 
 /**
  * Handles the platform_list_simulation_runs MCP tool invocation.
@@ -22,14 +23,14 @@ export async function handleListSimulationRuns(params: {
   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.";
+    return "No simulation runs found.\n\n> Run scenarios first with `platform_run_plan` or `platform_run_test_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 statusIcon = formatRunStatus(run.status);
     const duration = run.durationInMs > 0 ? `${(run.durationInMs / 1000).toFixed(1)}s` : "—";
     const verdict = run.results?.verdict ?? "";
 
@@ -40,6 +41,9 @@ export async function handleListSimulationRuns(params: {
     if (run.totalCost) {
       lines.push(`**Cost**: $${run.totalCost.toFixed(4)}`);
     }
+    if (run.note) {
+      lines.push(`**Note**: ${run.note}`);
+    }
     lines.push("");
   }
 

package/src/tools/list-test-suites.ts

@@ -0,0 +1,35 @@
+import { listTestSuites as apiListTestSuites } from "../langwatch-api-test-suites.js";
+
+/**
+ * Handles the platform_list_test_suites MCP tool invocation.
+ */
+export async function handleListTestSuites(params: {
+  format?: "digest" | "json";
+}): Promise<string> {
+  const suites = await apiListTestSuites();
+
+  if (params.format === "json") {
+    return JSON.stringify(suites, null, 2);
+  }
+
+  if (!Array.isArray(suites) || suites.length === 0) {
+    return "No test suites found in this project.\n\n> Tip: Use `platform_create_test_suite` to create one, then file scenarios in it with `testSuiteId`.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Test Suites (${suites.length} total)\n`);
+
+  for (const suite of suites) {
+    lines.push(`## ${suite.name}${suite.archivedAt ? " (archived)" : ""}`);
+    lines.push(`**ID**: ${suite.id}`);
+    lines.push(`**Slug**: ${suite.slug}`);
+    lines.push(`**Scenarios**: ${suite.scenarioCount}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_test_suite` with the ID to read the scenarios, or `platform_run_test_suite` to run them against a target.",
+  );
+
+  return lines.join("\n");
+}