@langwatch/mcp-server 0.3.3 → 0.5.0

package/src/tools/create-scenario.ts

@@ -0,0 +1,30 @@
+import { createScenario as apiCreateScenario } from "../langwatch-api-scenarios.js";
+
+/**
+ * Handles the create_scenario MCP tool invocation.
+ *
+ * Creates a new scenario in the LangWatch project and returns a
+ * confirmation with the created scenario's details.
+ */
+export async function handleCreateScenario(params: {
+  name: string;
+  situation: string;
+  criteria?: string[];
+  labels?: string[];
+}): Promise<string> {
+  const result = await apiCreateScenario(params);
+
+  const lines: string[] = [];
+  lines.push("Scenario created successfully!\n");
+  lines.push(`**ID**: ${result.id}`);
+  lines.push(`**Name**: ${result.name}`);
+  lines.push(`**Situation**: ${result.situation}`);
+  if (Array.isArray(result.criteria) && result.criteria.length > 0) {
+    lines.push(`**Criteria**: ${result.criteria.length} criteria`);
+  }
+  if (Array.isArray(result.labels) && result.labels.length > 0) {
+    lines.push(`**Labels**: ${result.labels.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}

package/src/tools/discover-scenario-schema.ts

@@ -0,0 +1,71 @@
+/**
+ * Returns a human-readable description of the scenario schema,
+ * including field descriptions, authoring guidance, and examples.
+ */
+export function formatScenarioSchema(): string {
+  const lines: string[] = [];
+
+  lines.push("# Scenario Schema\n");
+
+  lines.push("## Fields\n");
+  lines.push(
+    '- **name** (required): A short, descriptive name (e.g., "billing dispute resolution", "password reset with 2FA unavailable")',
+  );
+  lines.push(
+    "- **situation** (required): The context that guides the user simulator — who the user is, what they want, and any constraints (see Writing a Good Situation below)",
+  );
+  lines.push(
+    "- **criteria** (array of strings): Pass/fail conditions a judge evaluates the agent against (see Writing Good Criteria below)",
+  );
+  lines.push(
+    '- **labels** (array of strings): Tags for organizing scenarios (e.g., "auth", "happy-path", "edge-case")',
+  );
+
+  lines.push("\n## Writing a Good Situation\n");
+  lines.push(
+    "The situation drives the user simulator. Include these elements:",
+  );
+  lines.push("- **Persona**: Who is the user? (e.g., a stressed small business owner, a confused teenager)");
+  lines.push("- **Emotional state**: How are they feeling? (e.g., frustrated, anxious, impatient)");
+  lines.push("- **Background/Context**: What happened before this conversation?");
+  lines.push("- **Intent**: What do they want to accomplish?");
+  lines.push("- **Constraints**: What limitations do they have? (e.g., no phone for 2FA, unfamiliar with technical terms)");
+  lines.push("\nExample:");
+  lines.push("```");
+  lines.push("User is a small business owner stressed about tax deadline.");
+  lines.push("They need help categorizing expenses but aren't familiar with");
+  lines.push("accounting terms. They appreciate patient explanations and examples.");
+  lines.push("They have a spreadsheet of transactions but aren't sure which");
+  lines.push("categories apply to their consulting business.");
+  lines.push("```");
+
+  lines.push("\n## Writing Good Criteria\n");
+  lines.push("Criteria are what the judge uses to pass or fail the agent. Each criterion should be:");
+  lines.push("- **Specific and testable** — not vague like \"responds helpfully\"");
+  lines.push("- **Behavioral** — describes what the agent should *do*, not how it works internally");
+  lines.push("- **Independent** — each criterion checks one thing");
+  lines.push("\nGood criteria patterns:");
+  lines.push("- **Information gathering**: \"Agent asks for the user's account number before proceeding\"");
+  lines.push("- **Safety/guardrails**: \"Agent does not reveal internal system details or error stack traces\"");
+  lines.push("- **Clarification**: \"Agent asks clarifying questions before taking irreversible action\"");
+  lines.push("- **Tone**: \"Agent maintains a professional and empathetic tone throughout\"");
+  lines.push("- **Completeness**: \"Agent confirms the user understands the solution before ending\"");
+  lines.push("- **Domain-specific**: \"Agent recommends releasing a wild frog rather than keeping it as a pet\"");
+  lines.push("\nAvoid vague criteria like:");
+  lines.push('- "Responds correctly" — correct how?');
+  lines.push('- "Is helpful" — helpful in what way?');
+  lines.push('- "Works well" — not testable');
+
+  lines.push("\n## Target Types\n");
+  lines.push("Scenarios can target different execution backends:");
+  lines.push("- **prompt**: Test a prompt template with variable substitution");
+  lines.push("- **http**: Test an HTTP endpoint (e.g., a deployed agent API)");
+  lines.push("- **code**: Test a code function directly");
+
+  lines.push("\n## Tips\n");
+  lines.push("- Start simple, then layer complexity (add constraints, edge cases)");
+  lines.push("- Test edge cases: user changes their mind, gives ambiguous input, makes mistakes");
+  lines.push("- Use `fetch_scenario_docs` for the full authoring guide and advanced patterns");
+
+  return lines.join("\n");
+}

package/src/tools/discover-schema.ts

@@ -0,0 +1,106 @@
+import { filterFields } from "../schemas/filter-fields.js";
+import { analyticsMetrics } from "../schemas/analytics-metrics.js";
+import { analyticsGroups } from "../schemas/analytics-groups.js";
+
+export type Category =
+  | "filters"
+  | "metrics"
+  | "aggregations"
+  | "groups"
+  | "all";
+
+/**
+ * Formats the LangWatch analytics schema into human-readable markdown.
+ *
+ * Returns documentation for the requested category of schema elements
+ * (filter fields, metrics, aggregation types, or group-by options).
+ */
+export function formatSchema(category: Category): string {
+  const sections: string[] = [];
+
+  if (category === "filters" || category === "all") {
+    sections.push(formatFilters());
+  }
+  if (category === "metrics" || category === "all") {
+    sections.push(formatMetrics());
+  }
+  if (category === "aggregations" || category === "all") {
+    sections.push(formatAggregations());
+  }
+  if (category === "groups" || category === "all") {
+    sections.push(formatGroups());
+  }
+
+  return sections.join("\n\n");
+}
+
+function formatFilters(): string {
+  const lines = ["## Available Filter Fields", ""];
+  lines.push(
+    "Use these in the `filters` parameter of `search_traces` and `get_analytics`."
+  );
+  lines.push('Format: `{ "field_name": ["value1", "value2"] }`');
+  lines.push("");
+  for (const f of filterFields) {
+    lines.push(
+      `- **${f.field}**: ${f.description}${f.example ? ` (e.g., \`${f.example}\`)` : ""}`
+    );
+  }
+  return lines.join("\n");
+}
+
+function formatMetrics(): string {
+  const lines = ["## Available Metrics", ""];
+  lines.push(
+    "Use these in `get_analytics` as `metric` parameter in `category.name` format."
+  );
+  lines.push("");
+
+  const byCategory = new Map<string, typeof analyticsMetrics>();
+  for (const m of analyticsMetrics) {
+    const list = byCategory.get(m.category) || [];
+    list.push(m);
+    byCategory.set(m.category, list);
+  }
+
+  for (const [cat, metrics] of byCategory) {
+    lines.push(`### ${cat}`);
+    for (const m of metrics) {
+      lines.push(`- **${cat}.${m.name}** (${m.label}): ${m.description}`);
+      lines.push(`  Aggregations: ${m.allowedAggregations.join(", ")}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function formatAggregations(): string {
+  return [
+    "## Available Aggregation Types",
+    "",
+    "- **cardinality**: Count unique values",
+    "- **terms**: Distribution/breakdown of values",
+    "- **avg**: Average",
+    "- **sum**: Sum total",
+    "- **min**: Minimum",
+    "- **max**: Maximum",
+    "- **median**: 50th percentile",
+    "- **p90**: 90th percentile",
+    "- **p95**: 95th percentile",
+    "- **p99**: 99th percentile",
+    "",
+    "Note: Not all aggregations are available for all metrics. Check the metric's allowed aggregations.",
+  ].join("\n");
+}
+
+function formatGroups(): string {
+  const lines = ["## Available Group-By Options", ""];
+  lines.push(
+    "Use these in the `groupBy` parameter of `get_analytics`."
+  );
+  lines.push("");
+  for (const g of analyticsGroups) {
+    lines.push(`- **${g.name}** (${g.label}): ${g.description}`);
+  }
+  return lines.join("\n");
+}

package/src/tools/get-analytics.ts

@@ -0,0 +1,71 @@
+import { getAnalyticsTimeseries as apiGetAnalytics } from "../langwatch-api.js";
+import { parseRelativeDate } from "../utils/date-parsing.js";
+
+/**
+ * Handles the get_analytics MCP tool invocation.
+ *
+ * Queries analytics timeseries from LangWatch and formats the results
+ * as an AI-readable markdown table.
+ */
+export async function handleGetAnalytics(params: {
+  metric: string;
+  aggregation?: string;
+  startDate?: string;
+  endDate?: string;
+  timeZone?: string;
+  groupBy?: string;
+  filters?: Record<string, string[]>;
+}): Promise<string> {
+  const now = Date.now();
+  const startDate = params.startDate
+    ? parseRelativeDate(params.startDate)
+    : now - 7 * 86400000;
+  const endDate = params.endDate ? parseRelativeDate(params.endDate) : now;
+
+  // Parse metric format "category.name"
+  const [category, name] = params.metric.includes(".")
+    ? params.metric.split(".", 2)
+    : ["metadata", params.metric];
+  const metricKey = `${category}.${name}`;
+  const aggregation = params.aggregation ?? "avg";
+
+  const result = await apiGetAnalytics({
+    series: [{ metric: metricKey, aggregation }],
+    startDate,
+    endDate,
+    timeZone: params.timeZone ?? "UTC",
+    groupBy: params.groupBy,
+    filters: params.filters,
+  });
+
+  const lines: string[] = [];
+  lines.push(`# Analytics: ${metricKey} (${aggregation})\n`);
+  lines.push(
+    `Period: ${new Date(startDate).toISOString().split("T")[0]} to ${new Date(endDate).toISOString().split("T")[0]}`
+  );
+  if (params.groupBy) lines.push(`Grouped by: ${params.groupBy}`);
+  lines.push("");
+
+  const currentPeriod = result.currentPeriod ?? [];
+  if (currentPeriod.length === 0) {
+    lines.push("No data available for this period.");
+  } 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(
+    "\n> Tip: Use `discover_schema` to see all available metrics and aggregation types."
+  );
+
+  return lines.join("\n");
+}

package/src/tools/get-prompt.ts

@@ -0,0 +1,56 @@
+import { getPrompt as apiGetPrompt } from "../langwatch-api.js";
+
+/**
+ * Handles the 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.
+ */
+export async function handleGetPrompt(params: {
+  idOrHandle: string;
+  version?: number;
+}): Promise<string> {
+  const prompt = await apiGetPrompt(params.idOrHandle, params.version);
+
+  const lines: string[] = [];
+  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.description) lines.push(`**Description**: ${prompt.description}`);
+  if (prompt.latestVersionNumber != null)
+    lines.push(`**Latest Version**: v${prompt.latestVersionNumber}`);
+
+  // Show model config
+  const version = prompt.versions?.[0] ?? prompt;
+  if (version.model) lines.push(`**Model**: ${version.model}`);
+  if (version.modelProvider)
+    lines.push(`**Provider**: ${version.modelProvider}`);
+
+  // Show messages
+  const messages = version.messages || prompt.prompt || [];
+  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);
+    }
+  }
+
+  // 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`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/tools/get-scenario.ts

@@ -0,0 +1,36 @@
+import { getScenario as apiGetScenario } from "../langwatch-api-scenarios.js";
+
+/**
+ * Handles the get_scenario MCP tool invocation.
+ *
+ * Retrieves a specific scenario by ID and formats it as
+ * AI-readable markdown or raw JSON.
+ */
+export async function handleGetScenario(params: {
+  scenarioId: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const scenario = await apiGetScenario(params.scenarioId);
+
+  if (params.format === "json") {
+    return JSON.stringify(scenario, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Scenario: ${scenario.name}\n`);
+  lines.push(`**ID**: ${scenario.id}`);
+  lines.push(`**Situation**: ${scenario.situation}`);
+
+  if (Array.isArray(scenario.criteria) && scenario.criteria.length > 0) {
+    lines.push("\n## Criteria");
+    for (const criterion of scenario.criteria) {
+      lines.push(`- ${criterion}`);
+    }
+  }
+
+  if (Array.isArray(scenario.labels) && scenario.labels.length > 0) {
+    lines.push(`\n**Labels**: ${scenario.labels.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}

package/src/tools/get-trace.ts

@@ -0,0 +1,61 @@
+import { getTraceById as apiGetTraceById } from "../langwatch-api.js";
+
+/**
+ * Handles the get_trace MCP tool invocation.
+ *
+ * Retrieves a single trace by ID. In digest mode (default), returns the
+ * AI-readable formatted digest. In json mode, returns the full raw JSON.
+ */
+export async function handleGetTrace(params: {
+  traceId: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const format = params.format ?? "digest";
+  const result = await apiGetTraceById(params.traceId, format);
+
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Trace: ${params.traceId}\n`);
+
+  if (result.timestamps) {
+    lines.push(`**Started**: ${result.timestamps.started_at}`);
+    if (result.timestamps.updated_at)
+      lines.push(`**Updated**: ${result.timestamps.updated_at}`);
+  }
+
+  if (result.metadata) {
+    const meta = result.metadata;
+    if (meta.user_id) lines.push(`**User**: ${meta.user_id}`);
+    if (meta.thread_id) lines.push(`**Thread**: ${meta.thread_id}`);
+    if (meta.customer_id) lines.push(`**Customer**: ${meta.customer_id}`);
+    if (meta.labels?.length) lines.push(`**Labels**: ${meta.labels.join(", ")}`);
+  }
+
+  if (result.evaluations && result.evaluations.length > 0) {
+    lines.push("\n## Evaluations");
+    for (const evaluation of result.evaluations) {
+      const status =
+        evaluation.passed === true
+          ? "PASSED"
+          : evaluation.passed === false
+            ? "FAILED"
+            : "N/A";
+      lines.push(
+        `- **${evaluation.name || evaluation.evaluator_id}**: ${status}${evaluation.score != null ? ` (score: ${evaluation.score})` : ""}${evaluation.label ? ` [${evaluation.label}]` : ""}`
+      );
+    }
+  }
+
+  if (result.formatted_trace) {
+    lines.push(`\n## Trace Details\n${result.formatted_trace}`);
+  }
+
+  lines.push(
+    '\n> Tip: Use `get_trace` with `format: "json"` to get the full raw trace data.'
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-prompts.ts

@@ -0,0 +1,35 @@
+import { listPrompts as apiListPrompts } from "../langwatch-api.js";
+
+/**
+ * Handles the list_prompts MCP tool invocation.
+ *
+ * Lists all prompts in the LangWatch project, formatted as an
+ * AI-readable markdown table.
+ */
+export async function handleListPrompts(): Promise<string> {
+  const prompts = await apiListPrompts();
+
+  if (!Array.isArray(prompts) || prompts.length === 0) {
+    return "No prompts found in this project.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Prompts (${prompts.length} total)\n`);
+  lines.push("| Handle | Name | Latest Version | Description |");
+  lines.push("|--------|------|----------------|-------------|");
+
+  for (const p of prompts) {
+    const handle = p.handle || p.id || "N/A";
+    const name = p.name || "Untitled";
+    const versionNum = p.latestVersionNumber ?? p.version;
+    const version = versionNum != null ? `v${versionNum}` : "N/A";
+    const desc = (p.description || "").slice(0, 60);
+    lines.push(`| ${handle} | ${name} | ${version} | ${desc} |`);
+  }
+
+  lines.push(
+    "\n> Use `get_prompt` with the handle or ID to see full prompt details."
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-scenarios.ts

@@ -0,0 +1,47 @@
+import { listScenarios as apiListScenarios } from "../langwatch-api-scenarios.js";
+
+/**
+ * Handles the list_scenarios MCP tool invocation.
+ *
+ * Lists all scenarios in the LangWatch project, formatted as an
+ * AI-readable digest or raw JSON.
+ */
+export async function handleListScenarios(params: {
+  format?: "digest" | "json";
+}): Promise<string> {
+  const scenarios = await apiListScenarios();
+
+  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 `create_scenario` to create your first scenario.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Scenarios (${scenarios.length} total)\n`);
+
+  for (const s of scenarios) {
+    lines.push(`## ${s.name}`);
+    lines.push(`**ID**: ${s.id}`);
+    const preview =
+      s.situation && s.situation.length > 60
+        ? s.situation.slice(0, 60) + "..."
+        : s.situation;
+    lines.push(`**Situation**: ${preview}`);
+    lines.push(
+      `**Criteria**: ${Array.isArray(s.criteria) ? s.criteria.length : 0} criteria`,
+    );
+    if (Array.isArray(s.labels) && s.labels.length > 0) {
+      lines.push(`**Labels**: ${s.labels.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `get_scenario` with the ID to see full scenario details.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/search-traces.ts

@@ -0,0 +1,91 @@
+import { searchTraces as apiSearchTraces } from "../langwatch-api.js";
+import { parseRelativeDate } from "../utils/date-parsing.js";
+
+/**
+ * Handles the search_traces MCP tool invocation.
+ *
+ * Searches LangWatch traces with optional filters, text query, and date range.
+ * In digest mode (default), returns AI-readable formatted digests per trace.
+ * In json mode, returns the full raw JSON.
+ */
+export async function handleSearchTraces(params: {
+  query?: string;
+  filters?: Record<string, string[]>;
+  startDate?: string;
+  endDate?: string;
+  pageSize?: number;
+  scrollId?: string;
+  format?: "digest" | "json";
+}): Promise<string> {
+  const now = Date.now();
+  const startDate = params.startDate
+    ? parseRelativeDate(params.startDate)
+    : now - 86400000;
+  const endDate = params.endDate ? parseRelativeDate(params.endDate) : now;
+  const format = params.format ?? "digest";
+
+  const result = await apiSearchTraces({
+    query: params.query,
+    filters: params.filters,
+    startDate,
+    endDate,
+    pageSize: params.pageSize ?? 25,
+    scrollId: params.scrollId,
+    format,
+  });
+
+  const traces = result.traces ?? [];
+  if (traces.length === 0) {
+    return "No traces found matching your query.";
+  }
+
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    `Found ${result.pagination?.totalHits ?? traces.length} traces:\n`
+  );
+
+  for (const trace of traces) {
+    lines.push(`### Trace: ${trace.trace_id}`);
+
+    if (trace.formatted_trace) {
+      lines.push(trace.formatted_trace);
+    } else {
+      const inputStr = trace.input?.value
+        ? String(trace.input.value)
+        : "N/A";
+      const outputStr = trace.output?.value
+        ? String(trace.output.value)
+        : "N/A";
+      lines.push(
+        `- **Input**: ${inputStr.slice(0, 100)}${inputStr.length > 100 ? "..." : ""}`
+      );
+      lines.push(
+        `- **Output**: ${outputStr.slice(0, 100)}${outputStr.length > 100 ? "..." : ""}`
+      );
+    }
+
+    if (trace.timestamps) {
+      lines.push(`- **Time**: ${trace.timestamps.started_at || "N/A"}`);
+    }
+    if (trace.error) {
+      lines.push(`- **Error**: ${JSON.stringify(trace.error)}`);
+    }
+    lines.push("");
+  }
+
+  if (result.pagination?.scrollId) {
+    lines.push(
+      `\n**More results available.** Use scrollId: "${result.pagination.scrollId}" to get next page.`
+    );
+  }
+
+  lines.push(
+    '\n> Tip: Use `get_trace` with a trace_id for full details. Use `search_traces` with `format: "json"` for raw data. Use `discover_schema` to see available filter fields.'
+  );
+
+  return lines.join("\n");
+}

package/src/tools/update-prompt.ts

@@ -0,0 +1,44 @@
+import {
+  updatePrompt as apiUpdatePrompt,
+  createPromptVersion as apiCreateVersion,
+} from "../langwatch-api.js";
+import type { PromptMutationResponse } from "../langwatch-api.js";
+
+/**
+ * Handles the update_prompt MCP tool invocation.
+ *
+ * Updates an existing prompt or creates a new version, depending on the
+ * `createVersion` flag. Returns a confirmation with the updated details.
+ */
+export async function handleUpdatePrompt(params: {
+  idOrHandle: string;
+  messages?: Array<{ role: string; content: string }>;
+  model?: string;
+  modelProvider?: string;
+  commitMessage?: string;
+  createVersion?: boolean;
+}): Promise<string> {
+  const { idOrHandle, createVersion, ...data } = params;
+
+  let result: PromptMutationResponse;
+  if (createVersion) {
+    result = await apiCreateVersion(idOrHandle, data);
+  } else {
+    result = await apiUpdatePrompt(idOrHandle, data);
+  }
+
+  const lines: string[] = [];
+  lines.push(
+    createVersion
+      ? "New version created successfully!\n"
+      : "Prompt updated successfully!\n"
+  );
+  if (result.id) lines.push(`**ID**: ${result.id}`);
+  if (result.handle) lines.push(`**Handle**: ${result.handle}`);
+  if (result.latestVersionNumber != null)
+    lines.push(`**Version**: v${result.latestVersionNumber}`);
+  if (params.commitMessage)
+    lines.push(`**Commit**: ${params.commitMessage}`);
+
+  return lines.join("\n");
+}

package/src/tools/update-scenario.ts

@@ -0,0 +1,32 @@
+import { updateScenario as apiUpdateScenario } from "../langwatch-api-scenarios.js";
+
+/**
+ * Handles the update_scenario MCP tool invocation.
+ *
+ * Updates an existing scenario and returns a confirmation
+ * with the updated details.
+ */
+export async function handleUpdateScenario(params: {
+  scenarioId: string;
+  name?: string;
+  situation?: string;
+  criteria?: string[];
+  labels?: string[];
+}): Promise<string> {
+  const { scenarioId, ...data } = params;
+  const result = await apiUpdateScenario({ id: scenarioId, ...data });
+
+  const lines: string[] = [];
+  lines.push("Scenario updated successfully!\n");
+  lines.push(`**ID**: ${result.id}`);
+  lines.push(`**Name**: ${result.name}`);
+  if (result.situation) lines.push(`**Situation**: ${result.situation}`);
+  if (Array.isArray(result.criteria) && result.criteria.length > 0) {
+    lines.push(`**Criteria**: ${result.criteria.length} criteria`);
+  }
+  if (Array.isArray(result.labels) && result.labels.length > 0) {
+    lines.push(`**Labels**: ${result.labels.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}