@langwatch/mcp-server 2.0.0 → 2.2.0

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

@@ -1,11 +1,15 @@
-import { assignPromptTag as apiAssignPromptTag } from "../langwatch-api.js";
+import { assignPromptTag as apiAssignPromptTag } from "../langwatch-api.ts";
 
 export async function handleAssignPromptTag(params: {
   idOrHandle: string;
   tag: string;
   versionId: string;
 }): Promise<string> {
-  await apiAssignPromptTag({ idOrHandle: params.idOrHandle, tag: params.tag, versionId: params.versionId });
+  await apiAssignPromptTag({
+    idOrHandle: params.idOrHandle,
+    tag: params.tag,
+    versionId: params.versionId,
+  });
 
   const lines: string[] = [];
   lines.push("Tag assigned successfully!\n");

package/src/tools/create-agent.ts

@@ -1,4 +1,4 @@
-import { createAgent as apiCreateAgent } from "../langwatch-api-agents.js";
+import { createAgent as apiCreateAgent } from "../langwatch-api-agents.ts";
 
 export async function handleCreateAgent(params: {
   name: string;

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-dashboard.ts

@@ -1,4 +1,4 @@
-import { createDashboard as apiCreateDashboard } from "../langwatch-api-dashboards.js";
+import { createDashboard as apiCreateDashboard } from "../langwatch-api-dashboards.ts";
 
 export async function handleCreateDashboard(params: { name: string }): Promise<string> {
   const dashboard = await apiCreateDashboard({ name: params.name });

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,16 +1,18 @@
-import { createScenario as apiCreateScenario } from "../langwatch-api-scenarios.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;
   situation: string;
   criteria?: string[];
   labels?: string[];
+  testSuiteId?: string | null;
+  fields?: ScenarioFieldValues;
 }): Promise<string> {
   const result = await apiCreateScenario(params);
 
@@ -25,6 +27,10 @@ export async function handleCreateScenario(params: {
   if (Array.isArray(result.labels) && result.labels.length > 0) {
     lines.push(`**Labels**: ${result.labels.join(", ")}`);
   }
+  if (result.testSuiteId) {
+    lines.push(`**Test suite**: ${result.testSuiteId}`);
+  }
+  lines.push(...formatScenarioFields(result.fields));
 
   return lines.join("\n");
 }

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

@@ -0,0 +1,38 @@
+import { createTestSuite as apiCreateTestSuite } from "../langwatch-api-test-suites.ts";
+import {
+  type EvaluatorAttachmentInput,
+  type SuiteField,
+  toWireAttachments,
+} from "../schemas/suite-fields.ts";
+import { formatEvaluatorAttachments, formatSuiteFields } from "./format-suite-details.ts";
+
+/**
+ * Handles the platform_create_test_suite MCP tool invocation.
+ */
+export async function handleCreateTestSuite(params: {
+  name: string;
+  fields?: SuiteField[];
+  evaluators?: EvaluatorAttachmentInput[];
+}): Promise<string> {
+  const suite = await apiCreateTestSuite({
+    name: params.name,
+    ...(params.fields !== undefined ? { fields: params.fields } : {}),
+    ...(params.evaluators !== undefined
+      ? { evaluators: toWireAttachments(params.evaluators) }
+      : {}),
+  });
+
+  return [
+    `Test suite "${suite.name}" created.`,
+    "",
+    `**ID**: ${suite.id}`,
+    `**Slug**: ${suite.slug}`,
+    `**View**: ${suite.platformUrl}`,
+    ...formatSuiteFields(suite.fields),
+    ...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\`` : ""
+    }.`,
+  ].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-exists.ts

@@ -0,0 +1,25 @@
+import { getBoard } from "../langwatch-api-boards.js";
+import { LangWatchApiError } from "../langwatch-api.js";
+
+/**
+ * Refuses a dashboard id that names no Dashboards board in this project, naming the id, so an
+ * agent's typo, or the id of an Analytics Reports board, fails before any widget is written.
+ */
+export async function assertDashboardExists({
+  projectId,
+  dashboardId,
+}: {
+  projectId: string;
+  dashboardId: string;
+}): Promise<void> {
+  try {
+    await getBoard({ projectId, boardId: dashboardId });
+  } catch (error) {
+    if (error instanceof LangWatchApiError && error.status === 404) {
+      throw new Error(
+        `No dashboard with ID "${dashboardId}" was found in this project. Use list_dashboard_boards to find a valid dashboard ID.`,
+      );
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,32 @@
+import type { DashboardWidgetQueryInput } from "../langwatch-api-dashboard-widgets.js";
+
+/** 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/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-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-dashboard.ts

@@ -1,4 +1,4 @@
-import { deleteDashboard as apiDeleteDashboard } from "../langwatch-api-dashboards.js";
+import { deleteDashboard as apiDeleteDashboard } from "../langwatch-api-dashboards.ts";
 
 export async function handleDeleteDashboard(params: { id: string }): Promise<string> {
   const result = await apiDeleteDashboard(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");