@lightsage/mcp 0.3.1 → 0.4.1

package/src/models/createv2evalrequest.ts

@@ -5,31 +5,18 @@
 
 import * as z from "zod";
 import {
-  V2InlineCliReference,
-  V2InlineCliReference$zodSchema,
-} from "./v2inlineclireference.js";
+  SearchGroundingMode,
+  SearchGroundingMode$zodSchema,
+} from "./searchgroundingmode.js";
 import {
   V2InlineMcpDefinition,
   V2InlineMcpDefinition$zodSchema,
 } from "./v2inlinemcpdefinition.js";
-import {
-  V2SavedCliReference,
-  V2SavedCliReference$zodSchema,
-} from "./v2savedclireference.js";
 import {
   V2SavedMcpReference,
   V2SavedMcpReference$zodSchema,
 } from "./v2savedmcpreference.js";
 
-export type CreateV2EvalRequestCli = V2SavedCliReference | V2InlineCliReference;
-
-export const CreateV2EvalRequestCli$zodSchema: z.ZodType<
-  CreateV2EvalRequestCli
-> = z.union([
-  V2SavedCliReference$zodSchema,
-  V2InlineCliReference$zodSchema,
-]);
-
 export type CreateV2EvalRequestMcp =
   | V2InlineMcpDefinition
   | V2SavedMcpReference;
@@ -47,8 +34,11 @@ export type CreateV2EvalRequest = {
   judges: Array<string>;
   agent?: Array<string> | undefined;
   persona?: string | undefined;
-  clis?: Array<V2SavedCliReference | V2InlineCliReference> | undefined;
+  clis?: Array<string> | undefined;
   mcps?: Array<V2InlineMcpDefinition | V2SavedMcpReference> | undefined;
+  setup_commands?: Array<string> | undefined;
+  cleanup_commands?: Array<string> | undefined;
+  search_grounding?: SearchGroundingMode | undefined;
   runs?: number | undefined;
   tags?: Array<string> | undefined;
 };
@@ -58,11 +48,11 @@ export const CreateV2EvalRequest$zodSchema: z.ZodType<CreateV2EvalRequest> = z
     agent: z.array(z.string()).optional().describe(
       "Runnable agents from `GET /v2/agents`. An empty array saves the eval without default agents. CLI clients expose repeatable `--agent`.",
     ),
-    clis: z.array(z.union([
-      V2SavedCliReference$zodSchema,
-      V2InlineCliReference$zodSchema,
-    ])).optional().describe(
-      "Saved CLI references or inline installation commands.",
+    cleanup_commands: z.array(z.string()).optional().describe(
+      "Best-effort shell commands run sequentially after agent execution and result capture, before sandbox deletion. CLI clients expose repeatable `--cleanup-command`.",
+    ),
+    clis: z.array(z.string()).optional().describe(
+      "Saved CLI IDs or shell installation commands. UUID values resolve saved CLIs from `GET /v2/clis`; every other value is run as an installation command. CLI clients expose repeatable `--cli`.",
     ),
     judges: z.array(z.string()).describe(
       "Plain-text success criteria. CLI clients expose this as repeatable `--judge`.",
@@ -83,6 +73,12 @@ export const CreateV2EvalRequest$zodSchema: z.ZodType<CreateV2EvalRequest> = z
     runs: z.int().default(1).describe(
       "Independent attempts for every prompt-agent pair.",
     ),
+    search_grounding: SearchGroundingMode$zodSchema.optional().describe(
+      "Requested web-retrieval behavior for an eval run.",
+    ),
+    setup_commands: z.array(z.string()).optional().describe(
+      "Shell commands run sequentially in the prepared repository before the agent starts. CLI clients expose repeatable `--setup-command`.",
+    ),
     tags: z.array(z.string()).optional().describe(
       "Optional labels for organizing the eval. CLI clients may expose this string array as a repeatable `--tag` flag.",
     ),

package/src/models/createv2evalrunrequest.ts

@@ -5,33 +5,18 @@
 
 import * as z from "zod";
 import {
-  V2InlineCliReference,
-  V2InlineCliReference$zodSchema,
-} from "./v2inlineclireference.js";
+  SearchGroundingMode,
+  SearchGroundingMode$zodSchema,
+} from "./searchgroundingmode.js";
 import {
   V2InlineMcpDefinition,
   V2InlineMcpDefinition$zodSchema,
 } from "./v2inlinemcpdefinition.js";
-import {
-  V2SavedCliReference,
-  V2SavedCliReference$zodSchema,
-} from "./v2savedclireference.js";
 import {
   V2SavedMcpReference,
   V2SavedMcpReference$zodSchema,
 } from "./v2savedmcpreference.js";
 
-export type CreateV2EvalRunRequestCli =
-  | V2SavedCliReference
-  | V2InlineCliReference;
-
-export const CreateV2EvalRunRequestCli$zodSchema: z.ZodType<
-  CreateV2EvalRunRequestCli
-> = z.union([
-  V2SavedCliReference$zodSchema,
-  V2InlineCliReference$zodSchema,
-]);
-
 export type CreateV2EvalRunRequestMcp =
   | V2InlineMcpDefinition
   | V2SavedMcpReference;
@@ -54,14 +39,17 @@ export type CreateV2EvalRunRequest = {
   judges?: Array<string> | null | undefined;
   agent?: Array<string> | null | undefined;
   persona?: string | undefined;
-  clis?: Array<V2SavedCliReference | V2InlineCliReference> | null | undefined;
+  clis?: Array<string> | null | undefined;
   mcps?: Array<V2InlineMcpDefinition | V2SavedMcpReference> | null | undefined;
+  setup_commands?: Array<string> | null | undefined;
+  cleanup_commands?: Array<string> | null | undefined;
   runs?: number | undefined;
   tags?: Array<string> | undefined;
   repository?: string | undefined;
   env?: { [k: string]: string } | undefined;
   skills?: Array<string> | undefined;
   skill_ids?: Array<string> | undefined;
+  search_grounding?: SearchGroundingMode | null | undefined;
 };
 
 export const CreateV2EvalRunRequest$zodSchema: z.ZodType<
@@ -70,11 +58,11 @@ export const CreateV2EvalRunRequest$zodSchema: z.ZodType<
   agent: z.array(z.string()).nullable().optional().describe(
     "Runnable agents from `GET /v2/agents`. Required unless the saved eval already has agents. CLI clients expose repeatable `--agent`.",
   ),
-  clis: z.array(z.union([
-    V2SavedCliReference$zodSchema,
-    V2InlineCliReference$zodSchema,
-  ])).nullable().optional().describe(
-    "Saved CLI references or inline installation commands. In saved mode, an explicit empty array disables saved CLIs for this launch.",
+  cleanup_commands: z.array(z.string()).nullable().optional().describe(
+    "Best-effort shell commands run sequentially after agent execution and result capture, before sandbox deletion. In saved mode, an explicit empty array disables saved cleanup commands for this launch. CLI clients expose repeatable `--cleanup-command`.",
+  ),
+  clis: z.array(z.string()).nullable().optional().describe(
+    "Saved CLI IDs or shell installation commands. UUID values resolve saved CLIs from `GET /v2/clis`; every other value is run as an installation command. In saved mode, an explicit empty array disables saved CLIs for this launch. CLI clients expose repeatable `--cli`.",
   ),
   configuration_id: z.string().optional().describe(
     "Saved-run form only. Optional saved repository, environment, skills, and legacy tool configuration.",
@@ -109,6 +97,13 @@ export const CreateV2EvalRunRequest$zodSchema: z.ZodType<
   runs: z.int().optional().describe(
     "Independent attempts for every prompt-agent pair. Defaults to the saved eval value or 1 for a direct run.",
   ),
+  search_grounding: SearchGroundingMode$zodSchema.nullable().optional()
+    .describe(
+      "Web-retrieval policy for this launch. Overrides the selected configuration or saved eval when provided; direct runs default to `default`.",
+    ),
+  setup_commands: z.array(z.string()).nullable().optional().describe(
+    "Shell commands run sequentially in the prepared repository before the agent starts. In saved mode, an explicit empty array disables saved setup commands for this launch. CLI clients expose repeatable `--setup-command`.",
+  ),
   skill_ids: z.array(z.string()).optional().describe(
     "Direct create-and-run form only. Reusable skill IDs from `GET /v2/skills` to install before the agent starts.",
   ),

package/src/models/evaltemplate.ts

@@ -0,0 +1,154 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: ea68162f8775
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+import {
+  EvalTemplateRuntime,
+  EvalTemplateRuntime$zodSchema,
+} from "./evaltemplateruntime.js";
+import {
+  EvalTemplateSchedule,
+  EvalTemplateSchedule$zodSchema,
+} from "./evaltemplateschedule.js";
+import {
+  GraderDefinition,
+  GraderDefinition$zodSchema,
+} from "./graderdefinition.js";
+
+/**
+ * Kind of eval the template creates. A template only applies to evals of the same type.
+ */
+export const EvalTemplateEvalType = {
+  CustomEval: "custom_eval",
+  AgentPreference: "agent_preference",
+} as const;
+/**
+ * Kind of eval the template creates. A template only applies to evals of the same type.
+ */
+export type EvalTemplateEvalType = ClosedEnum<typeof EvalTemplateEvalType>;
+
+export const EvalTemplateEvalType$zodSchema = z.enum([
+  "custom_eval",
+  "agent_preference",
+]).describe(
+  "Kind of eval the template creates. A template only applies to evals of the same type.",
+);
+
+export const EvalTemplateIncludedComponent = {
+  Judges: "judges",
+  Targets: "targets",
+  Persona: "persona",
+  Competitors: "competitors",
+  Tag: "tag",
+  Category: "category",
+  Runs: "runs",
+  Schedule: "schedule",
+  Repository: "repository",
+  Environment: "environment",
+  SearchGrounding: "search_grounding",
+  Skills: "skills",
+  McpServers: "mcp_servers",
+  Clis: "clis",
+  BrandDocs: "brand_docs",
+  GithubPr: "github_pr",
+  RuntimeCommands: "runtime_commands",
+} as const;
+export type EvalTemplateIncludedComponent = ClosedEnum<
+  typeof EvalTemplateIncludedComponent
+>;
+
+export const EvalTemplateIncludedComponent$zodSchema = z.enum([
+  "judges",
+  "targets",
+  "persona",
+  "competitors",
+  "tag",
+  "category",
+  "runs",
+  "schedule",
+  "repository",
+  "environment",
+  "search_grounding",
+  "skills",
+  "mcp_servers",
+  "clis",
+  "brand_docs",
+  "github_pr",
+  "runtime_commands",
+]);
+
+export type EvalTemplate = {
+  name: string;
+  description?: string | null | undefined;
+  eval_type?: EvalTemplateEvalType | undefined;
+  included_components: Array<EvalTemplateIncludedComponent>;
+  persona?: string | null | undefined;
+  category_name?: string | null | undefined;
+  tag?: string | null | undefined;
+  competitor_ids?: Array<string> | undefined;
+  judges?: Array<GraderDefinition> | undefined;
+  target_keys?: Array<string> | undefined;
+  schedule?: EvalTemplateSchedule | undefined;
+  runs_per_execution?: number | undefined;
+  runtime?: EvalTemplateRuntime | undefined;
+  id: string;
+  org_id: string;
+  version: number;
+  created_by?: string | null | undefined;
+  created_at: string;
+  updated_at: string;
+  deleted_at?: string | null | undefined;
+};
+
+export const EvalTemplate$zodSchema: z.ZodType<EvalTemplate> = z.object({
+  category_name: z.string().nullable().optional().describe(
+    "Optional category copied when `category` is included.",
+  ),
+  competitor_ids: z.array(z.string()).optional().describe(
+    "Competitor IDs that create additional variants when `competitors` is included.",
+  ),
+  created_at: z.iso.datetime({ offset: true }),
+  created_by: z.string().nullable().optional(),
+  deleted_at: z.iso.datetime({ offset: true }).nullable().optional(),
+  description: z.string().nullable().optional().describe(
+    "Optional guidance describing when to use the template.",
+  ),
+  eval_type: EvalTemplateEvalType$zodSchema.default("custom_eval").describe(
+    "Kind of eval the template creates. A template only applies to evals of the same type.",
+  ),
+  id: z.string(),
+  included_components: z.array(EvalTemplateIncludedComponent$zodSchema)
+    .describe(
+      "Settings copied when the template is applied. Omitted components do not override the new eval; included components copy their saved value, including an empty value.",
+    ),
+  judges: z.array(GraderDefinition$zodSchema).optional().describe(
+    "Judge definitions copied when `judges` is included. May be empty to explicitly create the eval without template judges.",
+  ),
+  name: z.string().describe(
+    "Organization-visible name for this reusable template.",
+  ),
+  org_id: z.string(),
+  persona: z.string().nullable().optional().describe(
+    "Optional persona copied when `persona` is included.",
+  ),
+  runs_per_execution: z.int().default(1).describe(
+    "Attempt count copied when `runs` is included.",
+  ),
+  runtime: EvalTemplateRuntime$zodSchema.optional().describe(
+    "Reusable runtime resources copied into each created eval.",
+  ),
+  schedule: EvalTemplateSchedule$zodSchema.optional().describe(
+    "Schedule copied into every eval created from the template.",
+  ),
+  tag: z.string().nullable().optional().describe(
+    "Optional tag copied when `tag` is included.",
+  ),
+  target_keys: z.array(z.string()).optional().describe(
+    "Runnable target keys copied when `targets` is included, such as `agent:codex:gpt-5.6-terra`.",
+  ),
+  updated_at: z.iso.datetime({ offset: true }),
+  version: z.int(),
+});

package/src/models/evaltemplatebatchcreatedeval.ts

@@ -0,0 +1,26 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 98054871a9ae
+ */
+
+import * as z from "zod";
+
+export type EvalTemplateBatchCreatedEval = {
+  id: string;
+  eval_id?: string | null | undefined;
+  name: string;
+  prompt: string;
+  competitor_id?: string | null | undefined;
+  competitor_name?: string | null | undefined;
+};
+
+export const EvalTemplateBatchCreatedEval$zodSchema: z.ZodType<
+  EvalTemplateBatchCreatedEval
+> = z.object({
+  competitor_id: z.string().nullable().optional(),
+  competitor_name: z.string().nullable().optional(),
+  eval_id: z.string().nullable().optional(),
+  id: z.string(),
+  name: z.string(),
+  prompt: z.string(),
+});

package/src/models/evaltemplatebatchitem.ts

@@ -0,0 +1,54 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 23c0fa6bda51
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * Eval subject type used for organization and reporting.
+ */
+export const EvalTemplateBatchItemType = {
+  Workflow: "workflow",
+  Mcp: "mcp",
+  Cli: "cli",
+  Skill: "skill",
+} as const;
+/**
+ * Eval subject type used for organization and reporting.
+ */
+export type EvalTemplateBatchItemType = ClosedEnum<
+  typeof EvalTemplateBatchItemType
+>;
+
+export const EvalTemplateBatchItemType$zodSchema = z.enum([
+  "workflow",
+  "mcp",
+  "cli",
+  "skill",
+]).describe("Eval subject type used for organization and reporting.");
+
+/**
+ * Prompt-specific fields combined with the referenced template.
+ */
+export type EvalTemplateBatchItem = {
+  name: string;
+  prompts: Array<string>;
+  type?: EvalTemplateBatchItemType | undefined;
+  subject_id?: string | null | undefined;
+};
+
+export const EvalTemplateBatchItem$zodSchema: z.ZodType<EvalTemplateBatchItem> =
+  z.object({
+    name: z.string().describe("Name of the prompt-specific eval to create."),
+    prompts: z.array(z.string()).describe(
+      "Task prompts owned by this eval. Judges, targets, scheduling, and runtime resources come from the template.",
+    ),
+    subject_id: z.string().nullable().optional().describe(
+      "Optional subject identifier associated with this eval.",
+    ),
+    type: EvalTemplateBatchItemType$zodSchema.default("workflow").describe(
+      "Eval subject type used for organization and reporting.",
+    ),
+  }).describe("Prompt-specific fields combined with the referenced template.");

package/src/models/evaltemplatebatchresponse.ts

@@ -0,0 +1,30 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: a63a246560d8
+ */
+
+import * as z from "zod";
+import {
+  EvalTemplateBatchResult,
+  EvalTemplateBatchResult$zodSchema,
+} from "./evaltemplatebatchresult.js";
+
+export type EvalTemplateBatchResponse = {
+  template_id: string;
+  template_version: number;
+  created_count: number;
+  base_count: number;
+  variant_count: number;
+  results?: Array<EvalTemplateBatchResult> | undefined;
+};
+
+export const EvalTemplateBatchResponse$zodSchema: z.ZodType<
+  EvalTemplateBatchResponse
+> = z.object({
+  base_count: z.int(),
+  created_count: z.int(),
+  results: z.array(EvalTemplateBatchResult$zodSchema).optional(),
+  template_id: z.string(),
+  template_version: z.int(),
+  variant_count: z.int(),
+});

package/src/models/evaltemplatebatchresult.ts

@@ -0,0 +1,26 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: f2e21f14a77e
+ */
+
+import * as z from "zod";
+import {
+  EvalTemplateBatchCreatedEval,
+  EvalTemplateBatchCreatedEval$zodSchema,
+} from "./evaltemplatebatchcreatedeval.js";
+
+export type EvalTemplateBatchResult = {
+  input_index: number;
+  name: string;
+  base: EvalTemplateBatchCreatedEval;
+  variants?: Array<EvalTemplateBatchCreatedEval> | undefined;
+};
+
+export const EvalTemplateBatchResult$zodSchema: z.ZodType<
+  EvalTemplateBatchResult
+> = z.object({
+  base: EvalTemplateBatchCreatedEval$zodSchema,
+  input_index: z.int(),
+  name: z.string(),
+  variants: z.array(EvalTemplateBatchCreatedEval$zodSchema).optional(),
+});

package/src/models/evaltemplateruntime.ts

@@ -0,0 +1,64 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: c5af571c2713
+ */
+
+import * as z from "zod";
+import {
+  SearchGroundingMode,
+  SearchGroundingMode$zodSchema,
+} from "./searchgroundingmode.js";
+
+/**
+ * Reusable runtime resources copied into each created eval.
+ */
+export type EvalTemplateRuntime = {
+  starting_project_id?: string | null | undefined;
+  environment_profile_ids?: Array<string> | undefined;
+  include_env_vars?: boolean | undefined;
+  search_grounding?: SearchGroundingMode | undefined;
+  skill_ids?: Array<string> | undefined;
+  mcp_server_ids?: Array<string> | undefined;
+  cli_ids?: Array<string> | undefined;
+  include_brand_docs?: boolean | undefined;
+  run_on_github_pr?: boolean | undefined;
+  setup_commands?: Array<string> | undefined;
+  cleanup_commands?: Array<string> | undefined;
+};
+
+export const EvalTemplateRuntime$zodSchema: z.ZodType<EvalTemplateRuntime> = z
+  .object({
+    cleanup_commands: z.array(z.string()).optional().describe(
+      "Shell commands run after each eval attempt, in order.",
+    ),
+    cli_ids: z.array(z.string()).optional().describe(
+      "Reusable CLI IDs copied into each created eval.",
+    ),
+    environment_profile_ids: z.array(z.string()).optional().describe(
+      "Environment profile IDs copied into each created eval.",
+    ),
+    include_brand_docs: z.boolean().default(false).describe(
+      "Whether organization documentation is included at runtime.",
+    ),
+    include_env_vars: z.boolean().default(true).describe(
+      "Whether selected environment profiles are enabled.",
+    ),
+    mcp_server_ids: z.array(z.string()).optional().describe(
+      "Reusable MCP server IDs copied into each created eval.",
+    ),
+    run_on_github_pr: z.boolean().default(false).describe(
+      "Whether each created eval is configured for GitHub pull requests.",
+    ),
+    search_grounding: SearchGroundingMode$zodSchema.optional().describe(
+      "Requested web-retrieval behavior for an eval run.",
+    ),
+    setup_commands: z.array(z.string()).optional().describe(
+      "Shell commands run before each eval attempt, in order.",
+    ),
+    skill_ids: z.array(z.string()).optional().describe(
+      "Reusable skill IDs copied into each created eval.",
+    ),
+    starting_project_id: z.string().nullable().optional().describe(
+      "Optional reusable repository workspace ID.",
+    ),
+  }).describe("Reusable runtime resources copied into each created eval.");

package/src/models/evaltemplateschedule.ts

@@ -0,0 +1,44 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: e2a92236d519
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * Schedule cadence used when `enabled` is true.
+ */
+export const Frequency = {
+  Daily: "daily",
+  EveryOtherDay: "every_other_day",
+  Weekly: "weekly",
+} as const;
+/**
+ * Schedule cadence used when `enabled` is true.
+ */
+export type Frequency = ClosedEnum<typeof Frequency>;
+
+export const Frequency$zodSchema = z.enum([
+  "daily",
+  "every_other_day",
+  "weekly",
+]).describe("Schedule cadence used when `enabled` is true.");
+
+/**
+ * Schedule copied into every eval created from the template.
+ */
+export type EvalTemplateSchedule = {
+  enabled?: boolean | undefined;
+  frequency?: Frequency | undefined;
+};
+
+export const EvalTemplateSchedule$zodSchema: z.ZodType<EvalTemplateSchedule> = z
+  .object({
+    enabled: z.boolean().default(false).describe(
+      "Whether each eval created from the template receives a schedule.",
+    ),
+    frequency: Frequency$zodSchema.default("weekly").describe(
+      "Schedule cadence used when `enabled` is true.",
+    ),
+  }).describe("Schedule copied into every eval created from the template.");

package/src/models/evaltemplatesresponse.ts

@@ -0,0 +1,18 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 72a47845de15
+ */
+
+import * as z from "zod";
+import { EvalTemplate, EvalTemplate$zodSchema } from "./evaltemplate.js";
+
+export type EvalTemplatesResponse = {
+  data?: Array<EvalTemplate> | undefined;
+  count: number;
+};
+
+export const EvalTemplatesResponse$zodSchema: z.ZodType<EvalTemplatesResponse> =
+  z.object({
+    count: z.int(),
+    data: z.array(EvalTemplate$zodSchema).optional(),
+  });

package/src/models/graderdefinition.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: e683eba11663
+ */
+
+import * as z from "zod";
+
+export type GraderDefinition = {
+  name: string;
+  type: string;
+  needle?: string | null | undefined;
+  needles?: Array<string> | null | undefined;
+  pattern?: string | null | undefined;
+  case_sensitive?: boolean | undefined;
+  criteria?: string | null | undefined;
+  weight?: number | undefined;
+  blocking?: boolean | undefined;
+};
+
+export const GraderDefinition$zodSchema: z.ZodType<GraderDefinition> = z.object(
+  {
+    blocking: z.boolean().default(false).describe(
+      "Whether a failed or missing result from this grader fails the entire eval regardless of the aggregate score.",
+    ),
+    case_sensitive: z.boolean().default(false),
+    criteria: z.string().nullable().optional(),
+    name: z.string(),
+    needle: z.string().nullable().optional(),
+    needles: z.array(z.string()).nullable().optional(),
+    pattern: z.string().nullable().optional(),
+    type: z.string(),
+    weight: z.number().default(1),
+  },
+);

package/src/models/publiccompetitorrow.ts

@@ -26,11 +26,11 @@ export const PublicCompetitorRow$zodSchema: z.ZodType<PublicCompetitorRow> = z
     ),
     company: PublicCompany$zodSchema,
     share_of_voice: z.number().nullable().optional().describe(
-      "Share of all brand mentions across tracked companies, 0 to 1; rows sum to about 1.",
+      "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded. A run can mention several companies, so rows do not sum to 1.",
     ),
     share_of_voice_rank: z.int().nullable().optional(),
     visibility_score: z.number().nullable().optional().describe(
-      "The company's visibility score, from 0 to 1. Rows do not sum to 1.",
+      "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. Rows do not sum to 1.",
     ),
     visibility_score_rank: z.int().nullable().optional(),
   });