@langwatch/mcp-server 2.1.0 → 3.0.0

package/src/tools/create-analytics-report.ts

@@ -0,0 +1,7 @@
+import { createAnalyticsReport } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleCreateAnalyticsReport(params: { name: string }): Promise<string> {
+  const report = await createAnalyticsReport({ name: params.name });
+
+  return `Analytics Report created successfully!\n\n**Name**: ${report.name}\n**ID**: ${report.id}`;
+}

package/src/tools/create-annotation.ts

@@ -1,4 +1,4 @@
-import { createAnnotation as apiCreateAnnotation } from "../langwatch-api-annotations.js";
+import { createAnnotation as apiCreateAnnotation } from "../langwatch-api-annotations.ts";
 
 export async function handleCreateAnnotation(params: {
   traceId: string;
@@ -12,7 +12,12 @@ export async function handleCreateAnnotation(params: {
     email: params.email,
   });
 
-  const rating = params.isThumbsUp === true ? " 👍" : params.isThumbsUp === false ? " 👎" : "";
+  let rating = "";
+  if (params.isThumbsUp === true) {
+    rating = " 👍";
+  } else if (params.isThumbsUp === false) {
+    rating = " 👎";
+  }
 
   return `Annotation created successfully!${rating}\n\n**ID**: ${annotation.id ?? "—"}\n**Trace ID**: ${params.traceId}${params.comment ? `\n**Comment**: ${params.comment}` : ""}`;
 }

package/src/tools/create-api-key.ts

@@ -1,15 +1,15 @@
-import { createApiKey as apiCreateApiKey } from "../langwatch-api-api-keys.js";
+import { createApiKey as apiCreateApiKey } from "../langwatch-api-api-keys.ts";
 
 export async function handleCreateApiKey(params: {
   keyType: "personal" | "service";
   name: string;
   description?: string;
   expiresAt?: string;
-  bindings?: Array<{
+  bindings?: {
     role: "ADMIN" | "MEMBER" | "VIEWER";
     scopeType: "ORGANIZATION" | "TEAM" | "PROJECT";
     scopeId: string;
-  }>;
+  }[];
   projectIds?: string[];
 }): Promise<string> {
   const result = await apiCreateApiKey(params);
@@ -21,9 +21,7 @@ export async function handleCreateApiKey(params: {
   lines.push(`**Token**: \`${result.token}\``);
   lines.push(`**Created**: ${result.apiKey.createdAt}`);
   lines.push("");
-  lines.push(
-    "> ⚠️ Save this token now — it will not be shown again.",
-  );
+  lines.push("> ⚠️ Save this token now — it will not be shown again.");
 
   return lines.join("\n");
 }

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

@@ -1,10 +1,8 @@
-import { createDatasetRecords as apiCreateDatasetRecords } from "../langwatch-api-datasets.js";
+import { createDatasetRecords as apiCreateDatasetRecords } from "../langwatch-api-datasets.ts";
 
 /**
- * Handles the platform_create_dataset_records MCP tool invocation.
- *
- * Creates records in a dataset in batch and returns a confirmation
- * with the count of records created.
+ * Handles the platform_create_dataset_records MCP tool: creates records
+ * in batch and returns a confirmation with the count created.
  */
 export async function handleCreateDatasetRecords(params: {
   slugOrId: string;
@@ -15,9 +13,7 @@ export async function handleCreateDatasetRecords(params: {
 
   const lines: string[] = [];
   lines.push(`${count} record(s) created successfully!\n`);
-  lines.push(
-    "> Use `platform_get_dataset` to see the updated dataset with all records.",
-  );
+  lines.push("> Use `platform_get_dataset` to see the updated dataset with all records.");
 
   return lines.join("\n");
 }

package/src/tools/create-dataset.ts

@@ -1,12 +1,10 @@
-import { createDataset as apiCreateDataset } from "../langwatch-api-datasets.js";
-import type { DatasetColumnType } from "../langwatch-api-datasets.js";
-import { formatDatasetMutationDetails } from "./format-dataset-mutation.js";
+import { createDataset as apiCreateDataset } from "../langwatch-api-datasets.ts";
+import type { DatasetColumnType } from "../langwatch-api-datasets.ts";
+import { formatDatasetMutationDetails } from "./format-dataset-mutation.ts";
 
 /**
- * Handles the platform_create_dataset MCP tool invocation.
- *
- * Creates a new dataset in the LangWatch project and returns a
- * confirmation with the created dataset's details.
+ * Handles the platform_create_dataset MCP tool: creates a dataset and
+ * returns a confirmation with its details.
  */
 export async function handleCreateDataset(params: {
   name: string;

package/src/tools/create-evaluator.ts

@@ -1,13 +1,11 @@
 import {
   createEvaluator as apiCreateEvaluator,
   getEvaluatorType,
-} from "../langwatch-api-evaluators.js";
+} from "../langwatch-api-evaluators.ts";
 
 /**
- * Handles the platform_create_evaluator MCP tool invocation.
- *
- * Creates a new evaluator in the LangWatch project and returns a
- * confirmation with the created evaluator's details.
+ * Handles the platform_create_evaluator MCP tool: creates an evaluator
+ * and returns a confirmation with its details.
  */
 export async function handleCreateEvaluator(params: {
   name: string;

package/src/tools/create-project.ts

@@ -1,4 +1,4 @@
-import { createProject as apiCreateProject } from "../langwatch-api-projects.js";
+import { createProject as apiCreateProject } from "../langwatch-api-projects.ts";
 
 export async function handleCreateProject(params: {
   name: string;
@@ -38,7 +38,7 @@ export async function handleCreateProject(params: {
   lines.push("");
   lines.push(
     "> ⚠️ Save the service API key now — it will not be shown again. " +
-    "Use it as `LANGWATCH_API_KEY` to authenticate project-scoped operations.",
+      "Use it as `LANGWATCH_API_KEY` to authenticate project-scoped operations.",
   );
 
   return lines.join("\n");

package/src/tools/create-prompt-tag.ts

@@ -1,8 +1,6 @@
-import { createPromptTag as apiCreatePromptTag } from "../langwatch-api.js";
+import { createPromptTag as apiCreatePromptTag } from "../langwatch-api.ts";
 
-export async function handleCreatePromptTag(params: {
-  name: string;
-}): Promise<string> {
+export async function handleCreatePromptTag(params: { name: string }): Promise<string> {
   await apiCreatePromptTag(params.name);
 
   const lines: string[] = [];

package/src/tools/create-prompt.ts

@@ -1,13 +1,11 @@
-import { createPrompt as apiCreatePrompt } from "../langwatch-api.js";
+import { createPrompt as apiCreatePrompt } from "../langwatch-api.ts";
 
 const HANDLE_PATTERN = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$/;
 
 /**
- * Converts a human-readable name into a URL-friendly handle.
- *
- * Lowercases the input, replaces non-alphanumeric runs with hyphens,
- * and strips leading/trailing hyphens. May return an empty string
- * for inputs with no alphanumeric characters — callers must validate.
+ * Converts a human-readable name into a URL-friendly handle: lowercased,
+ * non-alphanumeric runs replaced with hyphens, leading/trailing hyphens
+ * stripped. May return empty — callers must validate.
  */
 function toHandle(name: string): string {
   return name
@@ -16,23 +14,18 @@ function toHandle(name: string): string {
     .replace(/^-|-$/g, "");
 }
 
-/**
- * Handles the platform_create_prompt MCP tool invocation.
- *
- * Creates a new prompt in the LangWatch project and returns a
- * confirmation with the created prompt's details.
- */
+/** Handles the platform_create_prompt MCP tool: creates a prompt and returns its details. */
 export async function handleCreatePrompt(params: {
   name: string;
   handle?: string;
-  messages: Array<{ role: string; content: string }>;
+  messages: { role: string; content: string }[];
   model: string;
   tags?: string[];
 }): Promise<string> {
   const handle = params.handle?.trim() || toHandle(params.name);
   if (!handle || !HANDLE_PATTERN.test(handle)) {
     throw new Error(
-      `Invalid prompt handle "${handle || ""}". Handle must match ${HANDLE_PATTERN}. Provide a valid \`handle\` explicitly.`
+      `Invalid prompt handle "${handle || ""}". Handle must match ${HANDLE_PATTERN}. Provide a valid \`handle\` explicitly.`,
     );
   }
 
@@ -49,10 +42,8 @@ export async function handleCreatePrompt(params: {
   if (result.handle) lines.push(`**Handle**: ${result.handle}`);
   lines.push(`**Name**: ${result.name || params.name}`);
   lines.push(`**Model**: ${params.model}`);
-  if (result.latestVersionNumber != null)
-    lines.push(`**Version**: v${result.latestVersionNumber}`);
-  if (params.tags && params.tags.length > 0)
-    lines.push(`**Tags**: ${params.tags.join(", ")}`);
+  if (result.latestVersionNumber != null) lines.push(`**Version**: v${result.latestVersionNumber}`);
+  if (params.tags && params.tags.length > 0) lines.push(`**Tags**: ${params.tags.join(", ")}`);
 
   return lines.join("\n");
 }

package/src/tools/create-scenario.ts

@@ -1,12 +1,10 @@
-import { createScenario as apiCreateScenario } from "../langwatch-api-scenarios.js";
-import type { ScenarioFieldValues } from "../schemas/suite-fields.js";
-import { formatScenarioFields } from "./format-scenario.js";
+import { createScenario as apiCreateScenario } from "../langwatch-api-scenarios.ts";
+import type { ScenarioFieldValues } from "../schemas/suite-fields.ts";
+import { formatScenarioFields } from "./format-scenario.ts";
 
 /**
- * Handles the platform_create_scenario MCP tool invocation.
- *
- * Creates a new scenario in the LangWatch project and returns a
- * confirmation with the created scenario's details.
+ * Handles the platform_create_scenario MCP tool: creates a scenario and
+ * returns a confirmation with its details.
  */
 export async function handleCreateScenario(params: {
   name: string;

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

@@ -1,13 +1,10 @@
-import { createTestSuite as apiCreateTestSuite } from "../langwatch-api-test-suites.js";
+import { createTestSuite as apiCreateTestSuite } from "../langwatch-api-test-suites.ts";
 import {
   type EvaluatorAttachmentInput,
   type SuiteField,
   toWireAttachments,
-} from "../schemas/suite-fields.js";
-import {
-  formatEvaluatorAttachments,
-  formatSuiteFields,
-} from "./format-suite-details.js";
+} from "../schemas/suite-fields.ts";
+import { formatEvaluatorAttachments, formatSuiteFields } from "./format-suite-details.ts";
 
 /**
  * Handles the platform_create_test_suite MCP tool invocation.
@@ -35,9 +32,7 @@ export async function handleCreateTestSuite(params: {
     ...formatEvaluatorAttachments(suite.evaluators),
     "",
     `> File scenarios in it with \`platform_create_scenario\` or \`platform_update_scenario\`, passing testSuiteId \`${suite.id}\`${
-      suite.fields && suite.fields.length > 0
-        ? ` and a value per field under \`fields\``
-        : ""
+      suite.fields && suite.fields.length > 0 ? ` and a value per field under \`fields\`` : ""
     }.`,
   ].join("\n");
 }

package/src/tools/create-trigger.ts

@@ -0,0 +1,55 @@
+import {
+  createTrigger as apiCreateTrigger,
+  type CreateTriggerInput,
+} from "../langwatch-api-triggers.ts";
+import { validateActionParamsForAction } from "../schemas/triggers.ts";
+
+/** An MCP tool result; `isError` tells the client the call was refused. */
+export type TriggerToolResult = {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+};
+
+/** A refusal the client must read as a failed call, not a success. */
+export function toolError(message: string): TriggerToolResult {
+  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+
+/**
+ * Handles the platform_create_trigger MCP tool invocation. `actionParams` is
+ * optional, as it was before it was stated per channel: omitted sends `{}` and
+ * the server decides; stated, it is checked against the channel first.
+ */
+export async function handleCreateTrigger(
+  params: Omit<CreateTriggerInput, "filters"> & { filters?: string },
+): Promise<TriggerToolResult> {
+  if (params.actionParams !== undefined) {
+    const verdict = validateActionParamsForAction({
+      action: params.action,
+      actionParams: params.actionParams,
+    });
+    if (!verdict.ok) return toolError(verdict.message);
+  }
+  let filters: Record<string, unknown> | undefined;
+  if (params.filters) {
+    const parsed = parseJsonObject(params.filters);
+    if (!parsed) return toolError("filters must be a JSON object");
+    filters = parsed;
+  }
+  const trigger = await apiCreateTrigger({ ...params, filters });
+  const text = `Trigger "${trigger.name}" created (ID: ${trigger.id}, Kind: ${trigger.kind ?? "AUTOMATION"}, Action: ${trigger.action}).`;
+  return { content: [{ type: "text", text }] };
+}
+
+/** A flag value that must be a JSON object; undefined for anything else. */
+export function parseJsonObject(raw: string): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return Object.fromEntries(Object.entries(parsed));
+  } catch {
+    return undefined;
+  }
+}

package/src/tools/dashboard-widget-queries.ts

@@ -0,0 +1,45 @@
+import type { DashboardWidgetQueryInput } from "../langwatch-api-dashboard-widgets.js";
+import type { WidgetSource } from "../schemas/widget-sources.js";
+
+/** Every query with `sources` set to the list given; as given when no list was named. */
+export function withSources({
+  queries,
+  sources,
+}: {
+  queries: readonly DashboardWidgetQueryInput[];
+  sources: WidgetSource[] | null | undefined;
+}): DashboardWidgetQueryInput[] {
+  if (sources === undefined) return [...queries];
+  return queries.map((query) => ({ ...query, sources }));
+}
+
+/** A widget file rarely needs more than a couple of named queries (server bound). */
+export const MAX_DASHBOARD_WIDGET_QUERIES = 8;
+
+/** The `{ name: sql }` shorthand or the array form the REST endpoint takes. */
+export type DashboardWidgetQueriesInput = DashboardWidgetQueryInput[] | Record<string, string>;
+
+/**
+ * Turns the `{ name: sql }` shorthand into the array shape the REST endpoint validates,
+ * refusing an empty or oversized set before any request is made.
+ */
+export function normalizeDashboardWidgetQueries({
+  queries,
+}: {
+  queries: DashboardWidgetQueriesInput;
+}): DashboardWidgetQueryInput[] {
+  const normalized = Array.isArray(queries)
+    ? queries
+    : Object.entries(queries).map(([name, sql]) => ({ name, sql }));
+  if (normalized.length === 0) {
+    throw new Error(
+      "Provide at least one named LWQL query in `queries`. Validate each query's SQL first with run_query.",
+    );
+  }
+  if (normalized.length > MAX_DASHBOARD_WIDGET_QUERIES) {
+    throw new Error(
+      `A widget may declare at most ${MAX_DASHBOARD_WIDGET_QUERIES} queries, got ${normalized.length}.`,
+    );
+  }
+  return normalized;
+}

package/src/tools/dashboards.ts

@@ -0,0 +1,104 @@
+/**
+ * The dashboard tools over `/api/v1/dashboards`: read, create, rename and delete a dashboard,
+ * list a dashboard's widgets and delete one. Spec: modules/dashboard/specs/dashboards-v2.feature
+ * AC199s.
+ */
+
+import {
+  type Dashboard,
+  createDashboard,
+  deleteDashboard,
+  deleteWidgetOnDashboard,
+  getDashboard,
+  listWidgetsOnDashboard,
+  updateDashboard,
+} from "../langwatch-api-dashboards.js";
+
+function describeDashboard(dashboard: Dashboard): string[] {
+  return [
+    `**Name**: ${dashboard.name}`,
+    `**ID**: ${dashboard.id}`,
+    `**Scope**: ${dashboard.scope}`,
+    ...(dashboard.description ? [`**Description**: ${dashboard.description}`] : []),
+    `**URL**: ${dashboard.platformUrl}`,
+  ];
+}
+
+/** Reads only `/api/v1/dashboards`; an Analytics Report's id is not found there. */
+export async function handleGetDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const dashboard = await getDashboard({ dashboardId });
+  return [`# ${dashboard.name}\n`, ...describeDashboard(dashboard)].join("\n");
+}
+
+export async function handleCreateDashboard({ name }: { name: string }): Promise<string> {
+  const dashboard = await createDashboard({ name });
+  return [
+    "Dashboard created.\n",
+    ...describeDashboard(dashboard),
+    "",
+    "> Pass the ID to `add_dashboard_widget` to add a widget to it.",
+  ].join("\n");
+}
+
+export async function handleRenameDashboard({
+  dashboardId,
+  name,
+  description,
+}: {
+  dashboardId: string;
+  name?: string;
+  description?: string;
+}): Promise<string> {
+  if (name === undefined && description === undefined) {
+    throw new Error("Provide at least one of name or description to change.");
+  }
+  const dashboard = await updateDashboard({
+    dashboardId,
+    ...(name === undefined ? {} : { name }),
+    ...(description === undefined ? {} : { description }),
+  });
+  return ["Dashboard updated.\n", ...describeDashboard(dashboard)].join("\n");
+}
+
+export async function handleDeleteDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const deleted = await deleteDashboard({ dashboardId });
+  return `Dashboard "${deleted.name}" deleted with its widgets (ID: ${deleted.id}).`;
+}
+
+export async function handleListDashboardWidgets({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const { data: widgets } = await listWidgetsOnDashboard({ dashboardId });
+  if (widgets.length === 0) return `Dashboard "${dashboardId}" has no widgets.`;
+
+  return [
+    `# Widgets on dashboard ${dashboardId} (${widgets.length} total)\n`,
+    ...widgets.flatMap((widget) => [
+      `## ${widget.name}`,
+      `**ID**: ${widget.id}`,
+      `**Queries**: ${widget.definition.queries.map((query) => query.name).join(", ") || "(none)"}`,
+      "",
+    ]),
+  ].join("\n");
+}
+
+export async function handleDeleteDashboardWidget({
+  dashboardId,
+  widgetId,
+}: {
+  dashboardId: string;
+  widgetId: string;
+}): Promise<string> {
+  await deleteWidgetOnDashboard({ dashboardId, widgetId });
+  return `Widget "${widgetId}" deleted from dashboard "${dashboardId}".`;
+}

package/src/tools/delete-agent.ts

@@ -1,4 +1,4 @@
-import { deleteAgent as apiDeleteAgent } from "../langwatch-api-agents.js";
+import { deleteAgent as apiDeleteAgent } from "../langwatch-api-agents.ts";
 
 export async function handleDeleteAgent(params: { id: string }): Promise<string> {
   const result = await apiDeleteAgent(params.id);

package/src/tools/delete-analytics-report.ts

@@ -0,0 +1,7 @@
+import { deleteAnalyticsReport } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleDeleteAnalyticsReport(params: { reportId: string }): Promise<string> {
+  const result = await deleteAnalyticsReport({ reportId: params.reportId });
+
+  return `Analytics Report deleted successfully!\n\n**Name**: ${result.name}\n**ID**: ${result.id}`;
+}

package/src/tools/delete-annotation.ts

@@ -1,4 +1,4 @@
-import { deleteAnnotation as apiDeleteAnnotation } from "../langwatch-api-annotations.js";
+import { deleteAnnotation as apiDeleteAnnotation } from "../langwatch-api-annotations.ts";
 
 export async function handleDeleteAnnotation(params: { id: string }): Promise<string> {
   await apiDeleteAnnotation(params.id);

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

@@ -1,10 +1,8 @@
-import { deleteDatasetRecords as apiDeleteDatasetRecords } from "../langwatch-api-datasets.js";
+import { deleteDatasetRecords as apiDeleteDatasetRecords } from "../langwatch-api-datasets.ts";
 
 /**
- * Handles the platform_delete_dataset_records MCP tool invocation.
- *
- * Deletes records from a dataset by IDs and returns confirmation
- * with the count of records deleted.
+ * Handles the platform_delete_dataset_records MCP tool: deletes records
+ * by ID and returns a confirmation with the count deleted.
  */
 export async function handleDeleteDatasetRecords(params: {
   slugOrId: string;
@@ -14,9 +12,7 @@ export async function handleDeleteDatasetRecords(params: {
 
   const lines: string[] = [];
   lines.push(`${result.deletedCount} record(s) deleted successfully!\n`);
-  lines.push(
-    "> Use `platform_get_dataset` to see the updated dataset.",
-  );
+  lines.push("> Use `platform_get_dataset` to see the updated dataset.");
 
   return lines.join("\n");
 }

package/src/tools/delete-dataset.ts

@@ -1,20 +1,16 @@
-import { deleteDataset as apiDeleteDataset } from "../langwatch-api-datasets.js";
+import { deleteDataset as apiDeleteDataset } from "../langwatch-api-datasets.ts";
 
 /**
  * Handles the platform_delete_dataset MCP tool invocation.
  *
  * Archives (soft-deletes) a dataset and returns confirmation.
  */
-export async function handleDeleteDataset(params: {
-  slugOrId: string;
-}): Promise<string> {
+export async function handleDeleteDataset(params: { slugOrId: string }): Promise<string> {
   await apiDeleteDataset(params.slugOrId);
 
   const lines: string[] = [];
   lines.push("Dataset deleted successfully!\n");
-  lines.push(
-    "> The dataset has been archived and will no longer appear in listings.",
-  );
+  lines.push("> The dataset has been archived and will no longer appear in listings.");
 
   return lines.join("\n");
 }

package/src/tools/delete-evaluator.ts

@@ -1,12 +1,10 @@
-import { deleteEvaluator as apiDeleteEvaluator } from "../langwatch-api-evaluators.js";
+import { deleteEvaluator as apiDeleteEvaluator } from "../langwatch-api-evaluators.ts";
 
 /**
  * Handles the platform_delete_evaluator MCP tool invocation.
  */
-export async function handleDeleteEvaluator(params: {
-  idOrSlug: string;
-}): Promise<string> {
-  const result = await apiDeleteEvaluator(params.idOrSlug);
+export async function handleDeleteEvaluator(params: { idOrSlug: string }): Promise<string> {
+  await apiDeleteEvaluator(params.idOrSlug);
 
-  return `Evaluator ${result.id} has been archived (soft-deleted).`;
+  return `Evaluator ${params.idOrSlug} has been archived (soft-deleted).`;
 }

package/src/tools/delete-prompt-tag.ts

@@ -1,8 +1,6 @@
-import { deletePromptTag as apiDeletePromptTag } from "../langwatch-api.js";
+import { deletePromptTag as apiDeletePromptTag } from "../langwatch-api.ts";
 
-export async function handleDeletePromptTag(params: {
-  tag: string;
-}): Promise<string> {
+export async function handleDeletePromptTag(params: { tag: string }): Promise<string> {
   await apiDeletePromptTag(params.tag);
 
   const lines: string[] = [];

package/src/tools/delete-workflow.ts

@@ -1,4 +1,4 @@
-import { deleteWorkflow as apiDeleteWorkflow } from "../langwatch-api-workflows.js";
+import { deleteWorkflow as apiDeleteWorkflow } from "../langwatch-api-workflows.ts";
 
 export async function handleDeleteWorkflow(params: { id: string }): Promise<string> {
   const result = await apiDeleteWorkflow(params.id);

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

@@ -1,12 +1,12 @@
-import { AVAILABLE_EVALUATORS } from "../../../../services/langevals/ts-integration/evaluators.generated.js";
-import type { EvaluatorDefinition, EvaluatorTypes } from "../../../../services/langevals/ts-integration/evaluators.generated.js";
+import {
+  AVAILABLE_EVALUATORS,
+  type EvaluatorDefinition,
+  type EvaluatorTypes,
+} from "@langwatch/evaluator-contract";
 
 /**
- * Formats evaluator schema information for the discover_schema tool.
- *
- * Two levels of detail:
- * - Overview (no evaluatorType): compact list of all evaluator types
- * - Detail (with evaluatorType): full schema for one evaluator type
+ * Formats evaluator schema for discover_schema: an overview (all types,
+ * compact) when no evaluatorType is given, else the full schema for one.
  */
 export function formatEvaluatorSchema(evaluatorType?: string): string {
   if (evaluatorType) {
@@ -50,9 +50,22 @@ function formatEvaluatorOverview(): string {
   return lines.join("\n");
 }
 
+function settingsSection(settingsEntries: [string, unknown][]): string[] {
+  if (settingsEntries.length === 0) return [];
+  const lines = ["\n## Settings\n"];
+  for (const [key, setting] of settingsEntries) {
+    const s = setting as { description?: string; default: unknown };
+    const defaultStr = JSON.stringify(s.default);
+    const desc = s.description ? ` - ${s.description}` : "";
+    lines.push(`- **${key}**${desc}`);
+    lines.push(`  Default: \`${defaultStr}\``);
+  }
+  return lines;
+}
+
 /**
- * Returns the full schema for a specific evaluator type.
- * Includes settings with descriptions and defaults, required/optional fields, env vars, and result fields.
+ * Returns the full schema for a specific evaluator type: settings, required/optional
+ * fields, env vars, and result fields.
  */
 function formatEvaluatorDetail(evaluatorType: string): string {
   const def = AVAILABLE_EVALUATORS[evaluatorType as EvaluatorTypes] as
@@ -85,18 +98,8 @@ function formatEvaluatorDetail(evaluatorType: string): string {
     lines.push(`**Optional**: ${def.optionalFields.join(", ")}`);
   }
 
-  // Settings
   const settingsEntries = Object.entries(def.settings);
-  if (settingsEntries.length > 0) {
-    lines.push("\n## Settings\n");
-    for (const [key, setting] of settingsEntries) {
-      const s = setting as { description?: string; default: unknown };
-      const defaultStr = JSON.stringify(s.default);
-      const desc = s.description ? ` - ${s.description}` : "";
-      lines.push(`- **${key}**${desc}`);
-      lines.push(`  Default: \`${defaultStr}\``);
-    }
-  }
+  lines.push(...settingsSection(settingsEntries));
 
   // Env vars
   if (def.envVars.length > 0) {
@@ -118,12 +121,18 @@ function formatEvaluatorDetail(evaluatorType: string): string {
 
   lines.push("\n## Usage Example\n");
   lines.push("```json");
-  lines.push(JSON.stringify({
-    evaluatorType: evaluatorType,
-    settings: Object.fromEntries(
-      settingsEntries.map(([key, setting]) => [key, (setting as { default: unknown }).default]),
+  lines.push(
+    JSON.stringify(
+      {
+        evaluatorType: evaluatorType,
+        settings: Object.fromEntries(
+          settingsEntries.map(([key, setting]) => [key, (setting as { default: unknown }).default]),
+        ),
+      },
+      null,
+      2,
     ),
-  }, null, 2));
+  );
   lines.push("```");
 
   return lines.join("\n");