@lightsage/mcp 0.4.17 → 0.4.19

package/src/funcs/promptsTargetsList.ts

@@ -0,0 +1,148 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 053c9d85cd77
+ */
+
+import { LightsageMcpCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  V2PromptTargetsListRequest,
+  V2PromptTargetsListRequest$zodSchema,
+} from "../models/v2prompttargetslistop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * List Targets
+ *
+ * @remarks
+ * Returns the answer engines and coding agents that run the organization's prompts on schedule, with each target's topic and frequency. Provide `topic_id` to list one topic's targets.
+ */
+export function promptsTargetsList(
+  client$: LightsageMcpCore,
+  request?: V2PromptTargetsListRequest | undefined,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: LightsageMcpCore,
+  request?: V2PromptTargetsListRequest | undefined,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => V2PromptTargetsListRequest$zodSchema.optional().parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/v2/prompts/targets")();
+  const query$ = encodeFormQuery({
+    "topic_id": payload$?.topic_id,
+  });
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "v2_prompt_targets_list",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}

package/src/funcs/promptsTargetsSet.ts

@@ -0,0 +1,145 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 1b39d535380b
+ */
+
+import { LightsageMcpCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  SetV2PromptTargetsRequest,
+  SetV2PromptTargetsRequest$zodSchema,
+} from "../models/setv2prompttargetsrequest.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Set Targets
+ *
+ * @remarks
+ * Sets which answer engines and coding agents run a topic's prompts on schedule, the same way the prompt editor does. The list replaces the topic's targets: targets you leave out stop running. Every prompt in the topic is set to exactly these platforms; you can still narrow one prompt afterwards with `platform_ids`. Name coding agents with IDs from `GET /v2/agents`, and list a harness more than once to run it on several models. To pick agents for a single run without changing the schedule, pass `agent` to `POST /v2/prompts/runs` instead.
+ */
+export function promptsTargetsSet(
+  client$: LightsageMcpCore,
+  request: SetV2PromptTargetsRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: LightsageMcpCore,
+  request: SetV2PromptTargetsRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => SetV2PromptTargetsRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = encodeJSON("body", payload$, { explode: true });
+  const path$ = pathToFunc("/v2/prompts/targets")();
+
+  const headers$ = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "v2_prompt_targets_set",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "PUT",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}

package/src/funcs/visibilityCitationsList.ts

@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
  * List Top Cited Urls
  *
  * @remarks
- * Returns URL-level citation counts ranked from most to least cited. Results can be filtered by platform and to owned or external sources.
+ * Returns URL-level citation counts ranked from most to least cited. Results can be filtered by platform and to owned or external sources. For totals by URL prefix, domain, or day compared with the previous period, use the citations summary.
  */
 export function visibilityCitationsList(
   client$: LightsageMcpCore,
@@ -89,6 +89,7 @@ async function $do(
   const query$ = encodeFormQuery({
     "end_date": payload$?.end_date,
     "limit": payload$?.limit,
+    "period": payload$?.period,
     "platform": payload$?.platform,
     "source_type": payload$?.source_type,
     "start_date": payload$?.start_date,

package/src/funcs/visibilityCitationsSummaryRetrieve.ts

@@ -0,0 +1,158 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: ce453917507f
+ */
+
+import { LightsageMcpCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  V2VisibilityCitationsSummaryRetrieveRequest,
+  V2VisibilityCitationsSummaryRetrieveRequest$zodSchema,
+} from "../models/v2visibilitycitationssummaryretrieveop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Retrieve Citation Summary
+ *
+ * @remarks
+ * Returns citation totals grouped by URL prefix (domain and first path segment, such as `example.com/blog`), URL, domain, or day, each compared with the previous period, with per-run rates and run coverage. Filter to one section of a site with `url_prefix`, for example `https://example.com/blog/`. Aggregated in one call; use it instead of paging the citations list.
+ */
+export function visibilityCitationsSummaryRetrieve(
+  client$: LightsageMcpCore,
+  request?: V2VisibilityCitationsSummaryRetrieveRequest | undefined,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: LightsageMcpCore,
+  request?: V2VisibilityCitationsSummaryRetrieveRequest | undefined,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) =>
+      V2VisibilityCitationsSummaryRetrieveRequest$zodSchema.optional().parse(
+        value$,
+      ),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/v2/visibility/citations/summary")();
+  const query$ = encodeFormQuery({
+    "end_date": payload$?.end_date,
+    "group_by": payload$?.group_by,
+    "limit": payload$?.limit,
+    "period": payload$?.period,
+    "platform": payload$?.platform,
+    "source_type": payload$?.source_type,
+    "start_date": payload$?.start_date,
+    "url_prefix": payload$?.url_prefix,
+  });
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "v2_visibility_citations_summary_retrieve",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}

package/src/funcs/visibilityCurrentRetrieve.ts

@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
  * Retrieve Current Visibility
  *
  * @remarks
- * Returns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company. Metrics are computed from active prompts only; when no data exists, values are `null`.
+ * Returns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company, with the same metrics for the previous period, run coverage, and per-run rates. Metrics are computed from active prompts only; when no data exists, values are `null`. Pass `period` (for example `last_30_days` or `2026Q4`) instead of computing dates.
  */
 export function visibilityCurrentRetrieve(
   client$: LightsageMcpCore,
@@ -88,6 +88,7 @@ async function $do(
   const path$ = pathToFunc("/v2/visibility/current")();
   const query$ = encodeFormQuery({
     "end_date": payload$?.end_date,
+    "period": payload$?.period,
     "start_date": payload$?.start_date,
   });
 

package/src/funcs/visibilityOverviewRetrieve.ts

@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
  * Retrieve Visibility Overview
  *
  * @remarks
- * Returns aggregate snapshot, daily trends, per-platform breakdowns, and competitor comparison. Calculated from active prompts only.
+ * Returns aggregate snapshot, daily trends, per-platform breakdowns, and competitor comparison, with run coverage and per-run rates against the previous period. Calculated from active prompts only.
  */
 export function visibilityOverviewRetrieve(
   client$: LightsageMcpCore,
@@ -88,6 +88,7 @@ async function $do(
   const path$ = pathToFunc("/v2/visibility/overview")();
   const query$ = encodeFormQuery({
     "end_date": payload$?.end_date,
+    "period": payload$?.period,
     "start_date": payload$?.start_date,
   });
 

package/src/funcs/visibilityPromptsRetrieve.ts

@@ -88,6 +88,7 @@ async function $do(
   const path$ = pathToFunc("/v2/visibility/prompts")();
   const query$ = encodeFormQuery({
     "end_date": payload$?.end_date,
+    "period": payload$?.period,
     "start_date": payload$?.start_date,
   });
 

package/src/landing-page.ts

@@ -931,7 +931,7 @@ http_headers = { "lightsage-api-key-auth" = "YOUR_LIGHTSAGE_API_KEY_AUTH" }`;
         <h1>Instructions</h1>
         <p>One-click installation for Claude Desktop users</p>
         <div class="instruction-item">
-          <a href="https://github.com/lightsagehq/mcp/releases/download/v0.4.17/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
+          <a href="https://github.com/lightsagehq/mcp/releases/download/v0.4.19/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
             📥 Download MCP Bundle
           </a>
         </div>

package/src/lib/config.ts

@@ -66,7 +66,7 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0.0",
-  sdkVersion: "0.4.17",
+  sdkVersion: "0.4.19",
   genVersion: "2.948.4",
-  userAgent: "speakeasy-sdk/mcp-typescript 0.4.17 2.948.4 1.0.0 @lightsage/mcp",
+  userAgent: "speakeasy-sdk/mcp-typescript 0.4.19 2.948.4 1.0.0 @lightsage/mcp",
 } as const;

package/src/mcp-server/mcp-server.ts

@@ -22,7 +22,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.4.17",
+    currentVersion: "0.4.19",
   },
 });
 

package/src/mcp-server/server.ts

@@ -64,9 +64,12 @@ import { tool$promptsDelete } from "./tools/promptsDelete.js";
 import { tool$promptsList } from "./tools/promptsList.js";
 import { tool$promptsRetrieve } from "./tools/promptsRetrieve.js";
 import { tool$promptsRun } from "./tools/promptsRun.js";
+import { tool$promptsRunCancel } from "./tools/promptsRunCancel.js";
 import { tool$promptsRunsList } from "./tools/promptsRunsList.js";
 import { tool$promptsRunsRetrieve } from "./tools/promptsRunsRetrieve.js";
 import { tool$promptsRunStatus } from "./tools/promptsRunStatus.js";
+import { tool$promptsTargetsList } from "./tools/promptsTargetsList.js";
+import { tool$promptsTargetsSet } from "./tools/promptsTargetsSet.js";
 import { tool$promptsTopicsCreate } from "./tools/promptsTopicsCreate.js";
 import { tool$promptsTopicsDelete } from "./tools/promptsTopicsDelete.js";
 import { tool$promptsTopicsList } from "./tools/promptsTopicsList.js";
@@ -87,6 +90,7 @@ import { tool$tasksList } from "./tools/tasksList.js";
 import { tool$tasksRetrieve } from "./tools/tasksRetrieve.js";
 import { tool$tasksUpdate } from "./tools/tasksUpdate.js";
 import { tool$visibilityCitationsList } from "./tools/visibilityCitationsList.js";
+import { tool$visibilityCitationsSummaryRetrieve } from "./tools/visibilityCitationsSummaryRetrieve.js";
 import { tool$visibilityCurrentRetrieve } from "./tools/visibilityCurrentRetrieve.js";
 import { tool$visibilityOverviewRetrieve } from "./tools/visibilityOverviewRetrieve.js";
 import { tool$visibilityPromptsRetrieve } from "./tools/visibilityPromptsRetrieve.js";
@@ -110,7 +114,7 @@ export function createMCPServer(deps: {
       sizes: ["any"],
     }],
     name: "LightsageMcp",
-    version: "0.4.17",
+    version: "0.4.19",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -161,12 +165,15 @@ export function createMCPServer(deps: {
   tool(tool$visibilityOverviewRetrieve);
   tool(tool$visibilityCitationsList);
   tool(tool$visibilityPromptsRetrieve);
+  tool(tool$visibilityCitationsSummaryRetrieve);
   tool(tool$promptsList);
   tool(tool$promptsCreate);
   tool(tool$promptsTopicsList);
   tool(tool$promptsTopicsCreate);
   tool(tool$promptsTopicsUpdate);
   tool(tool$promptsTopicsDelete);
+  tool(tool$promptsTargetsList);
+  tool(tool$promptsTargetsSet);
   tool(tool$promptsRunsList);
   tool(tool$promptsRunsRetrieve);
   tool(tool$promptsRetrieve);
@@ -174,6 +181,7 @@ export function createMCPServer(deps: {
   tool(tool$promptsDelete);
   tool(tool$promptsRun);
   tool(tool$promptsRunStatus);
+  tool(tool$promptsRunCancel);
   tool(tool$opportunitiesList);
   tool(tool$opportunitiesRetrieve);
   tool(tool$tasksList);

package/src/mcp-server/tools/agentAnalyticsSummaryRetrieve.ts

@@ -15,7 +15,7 @@ export const tool$agentAnalyticsSummaryRetrieve: ToolDefinition<typeof args> = {
   name: "agent-analytics-summary-retrieve",
   description: `Retrieve Agent Analytics Summary
 
-Returns a site's visits by traffic type (coding agents, user-requested AI fetches, AI search, AI training, other bots, and people) for the date range and for the same number of days before it.`,
+Returns a site's visits by traffic type (coding agents, user-requested AI fetches, AI search, AI training, other bots, and people) for the date range and for the previous period (the same number of days before it, or the previous calendar week, month, or quarter for a named \`period\`).`,
   annotations: {
     "title": "",
     "destructiveHint": false,

package/src/mcp-server/tools/agentsList.ts

@@ -10,7 +10,7 @@ export const tool$agentsList: ToolDefinition = {
   name: "agents-list",
   description: `List Agents
 
-Returns the harness-and-model combinations your plan can run, as single agent IDs for use in eval runs.`,
+Returns the coding-agent harness-and-model combinations your plan can run, as single agent IDs. Pass them as \`agent\` to \`POST /v2/prompts/runs\` to see how coding agents answer your prompts, with mentions and citations, or to \`PUT /v2/prompts/targets\` to run them on a schedule; to \`POST /v2/agent-preference/evals\` to see whether agents recommend your company over one competitor; or to \`POST /v2/evals\` and \`POST /v2/eval-runs\` to measure how well agents complete tasks with your product.`,
   annotations: {
     "title": "",
     "destructiveHint": false,

package/src/mcp-server/tools/evalsCreate.ts

@@ -15,7 +15,9 @@ export const tool$evalsCreate: ToolDefinition<typeof args> = {
   name: "evals-create",
   description: `Create Eval
 
-Creates a reusable simulation definition with one or more task prompts and judges. Optional agents, persona, CLI installations, MCP servers, setup commands, cleanup commands, grounding policy, repeat count, and tags are saved with the eval. \`search_grounding\` supports \`disabled\`, \`enabled\`, and \`default\`; \`default\` preserves normal platform behavior. Creating the eval does not start a run and does not accept secret environment values.`,
+Creates a reusable simulation definition with one or more task prompts and judges. Optional agents, persona, CLI installations, MCP servers, setup commands, cleanup commands, grounding policy, repeat count, and tags are saved with the eval. \`search_grounding\` supports \`disabled\`, \`enabled\`, and \`default\`; \`default\` preserves normal platform behavior. Creating the eval does not start a run and does not accept secret environment values.
+
+Evals measure how well agents complete tasks with your product. To track how agents and answer engines answer research questions, including which brands they mention and cite, run prompts with \`POST /v2/prompts/runs\` instead.`,
   annotations: {
     "title": "",
     "destructiveHint": false,

package/src/mcp-server/tools/evalsRun.ts

@@ -17,6 +17,8 @@ export const tool$evalsRun: ToolDefinition<typeof args> = {
 
 Queues a durable eval job and returns immediately with a polling ID. Poll \`GET /v2/eval-runs/{run_id}\` until its status reaches a terminal value; once finished it also returns the results and analysis. Follow a run live with the monitor operation.
 
+Eval runs measure how well agents complete tasks with your product. To compare how coding agents and answer engines answer the same research question, with mentions and citations, use \`POST /v2/prompts/runs\` with \`agent\` instead.
+
 Send one of these flat request forms:
 
 - **Saved eval:** provide \`eval_id\`; optionally replace its prompts, persona, agents, CLIs, MCPs, setup commands, cleanup commands, or runs for this launch. A saved configuration can still provide repository, environment, skills, and legacy tool selections.

package/src/mcp-server/tools/promptsRun.ts

@@ -15,11 +15,16 @@ export const tool$promptsRun: ToolDefinition<typeof args> = {
   name: "prompts-run",
   description: `Run Prompts
 
-Queue saved prompts using the organization's configured targets.
+Queue saved prompts on answer engines and coding agents.
 
 Provide \`prompt_ids\` to run selected prompts, or omit them to run all active
-prompts. Saved prompt run settings apply to coding-agent targets. The
-response returns a run ID to poll with
+prompts. By default the run uses the organization's configured targets,
+listed by \`GET /v2/prompts/targets\`.
+Provide \`agent\` with IDs from \`GET /v2/agents\` to run the prompts on
+specific coding-agent harnesses and models instead, for example to compare
+how several coding tools answer the same developer question. Results
+include mentions and citations. Saved prompt run settings apply to
+coding-agent targets. The response returns a run ID to poll with
 \`GET /v2/prompts/runs/{run_id}/status\`.`,
   annotations: {
     "title": "",