@certscore/mcp 0.2.12 → 0.2.15

package/dist/certscore-mcp.mjs

@@ -15294,8 +15294,17 @@ var UrlElicitationRequiredError = class extends McpError {
 };
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
+  constructor(options) {
+    this._maxBufferSize = options?.maxBufferSize ?? STDIO_DEFAULT_MAX_BUFFER_SIZE;
+  }
   append(chunk) {
+    const newSize = (this._buffer?.length ?? 0) + chunk.length;
+    if (newSize > this._maxBufferSize) {
+      this.clear();
+      throw new Error(`ReadBuffer exceeded maximum size of ${this._maxBufferSize} bytes`);
+    }
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
   }
   readMessage() {
@@ -15323,18 +15332,24 @@ function serializeMessage(message) {
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
-  constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
-    this._readBuffer = new ReadBuffer();
     this._started = false;
     this._ondata = (chunk) => {
-      this._readBuffer.append(chunk);
-      this.processReadBuffer();
+      try {
+        this._readBuffer.append(chunk);
+        this.processReadBuffer();
+      } catch (error2) {
+        this.onerror?.(error2);
+        this.close().catch(() => {
+        });
+      }
     };
     this._onerror = (error2) => {
       this.onerror?.(error2);
     };
+    this._readBuffer = new ReadBuffer({ maxBufferSize: options?.maxBufferSize });
   }
   /**
    * Starts listening for messages on stdin.
@@ -15439,11 +15454,13 @@ var ThrottledError = class extends CertScoreError {
 var CertScoreScanFailedError = class extends CertScoreError {
   scanId;
   jobId;
+  retryAfterSeconds;
   constructor(message, options = {}) {
     super(message, options);
     this.name = "CertScoreScanFailedError";
     this.scanId = options.scanId ?? void 0;
     this.jobId = options.jobId ?? void 0;
+    this.retryAfterSeconds = options.retryAfterSeconds;
   }
 };
 
@@ -15512,9 +15529,10 @@ function throwForTerminalStatus(status) {
     });
   }
   if (FAILURE_STATUSES.has(status.status)) {
-    throw new CertScoreScanFailedError(status.message ?? `Pulse scan ended with status ${status.status}.`, {
-      code: status.status,
+    throw new CertScoreScanFailedError(status.error?.message ?? status.message ?? `Pulse scan ended with status ${status.status}.`, {
+      code: status.error?.code ?? status.status,
       jobId: status.jobId,
+      retryAfterSeconds: status.error?.retryAfterSeconds ?? void 0,
       scanId: status.scanId ?? status.scan_id ?? void 0,
       responseBody: status
     });
@@ -15873,7 +15891,10 @@ var CertScoreClient = class {
       const fallbackMs = options.adaptivePolling ? adaptivePollIntervalMs(elapsedMs) : options.pollIntervalMs;
       const delay = Math.min(retryDelayMs(status, void 0, fallbackMs), Math.max(0, options.maxWaitMs - elapsedMs));
       await sleep(delay, options.signal);
-      const response = await this.fetch(this.scanResourceStatusUrlFor(status), { signal: options.signal });
+      let response = await this.fetch(this.scanResourceStatusUrlFor(status), { signal: options.signal });
+      if (response.status === 404 && status.jobId) {
+        response = await this.fetch(this.statusUrlFor(status), { signal: options.signal });
+      }
       if (response.status === 202 || response.status === 200 || response.status === 429) {
         status = await response.json();
         options.onStatusUpdate?.(status);
@@ -20100,6 +20121,7 @@ var publicScanNoGoReasonCodes = [
   "maintenance_or_unavailable",
   "tls_or_certificate_error",
   "unsupported_region",
+  "target_unreachable_or_unsuitable",
   "navigation_transport_failure",
   "visual_capture_failed_or_placeholder",
   "retained_visual_error_shell",
@@ -20301,7 +20323,18 @@ var pulseErrorSchema = external_exports2.object({
   error: external_exports2.object({
     code: pulseErrorCodeSchema,
     message: external_exports2.string(),
-    retryAfterSeconds: external_exports2.number().int().nullable().optional()
+    retryAfterSeconds: external_exports2.number().int().nullable().optional(),
+    recommendedNextAction: external_exports2.string().nullable().optional(),
+    rateLimit: external_exports2.object({
+      limitUnits: external_exports2.number().int().positive(),
+      policyVersion: external_exports2.string(),
+      profile: external_exports2.enum(["terminal", "status"]),
+      requestedUnits: external_exports2.number().int().positive(),
+      scope: external_exports2.enum(["callerTarget", "target", "caller"]),
+      usedUnits: external_exports2.number().int().nonnegative(),
+      windowId: external_exports2.enum(["burst", "daily"]),
+      windowSeconds: external_exports2.number().int().positive()
+    }).nullable().optional()
   }).passthrough(),
   feedback: pulseFeedbackSchema.optional(),
   resolution: external_exports2.object({
@@ -20316,7 +20349,7 @@ var pulseErrorSchema = external_exports2.object({
 var apiV2Disclaimer = "CertScore outputs are automated public-web observations for review. They are not legal advice, certification, or a compliance determination.";
 var apiV2ScanStatusSchema = external_exports2.enum(["queued", "running", "finalizing", "completed", "completed_limited", "failed", "expired", "rate_limited"]);
 var apiV2ScanFreshnessSchema = external_exports2.enum(["latest", "refresh"]);
-var apiV2ScanFromSchema = external_exports2.enum(["eu_ie"]);
+var apiV2ScanFromSchema = external_exports2.enum(["eu_de", "eu_ie", "california"]);
 var apiV2FindingCriticalitySchema = external_exports2.enum(["critical", "high", "medium", "low", "info", "unknown"]);
 var apiV2FindingConfidenceSchema = external_exports2.enum(["strong", "good", "moderate", "weak", "unknown"]);
 var apiV2EvidenceBasisSchema = external_exports2.enum(["runtime_observation", "policy_surface_detection", "accessibility_check", "public_report_projection"]);
@@ -20335,7 +20368,7 @@ var apiV2ScanCreationMetadataShape = {
   anonymousQuotaResetAt: external_exports2.string().nullable().optional(),
   upgradeSupportEmail: external_exports2.string().email().nullable().optional(),
   upgradeMessage: external_exports2.string().nullable().optional(),
-  recommendedNextTool: external_exports2.enum(["get_scan_status", "get_scan_bundle"]).optional()
+  recommendedNextTool: external_exports2.enum(["certscore_get_scan_status", "certscore_get_scan_bundle"]).optional()
 };
 var apiV2LinksSchema = external_exports2.object({
   self: external_exports2.string().optional(),
@@ -20351,7 +20384,19 @@ var apiV2ErrorSchema = external_exports2.object({
   error: external_exports2.object({
     code: external_exports2.enum(["invalid_request", "invalid_url", "not_found", "rate_limited", "unauthorized", "forbidden", "scan_unavailable", "internal_error"]),
     message: external_exports2.string(),
-    retryAfterSeconds: external_exports2.number().int().nullable().optional()
+    retryable: external_exports2.boolean(),
+    retryAfterSeconds: external_exports2.number().int().nullable(),
+    recommendedNextAction: external_exports2.string(),
+    rateLimit: external_exports2.object({
+      limitUnits: external_exports2.number().int().positive(),
+      policyVersion: external_exports2.string(),
+      profile: external_exports2.enum(["terminal", "status"]),
+      requestedUnits: external_exports2.number().int().positive(),
+      scope: external_exports2.enum(["callerTarget", "target", "caller"]),
+      usedUnits: external_exports2.number().int().nonnegative(),
+      windowId: external_exports2.enum(["burst", "daily"]),
+      windowSeconds: external_exports2.number().int().positive()
+    }).optional()
   }).passthrough(),
   links: apiV2LinksSchema.optional(),
   disclaimer: external_exports2.string().optional(),
@@ -20369,6 +20414,7 @@ var apiV2ScanJobSchema = external_exports2.object({
   jobId: external_exports2.string(),
   scanId: external_exports2.string().nullable().optional(),
   domain: external_exports2.string().nullable().optional(),
+  url: external_exports2.string().nullable().optional(),
   status: apiV2ScanStatusSchema,
   resultDisposition: scanResultDispositionSchema.optional(),
   noGo: scanNoGoResultSchema.optional(),
@@ -20377,8 +20423,33 @@ var apiV2ScanJobSchema = external_exports2.object({
   startedAt: external_exports2.string().nullable().optional(),
   completedAt: external_exports2.string().nullable().optional(),
   scanTimeSeconds: external_exports2.number().nullable().optional(),
+  score: external_exports2.number().int().min(0).max(100).nullable().optional(),
+  scoreStatus: external_exports2.enum(["provisional", "final"]).optional(),
+  scoreVersion: external_exports2.string().nullable().optional(),
+  scoreUpdatedAt: external_exports2.string().nullable().optional(),
+  riskLevel: external_exports2.string().nullable().optional(),
+  coverage: external_exports2.object({
+    status: external_exports2.string().optional(),
+    summary: external_exports2.string().optional(),
+    limitations: external_exports2.array(external_exports2.string()).optional()
+  }).passthrough().nullable().optional(),
   lastUpdatedAt: external_exports2.string().optional(),
+  phaseStartedAt: external_exports2.string().nullable().optional(),
+  lastHeartbeatAt: external_exports2.string().nullable().optional(),
+  progressPercent: external_exports2.number().int().min(0).max(100).optional(),
+  progressIsEstimate: external_exports2.boolean().optional(),
+  estimatedRemainingSeconds: external_exports2.number().int().min(0).nullable().optional(),
+  stalled: external_exports2.boolean().optional(),
   retryAfterSeconds: external_exports2.number().int().nullable().optional(),
+  error: external_exports2.object({
+    code: external_exports2.string(),
+    message: external_exports2.string(),
+    retryable: external_exports2.boolean(),
+    retryAfterSeconds: external_exports2.number().int().nullable(),
+    recommendedNextAction: external_exports2.string()
+  }).strict().optional(),
+  reportUrl: external_exports2.string().nullable().optional(),
+  recommendedNextAction: external_exports2.string().optional(),
   links: apiV2LinksSchema.optional(),
   disclaimer: external_exports2.string().optional(),
   ...apiV2ScanCreationMetadataShape
@@ -20397,6 +20468,9 @@ var apiV2ScanResourceSchema = external_exports2.object({
   completedAt: external_exports2.string().nullable().optional(),
   scanTimeSeconds: external_exports2.number().nullable().optional(),
   score: external_exports2.number().int().min(0).max(100).nullable().optional(),
+  scoreStatus: external_exports2.enum(["provisional", "final"]).optional(),
+  scoreVersion: external_exports2.string().nullable().optional(),
+  scoreUpdatedAt: external_exports2.string().nullable().optional(),
   riskLevel: external_exports2.string().nullable().optional(),
   coverage: external_exports2.object({
     status: external_exports2.string().optional(),
@@ -20442,6 +20516,13 @@ var apiV2EvidenceSummarySchema = external_exports2.object({
   authRequiredForExamples: external_exports2.boolean().optional(),
   examples: external_exports2.array(apiV2EvidenceEventSummarySchema).max(5).optional(),
   projectionWarnings: external_exports2.array(external_exports2.string().max(120)).max(20).optional(),
+  excerpt: external_exports2.object({
+    excerpt: external_exports2.string(),
+    isTruncated: external_exports2.boolean(),
+    truncationMarker: external_exports2.string().nullable(),
+    sourceUrl: external_exports2.string().max(2048).nullable(),
+    evidenceUrl: external_exports2.string().max(2048)
+  }).strict().optional(),
   hasTimingAnchor: external_exports2.boolean().optional(),
   hasVendorAnchor: external_exports2.boolean().optional(),
   hasConsentContext: external_exports2.boolean().optional(),
@@ -20500,6 +20581,35 @@ var apiV2ScanDiagnosticPhaseSchema = external_exports2.object({
   durationMs: external_exports2.number().int().min(0),
   outcome: external_exports2.enum(["success", "degraded", "failed", "unknown"])
 }).strict();
+var apiV2ScanLaneRunSchema = external_exports2.object({
+  laneId: external_exports2.enum(["consent_proof", "runtime_evidence", "policy_evidence"]),
+  physicalInvocationId: external_exports2.string().max(160),
+  region: external_exports2.string().max(80),
+  phaseName: external_exports2.enum(["preConsentRuntimeScanner", "policySurfaceScanner"]),
+  startedAt: external_exports2.string(),
+  firstResponse: external_exports2.object({
+    at: external_exports2.string(),
+    offsetMs: external_exports2.number().int().min(0),
+    httpStatus: external_exports2.number().int().min(100).max(599),
+    effectiveUrl: external_exports2.string().max(500).nullable()
+  }).strict().nullable(),
+  navigationCount: external_exports2.number().int().min(0),
+  challengeDetection: external_exports2.object({
+    detected: external_exports2.boolean(),
+    type: external_exports2.string().max(120).nullable()
+  }).strict(),
+  executionOutcome: external_exports2.enum(["success", "degraded", "failed"]),
+  accessOutcome: external_exports2.enum([
+    "representative_page",
+    "bot_challenge",
+    "access_denied",
+    "blank_or_unusable",
+    "navigation_failed",
+    "unknown"
+  ]),
+  completedAt: external_exports2.string().nullable(),
+  durationMs: external_exports2.number().int().min(0)
+}).strict();
 var apiV2PolicyDiscoveryDiagnosticsSchema = external_exports2.object({
   candidatesDiscovered: external_exports2.number().int().min(0).nullable(),
   candidatesAfterDeduplication: external_exports2.number().int().min(0).nullable(),
@@ -20517,6 +20627,7 @@ var apiV2ScanDiagnosticsSchema = external_exports2.object({
   generatedAt: external_exports2.string().nullable(),
   totalWallMs: external_exports2.number().int().min(0).nullable(),
   phases: external_exports2.array(apiV2ScanDiagnosticPhaseSchema).max(20),
+  lanes: external_exports2.array(apiV2ScanLaneRunSchema).max(8).default([]),
   policyDiscovery: apiV2PolicyDiscoveryDiagnosticsSchema,
   links: apiV2LinksSchema.optional(),
   disclaimer: external_exports2.string().optional()
@@ -20533,6 +20644,65 @@ var apiV2PreConsentCookiesTrackersRowSchema = external_exports2.object({
   priority: apiV2PreConsentInventoryPrioritySchema.optional(),
   confidence: apiV2PreConsentInventoryConfidenceSchema.optional(),
   party: external_exports2.enum(["first_party", "third_party", "mixed", "unknown"]).optional(),
+  setByThirdPartyScript: external_exports2.boolean().optional(),
+  set_by_third_party_script: external_exports2.boolean().optional(),
+  cookieDetails: external_exports2.array(external_exports2.object({
+    name: external_exports2.string(),
+    domain: external_exports2.string().nullable(),
+    category: external_exports2.string(),
+    essentiality: external_exports2.enum(["essential", "non_essential", "unknown"]),
+    essentialityConfidence: external_exports2.number().min(0).max(1).nullable(),
+    essentialityReasonCodes: external_exports2.array(external_exports2.string().max(120)).max(20),
+    essentialitySource: external_exports2.enum(["canonical_registry", "deterministic_classifier", "retained_explicit_classification", "unknown"]),
+    description: external_exports2.string(),
+    dataTypes: external_exports2.array(external_exports2.string()),
+    expiresAt: external_exports2.string().nullable(),
+    lifespanSeconds: external_exports2.number().int().min(0).nullable(),
+    lifespanSource: external_exports2.string().nullable(),
+    longLived: external_exports2.boolean(),
+    setByThirdPartyScript: external_exports2.boolean(),
+    set_by_third_party_script: external_exports2.boolean(),
+    setterScriptUrl: external_exports2.string().nullable(),
+    initiatorChain: external_exports2.array(external_exports2.string())
+  }).strict()).optional(),
+  requestDetails: external_exports2.array(external_exports2.object({
+    cookieNamesSent: external_exports2.array(external_exports2.string().max(256)).max(24),
+    essentiality: external_exports2.enum(["non_essential", "unknown"]),
+    hostname: external_exports2.string().max(253).nullable(),
+    identifierParameterNames: external_exports2.array(external_exports2.string().max(256)).max(24),
+    initiatorUrl: external_exports2.string().max(500).nullable(),
+    method: external_exports2.string().max(24).nullable(),
+    path: external_exports2.string().max(2e3).nullable(),
+    responseCookieNamesSet: external_exports2.array(external_exports2.string().max(256)).max(24),
+    responseObserved: external_exports2.boolean(),
+    responseStorageAttempted: external_exports2.boolean(),
+    vendor: external_exports2.string().max(160).nullable()
+  }).strict()).max(50).optional(),
+  canonicalEntity: external_exports2.string().nullable().optional(),
+  purposes: external_exports2.array(external_exports2.string()).optional(),
+  domains: external_exports2.array(external_exports2.string()).optional(),
+  products: external_exports2.array(external_exports2.string()).optional(),
+  dataFlows: external_exports2.array(external_exports2.object({
+    endpoint: external_exports2.string(),
+    idSync: external_exports2.boolean(),
+    networkDestination: external_exports2.object({
+      ip: external_exports2.string().nullable(),
+      country: external_exports2.string().nullable(),
+      countryCode: external_exports2.string().nullable(),
+      asn: external_exports2.number().int().positive().nullable(),
+      provider: external_exports2.string().nullable(),
+      label: external_exports2.literal("server location (may be CDN edge)")
+    }).strict(),
+    controllingEntity: external_exports2.object({
+      legalEntity: external_exports2.string().nullable(),
+      headquartersCountry: external_exports2.string().nullable()
+    }).strict(),
+    transferMechanism: external_exports2.object({
+      mechanism: external_exports2.enum(["adequacy_decision", "dpf_certified", "sccs_assumed_unverified", "unknown"]),
+      basis: external_exports2.string(),
+      verifiedAsOf: external_exports2.string()
+    }).strict()
+  }).strict()).optional(),
   requestCount: external_exports2.number().int().min(0).nullable().optional(),
   phase: apiV2PreConsentInventoryPhaseSchema,
   observedBeforeConsent: external_exports2.boolean(),
@@ -20544,7 +20714,9 @@ var apiV2PreConsentCookiesTrackersSummarySchema = external_exports2.object({
   rowCount: external_exports2.number().int().min(0),
   trackerCount: external_exports2.number().int().min(0),
   cookieCount: external_exports2.number().int().min(0),
-  requestCount: external_exports2.number().int().min(0)
+  requestCount: external_exports2.number().int().min(0),
+  vendorCount: external_exports2.number().int().min(0).default(0),
+  domainCount: external_exports2.number().int().min(0).default(0)
 }).strict();
 var apiV2PreConsentCookiesTrackersSchema = external_exports2.object({
   type: external_exports2.literal("certscore_pre_consent_cookies_trackers"),
@@ -20562,7 +20734,7 @@ var mcpPulseDetailSchema = external_exports2.enum(["tiny", "quick", "standard",
 var mcpGptSafePulseDetailSchema = external_exports2.enum(["tiny", "standard", "summary"]);
 var mcpPulseFormatSchema = external_exports2.enum(["json", "markdown"]);
 var mcpPulseFreshnessSchema = external_exports2.enum(["latest", "refresh"]);
-var mcpScanFromSchema = external_exports2.enum(["eu_ie"]);
+var mcpScanFromSchema = apiV2ScanFromSchema;
 var mcpCreateScanInputSchema = {
   url: external_exports2.string().min(1).describe("Public URL or domain to scan."),
   detail: mcpPulseDetailSchema.optional().describe("Pulse detail level. Defaults to summary."),
@@ -20578,8 +20750,7 @@ var mcpScanSiteInputSchema = {
   maxWaitSeconds: external_exports2.number().int().min(1).max(45).optional().describe("Maximum time to wait before returning the still-running job. Defaults to 45 seconds; never turns an active scan into an error.")
 };
 var mcpGetScanStatusInputSchema = {
-  jobId: external_exports2.string().min(1).optional().describe("Pulse job ID for a just-created scan that has not yet returned a scanId."),
-  scanId: external_exports2.string().min(1).optional().describe("Preferred stable CertScore scan ID for API v2 scan status.")
+  scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID returned by certscore_scan_site.")
 };
 var mcpGetScanInputSchema = {
   scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID.")
@@ -20594,8 +20765,10 @@ var mcpGetEvidenceInputSchema = {
 };
 var mcpGetScanBundleInputSchema = {
   scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID."),
-  maxFindings: external_exports2.number().int().min(1).max(50).optional().describe("Maximum compact findings to return. Defaults to 20."),
-  maxPreConsentRows: external_exports2.number().int().min(1).max(50).optional().describe("Maximum pre-consent inventory rows to return. Defaults to 20.")
+  detail: external_exports2.enum(["summary", "findings", "evidence", "full"]).optional().describe("Response detail. Defaults to summary; evidence and full opt into heavier retained context."),
+  maxBytes: external_exports2.number().int().min(5e3).max(2e5).optional().describe("Maximum serialized structured response size in bytes. Defaults to 50000."),
+  maxFindings: external_exports2.number().int().min(1).max(50).optional().describe("Maximum compact findings to return. Defaults to 5 for summary and 20 otherwise."),
+  maxPreConsentRows: external_exports2.number().int().min(1).max(50).optional().describe("Maximum pre-consent inventory rows when evidence is requested. Defaults to 20.")
 };
 var mcpExportFindingsInputSchema = {
   scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID.")
@@ -20642,6 +20815,26 @@ var mcpToolErrorPayloadSchema = external_exports2.object({
     responseBody: external_exports2.unknown().optional()
   }).passthrough()
 }).passthrough();
+var mcpExecutiveSummarySchema = external_exports2.object({
+  completionSummary: external_exports2.string().optional(),
+  domain: external_exports2.string().optional(),
+  score: external_exports2.number().int().min(0).max(100).nullable().optional(),
+  scoreLabel: external_exports2.string().optional(),
+  scoreMetadata: external_exports2.object({
+    coverageConfidence: external_exports2.string().optional(),
+    coverageRatio: external_exports2.number().nullable().optional(),
+    kind: external_exports2.string().optional(),
+    metricLabel: external_exports2.string().optional(),
+    source: external_exports2.string().optional(),
+    status: external_exports2.string().optional(),
+    version: external_exports2.string().nullable().optional(),
+    withholdingReason: external_exports2.string().nullable().optional()
+  }).passthrough().optional(),
+  riskLevel: external_exports2.string().optional(),
+  actionLabel: external_exports2.string().optional(),
+  issuesToReview: external_exports2.number().int().min(0).optional(),
+  scanTimeSeconds: external_exports2.number().nullable().optional()
+}).passthrough();
 var mcpCreateScanOutputSchema = external_exports2.object({
   type: external_exports2.literal("certscore_mcp_scan_created"),
   status: external_exports2.string().nullable().optional(),
@@ -20655,18 +20848,41 @@ var mcpCreateScanOutputSchema = external_exports2.object({
   resultDisposition: scanResultDispositionSchema.nullable().optional(),
   noGo: scanNoGoResultSchema.nullable().optional()
 }).passthrough();
+var mcpActionableErrorSchema = external_exports2.object({
+  code: external_exports2.string(),
+  message: external_exports2.string(),
+  retryable: external_exports2.boolean(),
+  retryAfterSeconds: external_exports2.number().int().nullable(),
+  recommendedNextAction: external_exports2.string(),
+  field: external_exports2.string().optional(),
+  mcpCode: external_exports2.number().int().optional(),
+  name: external_exports2.string().optional(),
+  status: external_exports2.number().int().optional(),
+  responseBody: external_exports2.unknown().optional()
+}).strict();
 var mcpScanSiteOutputSchema = external_exports2.object({
-  type: external_exports2.enum(["certscore_scan", "certscore_scan_job"]),
+  type: external_exports2.enum(["certscore_scan", "certscore_scan_job", "certscore_tool_error"]),
   scanId: external_exports2.string().nullable().optional(),
   jobId: external_exports2.string().optional(),
   domain: external_exports2.string().nullable().optional(),
-  status: apiV2ScanStatusSchema,
+  status: external_exports2.union([apiV2ScanStatusSchema, external_exports2.literal("invalid_arguments")]),
   resultDisposition: scanResultDispositionSchema.optional(),
   noGo: scanNoGoResultSchema.optional(),
   scanFrom: apiV2ScanFromSchema.optional(),
+  createdAt: external_exports2.string().nullable().optional(),
   startedAt: external_exports2.string().nullable().optional(),
   completedAt: external_exports2.string().nullable().optional(),
-  scanTimeSeconds: external_exports2.number().nullable().optional()
+  scanTimeSeconds: external_exports2.number().nullable().optional(),
+  score: external_exports2.number().int().min(0).max(100).nullable().optional(),
+  scoreStatus: external_exports2.enum(["provisional", "final"]).optional(),
+  scoreVersion: external_exports2.string().nullable().optional(),
+  scoreUpdatedAt: external_exports2.string().nullable().optional(),
+  riskLevel: external_exports2.string().nullable().optional(),
+  coverage: apiV2ScanResourceSchema.shape.coverage.nullable().optional(),
+  error: mcpActionableErrorSchema.nullable(),
+  recommendedNextTool: external_exports2.enum(["certscore_get_scan_status", "certscore_get_scan_bundle"]).nullable(),
+  recommendedNextAction: external_exports2.string(),
+  observationOnlyDisclaimer: external_exports2.string()
 }).passthrough();
 var mcpScanStatusOutputSchema = external_exports2.object({
   type: external_exports2.enum(["certscore_scan_job", "certscore_pulse_status"]).optional(),
@@ -20674,13 +20890,35 @@ var mcpScanStatusOutputSchema = external_exports2.object({
   scanId: external_exports2.string().nullable().optional(),
   scan_id: external_exports2.string().nullable().optional(),
   domain: external_exports2.string().nullable().optional(),
+  url: external_exports2.string().nullable().optional(),
   status: external_exports2.union([apiV2ScanStatusSchema, pulseStatusSchema.shape.status]).optional(),
   resultDisposition: scanResultDispositionSchema.optional(),
   noGo: scanNoGoResultSchema.optional(),
   startedAt: external_exports2.string().nullable().optional(),
+  createdAt: external_exports2.string().nullable().optional(),
   completedAt: external_exports2.string().nullable().optional(),
   scanTimeSeconds: external_exports2.number().nullable().optional(),
-  error: mcpToolErrorPayloadSchema.shape.error.optional()
+  score: external_exports2.number().int().min(0).max(100).nullable().optional(),
+  scoreStatus: external_exports2.enum(["provisional", "final"]).optional(),
+  scoreVersion: external_exports2.string().nullable().optional(),
+  scoreUpdatedAt: external_exports2.string().nullable().optional(),
+  riskLevel: external_exports2.string().nullable().optional(),
+  coverage: apiV2ScanResourceSchema.shape.coverage.nullable().optional(),
+  phase: external_exports2.string().optional(),
+  phaseStartedAt: external_exports2.string().nullable().optional(),
+  lastUpdatedAt: external_exports2.string().optional(),
+  lastHeartbeatAt: external_exports2.string().nullable().optional(),
+  progressPercent: external_exports2.number().int().min(0).max(100).optional(),
+  progressIsEstimate: external_exports2.boolean().optional(),
+  estimatedRemainingSeconds: external_exports2.number().int().min(0).nullable().optional(),
+  stalled: external_exports2.boolean().optional(),
+  retryAfterSeconds: external_exports2.number().int().nullable().optional(),
+  error: mcpActionableErrorSchema.nullable(),
+  reportUrl: external_exports2.string().nullable().optional(),
+  links: apiV2ScanResourceSchema.shape.links.optional(),
+  recommendedNextTool: external_exports2.enum(["certscore_get_scan_status", "certscore_get_scan_bundle"]).nullable(),
+  recommendedNextAction: external_exports2.string(),
+  observationOnlyDisclaimer: external_exports2.string()
 }).passthrough();
 var mcpReportOutputSchema = external_exports2.object({
   type: external_exports2.enum(["certscore_pulse", "certscore_pulse_summary", "certscore_pulse_evidence"]).optional(),
@@ -20692,17 +20930,63 @@ var mcpReportOutputSchema = external_exports2.object({
 }).passthrough();
 var mcpScanBundleOutputSchema = external_exports2.object({
   type: external_exports2.literal("certscore_scan_bundle"),
+  detail: external_exports2.enum(["summary", "findings", "evidence", "full"]),
   scanId: external_exports2.string(),
+  domain: external_exports2.string(),
+  url: external_exports2.string().nullable(),
   status: apiV2ScanStatusSchema,
+  score: external_exports2.number().int().min(0).max(100).nullable(),
+  scoreStatus: external_exports2.enum(["provisional", "final"]),
+  scoreVersion: external_exports2.string().nullable(),
+  scoreUpdatedAt: external_exports2.string().nullable(),
+  riskLevel: external_exports2.string().nullable(),
   resultDisposition: scanResultDispositionSchema.nullable().optional(),
   noGo: scanNoGoResultSchema.nullable().optional(),
-  scan: apiV2ScanResourceSchema,
-  summary: external_exports2.unknown().nullable(),
-  findings: external_exports2.array(external_exports2.unknown()),
-  evidenceSummary: external_exports2.unknown().nullable(),
-  preConsentCookiesTrackers: external_exports2.unknown().nullable(),
+  coverage: apiV2ScanResourceSchema.shape.coverage.nullable(),
+  createdAt: external_exports2.string().nullable(),
+  startedAt: external_exports2.string().nullable(),
+  completedAt: external_exports2.string().nullable(),
+  scanTimeSeconds: external_exports2.number().nullable(),
+  timing: external_exports2.object({
+    createdAt: external_exports2.string().nullable(),
+    startedAt: external_exports2.string().nullable(),
+    completedAt: external_exports2.string().nullable(),
+    scanTimeSeconds: external_exports2.number().nullable()
+  }).strict(),
+  summary: external_exports2.object({
+    headline: external_exports2.string().nullable(),
+    executiveSummary: mcpExecutiveSummarySchema.nullable(),
+    counts: external_exports2.record(external_exports2.union([external_exports2.number(), external_exports2.boolean(), external_exports2.null()])).nullable(),
+    agentInterpretation: pulseAgentInterpretationSchema.nullable()
+  }).strict(),
+  findings: external_exports2.array(apiV2FindingDetailSchema),
+  findingsMetadata: external_exports2.object({
+    shown: external_exports2.number().int().min(0),
+    total: external_exports2.number().int().min(0),
+    truncated: external_exports2.boolean()
+  }).strict(),
+  evidenceSummary: external_exports2.record(external_exports2.unknown()).optional(),
+  fullReport: pulseResponseSchema.optional(),
+  preConsentCookiesTrackers: external_exports2.record(external_exports2.unknown()).optional(),
   links: external_exports2.record(external_exports2.string()).optional(),
-  recommendedNextTool: external_exports2.string().nullable(),
+  reportUrl: external_exports2.string().nullable(),
+  recommendedNextTool: external_exports2.enum(["certscore_get_scan_status", "certscore_get_scan_bundle"]).nullable(),
+  recommendedNextAction: external_exports2.string(),
+  error: mcpActionableErrorSchema.nullable(),
+  mcpMetadata: external_exports2.object({
+    detail: external_exports2.enum(["summary", "findings", "evidence", "full"]),
+    heavyEvidenceIncluded: external_exports2.boolean(),
+    findingsTruncated: external_exports2.boolean(),
+    requestedMaxBytes: external_exports2.number().int().min(5e3),
+    actualBytes: external_exports2.number().int().min(0),
+    truncated: external_exports2.boolean(),
+    truncationReason: external_exports2.string().nullable(),
+    omittedSections: external_exports2.array(external_exports2.string()),
+    nextRecommendedMaxBytes: external_exports2.number().int().min(5e3).max(2e5).nullable(),
+    omittedContentAvailableViaUrl: external_exports2.boolean(),
+    contentUrls: external_exports2.record(external_exports2.string())
+  }).strict(),
+  observationOnlyDisclaimer: external_exports2.string(),
   disclaimer: external_exports2.string().nullable()
 }).passthrough();
 var mcpFindingsExportOutputSchema = external_exports2.object({
@@ -20746,23 +21030,15 @@ var mcpPreConsentCookiesTrackersOutputSchema = apiV2PreConsentCookiesTrackersSch
 });
 var certScoreMcpToolContracts = [
   {
-    name: "create_scan",
-    title: "Deprecated \u2014 Create CertScore Pulse scan",
-    description: "Deprecated compatibility alias of scan_site. Use scan_site for new integrations. Returns completed-limited no-go disposition and reason-specific guidance when applicable.",
-    inputSchema: mcpCreateScanInputSchema,
-    outputSchema: mcpCreateScanOutputSchema,
-    annotations: scanCreationAnnotations
-  },
-  {
-    name: "scan_site",
+    name: "certscore_scan_site",
     title: "Scan site",
-    description: "Recommended first call. Starts or reuses a public-web scan, reports freshness and anonymous quota decisions, and waits up to 45 seconds by default. If still running, use get_scan_status; otherwise use get_scan_bundle. Completed no-go scans retain completed_limited status and reason-specific guidance.",
+    description: "First call. Starts or reuses a public-web scan and waits up to 45 seconds by default. If status is queued, running, or finalizing, retain scanId and poll certscore_get_scan_status using only that scanId. Stop polling at completed, completed_limited, failed, expired, or rate_limited. For usable completion, call certscore_get_scan_bundle. No-go and limited coverage are observations, never proof of compliance.",
     inputSchema: mcpScanSiteInputSchema,
     outputSchema: mcpScanSiteOutputSchema,
     annotations: scanCreationAnnotations
   },
   {
-    name: "get_scan",
+    name: "certscore_get_scan",
     title: "Get CertScore scan",
     description: "Retrieve the API v2 public-safe scan resource, including completed-limited no-go disposition, reason-specific guidance, and timing when available.",
     inputSchema: mcpGetScanInputSchema,
@@ -20770,23 +21046,23 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_scan_status",
-    title: "Get CertScore Pulse scan status",
-    description: "Retrieve terminal status, including completed_limited no-go disposition and reason-specific guidance. Pass jobId only before a stable scanId is available.",
+    name: "certscore_get_scan_status",
+    title: "Get scan status",
+    description: "Poll with only the stable scanId returned by certscore_scan_site. Active responses include phase, heartbeat, estimated progress, stalled state, and retry delay. Terminal responses include the canonical score, risk, coverage, timestamps, report URL, and an explicit next action. Stop polling at any terminal status.",
     inputSchema: mcpGetScanStatusInputSchema,
     outputSchema: mcpScanStatusOutputSchema,
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_report",
+    name: "certscore_get_report",
     title: "Get CertScore Pulse report",
-    description: "Retrieve a summary Pulse report, including customer-safe no-go messaging when coverage is completed-limited. Use get_evidence for the larger bounded packet.",
+    description: "Retrieve a summary Pulse report, including customer-safe no-go messaging when coverage is completed-limited. Use certscore_get_evidence for the larger bounded packet.",
     inputSchema: mcpGetReportInputSchema,
     outputSchema: mcpReportOutputSchema,
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_evidence",
+    name: "certscore_get_evidence",
     title: "Get CertScore Pulse evidence",
     description: "Retrieve the bounded structured Evidence JSON packet for a stable scan ID. Excludes raw cookie values, raw bodies, sensitive payloads, full DOM, and unredacted query values.",
     inputSchema: mcpGetEvidenceInputSchema,
@@ -20794,15 +21070,15 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_scan_bundle",
-    title: "Get compact CertScore scan bundle",
-    description: "Recommended second call after scan_site. Returns the canonical scan state, compact report summary, findings, bounded evidence summary, and pre-consent inventory in one agent-friendly response.",
+    name: "certscore_get_scan_bundle",
+    title: "Get scan bundle",
+    description: "Call after completed or completed_limited status. summary returns the canonical overview without finding bodies; findings reserves space for compact findings; evidence reserves findings plus bounded evidence digests and references; full adds all available bounded sections. Every response declares detail and byte-budget metadata, omittedSections, retrieval URLs, and nextRecommendedMaxBytes when truncated. Never interpret no-go, not-observed, or limited coverage as proof of compliance.",
     inputSchema: mcpGetScanBundleInputSchema,
     outputSchema: mcpScanBundleOutputSchema,
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "export_findings",
+    name: "certscore_export_findings",
     title: "Export CertScore findings",
     description: "Return structured findings plus completed-limited no-go disposition and guidance for downstream review or ticketing workflows.",
     inputSchema: mcpExportFindingsInputSchema,
@@ -20810,7 +21086,7 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "list_findings",
+    name: "certscore_list_findings",
     title: "List CertScore findings",
     description: "List API v2 public-safe findings already projected for a scan.",
     inputSchema: mcpListFindingsInputSchema,
@@ -20818,7 +21094,7 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_pre_consent_cookies_trackers",
+    name: "certscore_get_pre_consent_cookies_trackers",
     title: "Get pre-consent cookies and trackers",
     description: "Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.",
     inputSchema: mcpGetPreConsentCookiesTrackersInputSchema,
@@ -20826,7 +21102,7 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "explain_finding",
+    name: "certscore_explain_finding",
     title: "Explain CertScore finding",
     description: "Explain one projected finding with public evidence, caveats, reviewer next steps, and reason-specific no-go context when applicable.",
     inputSchema: mcpExplainFindingInputSchema,
@@ -20834,7 +21110,7 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_latest_domain_scan",
+    name: "certscore_get_latest_domain_scan",
     title: "Get latest domain scan",
     description: "Retrieve the latest eligible API v2 public-safe scan for a domain.",
     inputSchema: mcpGetLatestDomainScanInputSchema,
@@ -20842,7 +21118,7 @@ var certScoreMcpToolContracts = [
     annotations: readOnlyOpenWorldAnnotations
   },
   {
-    name: "get_latest_domain_pre_consent_cookies_trackers",
+    name: "certscore_get_latest_domain_pre_consent_cookies_trackers",
     title: "Get latest domain pre-consent cookies and trackers",
     description: "Retrieve the public-safe Cookies & Trackers (Pre-consent) table from the latest eligible scan for a domain.",
     inputSchema: mcpGetLatestDomainPreConsentCookiesTrackersInputSchema,
@@ -20852,10 +21128,17 @@ var certScoreMcpToolContracts = [
 ];
 
 // ../certscore-api-contracts/src/openapi-v2.ts
+var diagnosticHeaders = {
+  "x-certscore-api-version": { schema: { type: "string", const: "v2" }, description: "CertScore API version marker." },
+  "x-certscore-request-id": { schema: { type: "string" }, description: "Request identifier for support and diagnostics." }
+};
+var retryAfterHeader = {
+  "Retry-After": { schema: { type: "integer" }, description: "Recommended retry or polling delay in seconds." }
+};
 var preConsentCookiesTrackersExample = {
   type: "certscore_pre_consent_cookies_trackers",
   scanId: "00000000-0000-4000-8000-000000000123",
-  domain: "example.com",
+  domain: "ergoveritas.com",
   generatedAt: "2026-06-30T12:00:10.000Z",
   summary: {
     rowCount: 2,
@@ -20881,7 +21164,7 @@ var preConsentCookiesTrackersExample = {
       observedBeforeConsent: true,
       evidenceBasis: "public_report_projection",
       firstObservedAtMs: 1234,
-      pageUrlHost: "example.com"
+      pageUrlHost: "ergoveritas.com"
     },
     {
       id: "cookie:google:advertising:doubleclick-net",
@@ -20900,7 +21183,7 @@ var preConsentCookiesTrackersExample = {
       observedBeforeConsent: true,
       evidenceBasis: "public_report_projection",
       firstObservedAtMs: 512,
-      pageUrlHost: "example.com"
+      pageUrlHost: "ergoveritas.com"
     }
   ],
   links: {
@@ -20917,6 +21200,56 @@ var emptyPreConsentCookiesTrackersExample = {
   summary: { rowCount: 0, trackerCount: 0, cookieCount: 0, requestCount: 0 },
   rows: []
 };
+var errorContent = {
+  "application/json": {
+    schema: { $ref: "#/components/schemas/ApiError" },
+    examples: {
+      invalidRequest: {
+        summary: "Invalid request",
+        value: { type: "certscore_api_error", error: { code: "invalid_request", message: "Invalid request.", retryable: false, retryAfterSeconds: null, recommendedNextAction: "Correct the request before retrying." }, disclaimer: apiV2Disclaimer }
+      },
+      unauthorized: {
+        summary: "Missing or invalid API key",
+        value: { type: "certscore_api_error", error: { code: "unauthorized", message: "Missing or invalid API key.", retryable: false, retryAfterSeconds: null, recommendedNextAction: "Stop and review authentication before retrying." }, disclaimer: apiV2Disclaimer }
+      },
+      forbidden: {
+        summary: "Missing required scope",
+        value: { type: "certscore_api_error", error: { code: "forbidden", message: "API key is missing the required scope.", retryable: false, retryAfterSeconds: null, recommendedNextAction: "Stop and request the required scope before retrying." }, disclaimer: apiV2Disclaimer }
+      },
+      notFound: {
+        summary: "Resource not found",
+        value: { type: "certscore_api_error", error: { code: "not_found", message: "Scan not found.", retryable: false, retryAfterSeconds: null, recommendedNextAction: "Stop and verify the scan ID." }, disclaimer: apiV2Disclaimer }
+      },
+      rateLimited: {
+        summary: "Rate limited",
+        value: {
+          type: "certscore_api_error",
+          error: {
+            code: "rate_limited",
+            message: "Completed scan resource read limit exceeded. Retry after 60 seconds.",
+            retryable: true,
+            retryAfterSeconds: 60,
+            recommendedNextAction: "Wait for Retry-After, then make one bounded retrieval. Do not poll terminal scan resources."
+          },
+          disclaimer: apiV2Disclaimer
+        }
+      },
+      internalError: {
+        summary: "Temporary service error",
+        value: {
+          type: "certscore_api_error",
+          error: { code: "internal_error", message: "CertScore API v2 is temporarily unavailable. Try again later.", retryable: true, retryAfterSeconds: 30, recommendedNextAction: "Retry after 30 seconds. If the error repeats, stop and contact CertScore support." },
+          disclaimer: apiV2Disclaimer
+        }
+      }
+    }
+  }
+};
+var readRateLimitedResponse = {
+  description: "Weighted scan-resource read limit reached. Honor Retry-After before retrying and do not poll terminal scan resources.",
+  headers: { ...diagnosticHeaders, ...retryAfterHeader },
+  content: errorContent
+};
 
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/zod/v3/helpers/util.js
 var util2;
@@ -24922,17 +25255,33 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
+function getDotPath(path) {
+  if (path.length === 0) {
+    return "object root";
+  }
+  return path.reduce((acc, seg, index) => {
+    if (index === 0) {
+      return String(seg);
+    }
+    if (typeof seg === "number") {
+      return `${acc}[${seg}]`;
+    }
+    return `${acc}.${seg}`;
+  }, "");
+}
 function getParseErrorMessage(error2) {
   if (error2 && typeof error2 === "object") {
+    if ("issues" in error2 && Array.isArray(error2.issues) && error2.issues.length > 0) {
+      return error2.issues.map((i) => {
+        if (!i.path?.length) {
+          return i.message;
+        }
+        return `${i.message} at ${getDotPath(i.path)}`;
+      }).join("\n");
+    }
     if ("message" in error2 && typeof error2.message === "string") {
       return error2.message;
     }
-    if ("issues" in error2 && Array.isArray(error2.issues) && error2.issues.length > 0) {
-      const firstIssue = error2.issues[0];
-      if (firstIssue && typeof firstIssue === "object" && "message" in firstIssue) {
-        return String(firstIssue.message);
-      }
-    }
     try {
       return JSON.stringify(error2);
     } catch {
@@ -31525,16 +31874,7 @@ var Server = class extends Protocol {
     if (!methodSchema) {
       throw new Error("Schema is missing a method literal");
     }
-    let methodValue;
-    if (isZ4Schema(methodSchema)) {
-      const v4Schema = methodSchema;
-      const v4Def = v4Schema._zod?.def;
-      methodValue = v4Def?.value ?? v4Schema.value;
-    } else {
-      const v3Schema = methodSchema;
-      const legacyDef = v3Schema._def;
-      methodValue = legacyDef?.value ?? v3Schema.value;
-    }
+    const methodValue = getLiteralValue(methodSchema);
     if (typeof methodValue !== "string") {
       throw new Error("Schema method literal must be a string");
     }
@@ -32731,6 +33071,18 @@ var MAX_EVIDENCE_PACKET_CHARS = 25e4;
 var EVIDENCE_STRING_CHARS = 4e3;
 var EVIDENCE_ARRAY_ITEMS = 40;
 var EVIDENCE_OBJECT_KEYS = 80;
+var OBSERVATION_ONLY_DISCLAIMER = "Observation only: no-go, not-observed, and limited-coverage results are not proof of compliance.";
+function toolResultSummary(payload) {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    return "CertScore tool call completed. Read structuredContent for the result.";
+  }
+  const record2 = payload;
+  const type = typeof record2.type === "string" ? record2.type : "result";
+  const status = typeof record2.status === "string" ? `; status=${record2.status}` : "";
+  const scanId = typeof record2.scanId === "string" ? `; scanId=${record2.scanId}` : "";
+  const score = typeof record2.score === "number" ? `; score=${record2.score}` : "";
+  return `CertScore ${type}${status}${scanId}${score}. Full result is in structuredContent.`;
+}
 function toToolResult(payload) {
   const structuredContent = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : { value: payload };
   return {
@@ -32738,25 +33090,32 @@ function toToolResult(payload) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(payload)
+        text: toolResultSummary(payload)
       }
     ]
   };
 }
 function toToolError(error2) {
-  const payload = error2 instanceof CertScoreError ? {
+  const responseRecord = error2 instanceof CertScoreError && error2.responseBody && typeof error2.responseBody === "object" && !Array.isArray(error2.responseBody) ? error2.responseBody : null;
+  const terminalError = responseRecord?.error && typeof responseRecord.error === "object" && !Array.isArray(responseRecord.error) ? responseRecord.error : null;
+  const status = error2 instanceof CertScoreError ? error2.status : void 0;
+  const retryable = typeof terminalError?.retryable === "boolean" ? terminalError.retryable : status === 429 || typeof status === "number" && status >= 500;
+  const retryAfterSeconds = typeof terminalError?.retryAfterSeconds === "number" ? terminalError.retryAfterSeconds : error2 instanceof CertScoreError && "retryAfterSeconds" in error2 && typeof error2.retryAfterSeconds === "number" ? error2.retryAfterSeconds : retryable ? 30 : null;
+  const code = error2 instanceof CertScoreError ? error2.code : "internal_error";
+  const message = error2 instanceof Error ? error2.message : "Unknown CertScore MCP error.";
+  const recommendedNextAction = typeof terminalError?.recommendedNextAction === "string" ? terminalError.recommendedNextAction : retryable ? `Wait ${retryAfterSeconds ?? 30} seconds, then retry the same request. Stop and contact CertScore support if the error repeats.` : "Correct the request using the error details, then retry only if the requested operation is still appropriate.";
+  const payload = {
     error: {
-      name: error2.name,
-      message: error2.message,
-      status: error2.status,
-      code: error2.code,
-      retryAfterSeconds: "retryAfterSeconds" in error2 ? error2.retryAfterSeconds : void 0,
-      responseBody: truncateErrorResponseBody(error2.responseBody)
-    }
-  } : {
-    error: {
-      name: error2 instanceof Error ? error2.name : "Error",
-      message: error2 instanceof Error ? error2.message : "Unknown CertScore MCP error."
+      code,
+      message,
+      retryable,
+      retryAfterSeconds,
+      recommendedNextAction,
+      ...error2 instanceof CertScoreError ? {
+        name: error2.name,
+        status: error2.status,
+        responseBody: truncateErrorResponseBody(error2.responseBody)
+      } : {}
     }
   };
   return {
@@ -32764,6 +33123,95 @@ function toToolError(error2) {
     isError: true
   };
 }
+function toInvalidArgumentsToolError(errorMessage) {
+  const tool = errorMessage.match(/tool ([a-z_]+)/i)?.[1] ?? null;
+  const field = errorMessage.match(/\bat ([a-zA-Z0-9_.-]+)/)?.[1] ?? (errorMessage.includes("url") ? "url" : errorMessage.includes("scanId") ? "scanId" : null);
+  const missing = /required|expected string, received undefined/i.test(errorMessage);
+  const message = field ? missing ? `The ${field} field is required.` : `The ${field} field is invalid.` : `The arguments for ${tool ?? "this tool"} are invalid.`;
+  const recommendedNextAction = field === "url" ? "Provide a public URL or domain." : field === "scanId" ? "Provide the stable scanId returned by certscore_scan_site." : "Correct the named fields using the tool input schema, then retry.";
+  const error2 = {
+    code: "invalid_arguments",
+    message,
+    ...field ? { field } : {},
+    retryable: false,
+    retryAfterSeconds: null,
+    recommendedNextAction,
+    mcpCode: -32602
+  };
+  const payload = tool === "certscore_scan_site" ? {
+    type: "certscore_tool_error",
+    status: "invalid_arguments",
+    error: error2,
+    recommendedNextTool: null,
+    recommendedNextAction,
+    observationOnlyDisclaimer: OBSERVATION_ONLY_DISCLAIMER
+  } : { error: error2 };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    ...tool === "certscore_scan_site" ? { structuredContent: payload } : {},
+    isError: true
+  };
+}
+function terminalErrorForResult(value) {
+  const existing = value.error && typeof value.error === "object" && !Array.isArray(value.error) ? value.error : null;
+  if (existing) {
+    const retryable = existing.retryable === true;
+    return {
+      code: typeof existing.code === "string" ? existing.code : String(value.status ?? "scan_failed"),
+      message: typeof existing.message === "string" ? existing.message : "The scan did not produce a canonical result.",
+      retryable,
+      retryAfterSeconds: typeof existing.retryAfterSeconds === "number" ? existing.retryAfterSeconds : retryable ? 30 : null,
+      recommendedNextAction: typeof existing.recommendedNextAction === "string" ? existing.recommendedNextAction : retryable ? "Wait for the recommended delay, then retry certscore_scan_site with freshness=refresh." : "Stop and review the scan limitations before deciding whether to change the URL."
+    };
+  }
+  if (value.status === "completed_limited" && value.noGo) {
+    const retryable = value.noGo.retryLikelyToHelp === true;
+    return {
+      code: typeof value.noGo.reasonCode === "string" ? value.noGo.reasonCode : "completed_limited",
+      message: typeof value.noGo.explanation === "string" ? value.noGo.explanation : "The scan completed with a no-go limitation.",
+      retryable,
+      retryAfterSeconds: retryable ? 30 : null,
+      recommendedNextAction: typeof value.noGo.recommendedNextAction === "string" ? value.noGo.recommendedNextAction : "Review the retained limitation and change the URL or site state before retrying."
+    };
+  }
+  const fallback = {
+    failed: {
+      code: "scanner_runtime_failure",
+      message: "The scan ended before a canonical result could be produced.",
+      retryable: true,
+      retryAfterSeconds: 30,
+      recommendedNextAction: "Wait 30 seconds, then retry certscore_scan_site with freshness=refresh. Stop if the failure repeats."
+    },
+    expired: {
+      code: "scan_expired",
+      message: "The scan expired before a canonical result was available.",
+      retryable: true,
+      retryAfterSeconds: 30,
+      recommendedNextAction: "Wait 30 seconds, then retry certscore_scan_site with freshness=refresh."
+    },
+    rate_limited: {
+      code: "rate_limited",
+      message: "The scan is rate limited.",
+      retryable: true,
+      retryAfterSeconds: typeof value.retryAfterSeconds === "number" ? value.retryAfterSeconds : 30,
+      recommendedNextAction: "Wait for the recommended delay, then retry the same certscore_scan_site request."
+    }
+  };
+  return fallback[String(value.status)] ?? null;
+}
+function withMcpAgentGuidance(value) {
+  const status = String(value.status ?? "");
+  const active = status === "queued" || status === "running" || status === "finalizing";
+  const usable = status === "completed" || status === "completed_limited";
+  const error2 = terminalErrorForResult(value);
+  return {
+    ...value,
+    error: error2,
+    recommendedNextTool: active ? "certscore_get_scan_status" : usable ? "certscore_get_scan_bundle" : null,
+    recommendedNextAction: error2?.recommendedNextAction ?? value.recommendedNextAction ?? (active ? `Poll certscore_get_scan_status with scanId ${value.scanId ?? value.jobId} after the recommended delay.` : usable ? `Call certscore_get_scan_bundle with scanId ${value.scanId ?? value.jobId} for the canonical findings and limitations.` : "Review the result and retained limitations."),
+    observationOnlyDisclaimer: OBSERVATION_ONLY_DISCLAIMER
+  };
+}
 function boundEvidencePacket(payload, maxSerializedChars = MAX_EVIDENCE_PACKET_CHARS) {
   const originalSerializedChars = measureSerializedChars(payload);
   if (originalSerializedChars <= maxSerializedChars) {
@@ -32807,6 +33255,107 @@ function boundEvidencePacket(payload, maxSerializedChars = MAX_EVIDENCE_PACKET_C
 function measureSerializedChars(value) {
   return JSON.stringify(value)?.length ?? 0;
 }
+function measureSerializedBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function updateBundleActualBytes(bundle) {
+  bundle.mcpMetadata.actualBytes = 0;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const measured = measureSerializedBytes(bundle);
+    if (bundle.mcpMetadata.actualBytes === measured) {
+      break;
+    }
+    bundle.mcpMetadata.actualBytes = measured;
+  }
+  return bundle.mcpMetadata.actualBytes;
+}
+function boundedText(value, maxChars) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return value.length > maxChars ? `${value.slice(0, maxChars)}\u2026[truncated]` : value;
+}
+function compactBundleFinding(finding) {
+  const evidence = finding.evidence && typeof finding.evidence === "object" && !Array.isArray(finding.evidence) ? finding.evidence : {};
+  return {
+    type: finding.type,
+    id: finding.id,
+    scanId: finding.scanId,
+    label: boundedText(finding.label, 140),
+    criticality: finding.criticality,
+    confidence: finding.confidence,
+    plainEnglish: boundedText(finding.plainEnglish, 280),
+    ...finding.resultDisposition ? { resultDisposition: finding.resultDisposition } : {},
+    ...finding.noGo ? { noGo: finding.noGo } : {},
+    reviewLenses: Array.isArray(finding.reviewLenses) ? finding.reviewLenses.slice(0, 2) : [],
+    evidence: {
+      basis: evidence.basis,
+      summary: boundedText(evidence.summary, 220),
+      ...evidence.phase !== void 0 ? { phase: evidence.phase } : {},
+      exampleCount: evidence.exampleCount,
+      examplesShown: evidence.examplesShown,
+      ...evidence.hasTimingAnchor !== void 0 ? { hasTimingAnchor: evidence.hasTimingAnchor } : {},
+      ...evidence.hasVendorAnchor !== void 0 ? { hasVendorAnchor: evidence.hasVendorAnchor } : {},
+      ...evidence.hasConsentContext !== void 0 ? { hasConsentContext: evidence.hasConsentContext } : {},
+      ...evidence.hasPolicyAnchor !== void 0 ? { hasPolicyAnchor: evidence.hasPolicyAnchor } : {}
+    },
+    ...finding.nextStep !== void 0 ? { nextStep: boundedText(finding.nextStep, 180) } : {}
+  };
+}
+function compactPriorityEvidenceSummary(summary) {
+  const firstDigest = Array.isArray(summary.digests) ? summary.digests[0] : null;
+  const firstReference = summary.references && typeof summary.references === "object" && !Array.isArray(summary.references) ? Object.entries(summary.references).find(([, value]) => typeof value === "string") : null;
+  return {
+    digests: firstDigest ? [{
+      findingId: firstDigest.findingId,
+      basis: firstDigest.basis ?? null,
+      summary: boundedText(firstDigest.summary, 180) ?? null,
+      phase: firstDigest.phase ?? null,
+      evidenceUrl: firstDigest.evidenceUrl ?? firstReference?.[1] ?? null
+    }] : [],
+    evidenceAvailable: summary.evidenceAvailable === true,
+    evidenceSafetyNotes: [],
+    references: firstDigest ? {} : firstReference ? { [firstReference[0]]: firstReference[1] } : {}
+  };
+}
+function bundleEvidenceSummary(evidence, findings, links, includeDiagnostics) {
+  const digests = findings.slice(0, 3).map((finding) => {
+    const findingEvidence = finding.evidence && typeof finding.evidence === "object" && !Array.isArray(finding.evidence) ? finding.evidence : {};
+    return {
+      findingId: finding.id,
+      basis: findingEvidence.basis ?? null,
+      summary: boundedText(findingEvidence.summary, 500) ?? null,
+      phase: findingEvidence.phase ?? null,
+      evidenceUrl: findingEvidence.excerpt && typeof findingEvidence.excerpt === "object" && !Array.isArray(findingEvidence.excerpt) ? findingEvidence.excerpt.evidenceUrl ?? null : typeof links.findings === "string" ? links.findings : typeof links.report === "string" ? links.report : null
+    };
+  });
+  return {
+    digests,
+    evidenceAvailable: digests.length > 0 || Object.keys(evidence).length > 0,
+    evidenceSafetyNotes: Array.isArray(evidence.evidenceSafetyNotes) ? evidence.evidenceSafetyNotes.slice(0, 3).map((note) => boundedText(note, 300)) : [],
+    references: Object.fromEntries(Object.entries(links).filter(([key, value]) => ["findings", "pulse", "report", "preConsentCookiesTrackers"].includes(key) && typeof value === "string")),
+    ...includeDiagnostics ? {
+      projectionDiagnostics: compactEvidenceValue(evidence.projectionDiagnostics ?? null, {
+        arrayItems: 12,
+        depth: 4,
+        objectKeys: 24,
+        stringChars: 600
+      }),
+      coverageDiagnostics: compactEvidenceValue(evidence.coverageDiagnostics ?? null, {
+        arrayItems: 12,
+        depth: 4,
+        objectKeys: 24,
+        stringChars: 600
+      }),
+      policySurfaceCoverage: compactEvidenceValue(evidence.policySurfaceCoverage ?? null, {
+        arrayItems: 12,
+        depth: 4,
+        objectKeys: 24,
+        stringChars: 600
+      })
+    } : {}
+  };
+}
 function compactEvidenceValue(value, options) {
   if (value === null || value === void 0) {
     return value;
@@ -32935,9 +33484,6 @@ function normalizeDetail2(detail) {
 function normalizeFormat2(format) {
   return format ?? "json";
 }
-function scanIdFromStatus(status) {
-  return status.scanId ?? status.scan_id ?? null;
-}
 function scanIdFromPulse(report) {
   const nestedScan = "scan" in report && report.scan && typeof report.scan === "object" ? report.scan : void 0;
   return report.scanId ?? report.scan_id ?? nestedScan?.scanId ?? null;
@@ -33014,69 +33560,261 @@ function limitPreConsentRows(payload, options = {}) {
   };
 }
 function buildScanBundle(input) {
-  const maxFindings = Math.min(50, Math.max(1, input.maxFindings ?? 20));
+  const detail = input.detail ?? "summary";
+  const maxFindings = Math.min(50, Math.max(1, input.maxFindings ?? (detail === "summary" ? 5 : 20)));
   const maxPreConsentRows = Math.min(50, Math.max(1, input.maxPreConsentRows ?? 20));
-  const evidence = input.evidence;
-  const report = input.report;
-  const findings = Array.isArray(input.findings.findings) ? input.findings.findings.slice(0, maxFindings) : [];
-  const preConsentRows = Array.isArray(input.preConsentCookiesTrackers.rows) ? input.preConsentCookiesTrackers.rows.slice(0, maxPreConsentRows) : [];
+  const evidence = input.evidence ?? {};
+  const report = input.report ?? {};
+  const allFindings = Array.isArray(input.findings.findings) ? input.findings.findings : [];
+  const findings = detail === "summary" ? [] : allFindings.slice(0, maxFindings).map((finding) => detail === "full" ? finding : compactBundleFinding(finding));
+  const preConsentRows = Array.isArray(input.preConsentCookiesTrackers?.rows) ? input.preConsentCookiesTrackers.rows.slice(0, maxPreConsentRows) : [];
   const links = {
     ...input.scan.links ?? {},
     ...report.links && typeof report.links === "object" && !Array.isArray(report.links) ? report.links : {}
   };
-  return {
+  const maxBytes = Math.min(2e5, Math.max(5e3, input.maxBytes ?? 5e4));
+  const contentUrls = Object.fromEntries(Object.entries({
+    report: input.scan.links?.report ?? links.report,
+    findings: links.findings,
+    evidence: links.pulse,
+    preConsentCookiesTrackers: links.preConsentCookiesTrackers
+  }).filter(([, value]) => typeof value === "string"));
+  const intentionallyOmitted = /* @__PURE__ */ new Set();
+  if (detail === "summary" && allFindings.length > 0) intentionallyOmitted.add("findings");
+  if ((detail === "summary" || detail === "findings") && (Object.keys(evidence).length > 0 || allFindings.length > 0)) intentionallyOmitted.add("evidence");
+  if (detail !== "full" && Object.keys(report).length > 0) intentionallyOmitted.add("fullReport");
+  const guidedScan = withMcpAgentGuidance(input.scan);
+  const bundle = {
     type: "certscore_scan_bundle",
+    detail,
     scanId: input.scan.scanId,
+    domain: input.scan.domain,
+    url: input.scan.url ?? null,
     status: input.scan.status,
+    score: input.scan.score ?? null,
+    scoreStatus: input.scan.scoreStatus ?? "final",
+    scoreVersion: input.scan.scoreVersion ?? null,
+    scoreUpdatedAt: input.scan.scoreUpdatedAt ?? null,
+    riskLevel: input.scan.riskLevel ?? null,
     resultDisposition: input.scan.resultDisposition ?? null,
     noGo: input.scan.noGo ?? null,
-    scan: input.scan,
+    coverage: input.scan.coverage ?? null,
+    createdAt: input.scan.createdAt ?? null,
+    startedAt: input.scan.startedAt ?? null,
+    completedAt: input.scan.completedAt ?? null,
+    scanTimeSeconds: input.scan.scanTimeSeconds ?? null,
+    timing: {
+      createdAt: input.scan.createdAt ?? null,
+      startedAt: input.scan.startedAt ?? null,
+      completedAt: input.scan.completedAt ?? null,
+      scanTimeSeconds: input.scan.scanTimeSeconds ?? null
+    },
     summary: {
-      summary: report.summary ?? null,
+      headline: report.summary && typeof report.summary === "object" && !Array.isArray(report.summary) ? report.summary.headline ?? null : null,
       executiveSummary: report.executiveSummary ?? null,
       counts: report.counts ?? null,
-      coverage: report.coverage ?? input.scan.coverage ?? null,
       agentInterpretation: report.agentInterpretation ?? null
     },
     findings,
     findingsMetadata: {
       shown: findings.length,
-      total: Array.isArray(input.findings.findings) ? input.findings.findings.length : 0,
-      truncated: Array.isArray(input.findings.findings) && input.findings.findings.length > findings.length
+      total: allFindings.length,
+      truncated: allFindings.length > findings.length
     },
-    evidenceSummary: {
-      evidenceSafetyNotes: evidence.evidenceSafetyNotes ?? null,
-      projectionDiagnostics: evidence.projectionDiagnostics ?? null,
-      projectedFindings: compactEvidenceValue(evidence.projectedFindings ?? [], {
-        arrayItems: maxFindings,
-        depth: 5,
-        objectKeys: 40,
-        stringChars: 1e3
-      }),
-      coverageDiagnostics: compactEvidenceValue(evidence.coverageDiagnostics ?? null, {
-        arrayItems: 20,
-        depth: 5,
-        objectKeys: 40,
-        stringChars: 1e3
-      }),
-      policySurfaceCoverage: compactEvidenceValue(evidence.policySurfaceCoverage ?? null, {
-        arrayItems: 20,
-        depth: 5,
-        objectKeys: 40,
-        stringChars: 1e3
+    ...detail === "evidence" || detail === "full" ? { evidenceSummary: bundleEvidenceSummary(evidence, allFindings, links, detail === "full") } : {},
+    ...detail === "full" ? {
+      fullReport: compactEvidenceValue(report, {
+        arrayItems: 50,
+        depth: 8,
+        objectKeys: 100,
+        stringChars: 4e3
       })
-    },
-    preConsentCookiesTrackers: {
+    } : {},
+    ...input.preConsentCookiesTrackers ? { preConsentCookiesTrackers: {
       summary: input.preConsentCookiesTrackers.summary,
       rows: preConsentRows,
       shown: preConsentRows.length,
       total: Array.isArray(input.preConsentCookiesTrackers.rows) ? input.preConsentCookiesTrackers.rows.length : 0,
       truncated: Array.isArray(input.preConsentCookiesTrackers.rows) && input.preConsentCookiesTrackers.rows.length > preConsentRows.length
-    },
+    } } : {},
     links,
-    recommendedNextTool: findings.length > 0 ? "explain_finding" : null,
-    disclaimer: input.scan.disclaimer ?? input.report.disclaimer ?? null
+    reportUrl: input.scan.links?.report ?? (typeof links.report === "string" ? links.report : null),
+    recommendedNextTool: null,
+    recommendedNextAction: guidedScan.error?.recommendedNextAction ?? (detail === "summary" && allFindings.length > 0 ? "Review this overview, then request detail=findings for bounded finding objects or open the report URL." : findings.length > 0 ? "Review the returned findings and follow their evidence references. Use detail=evidence only when deeper retained context is needed." : "Review coverage and limitations before interpreting the absence of findings."),
+    error: guidedScan.error,
+    mcpMetadata: {
+      detail,
+      heavyEvidenceIncluded: detail === "evidence" || detail === "full",
+      findingsTruncated: allFindings.length > findings.length,
+      requestedMaxBytes: maxBytes,
+      actualBytes: 0,
+      truncated: false,
+      truncationReason: null,
+      omittedSections: [...intentionallyOmitted],
+      nextRecommendedMaxBytes: null,
+      omittedContentAvailableViaUrl: intentionallyOmitted.size > 0 && Object.keys(contentUrls).length > 0,
+      contentUrls
+    },
+    observationOnlyDisclaimer: OBSERVATION_ONLY_DISCLAIMER,
+    disclaimer: input.scan.disclaimer ?? input.report?.disclaimer ?? OBSERVATION_ONLY_DISCLAIMER
+  };
+  const recommendationCandidates = [];
+  const markBudgetOmitted = (section, reason, requiredBytes = bundle.mcpMetadata.actualBytes) => {
+    bundle.mcpMetadata.truncated = true;
+    bundle.mcpMetadata.truncationReason ??= reason;
+    if (!bundle.mcpMetadata.omittedSections.includes(section)) {
+      bundle.mcpMetadata.omittedSections.push(section);
+    }
+    recommendationCandidates.push(requiredBytes);
+    bundle.mcpMetadata.omittedContentAvailableViaUrl = Object.keys(contentUrls).length > 0;
   };
+  const refresh = () => updateBundleActualBytes(bundle);
+  refresh();
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.fullReport) {
+    markBudgetOmitted("fullReport", "full_report_omitted_to_byte_limit");
+    delete bundle.fullReport;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && detail === "full" && bundle.evidenceSummary) {
+    const compactSummary = bundleEvidenceSummary(evidence, allFindings, links, false);
+    markBudgetOmitted("evidenceDiagnostics", "evidence_diagnostics_omitted_to_byte_limit");
+    bundle.evidenceSummary = compactSummary;
+    refresh();
+  }
+  const inventoryRows = bundle.preConsentCookiesTrackers?.rows;
+  while (bundle.mcpMetadata.actualBytes > maxBytes && Array.isArray(inventoryRows) && inventoryRows.length > 0) {
+    markBudgetOmitted("preConsentCookiesTrackers", "evidence_inventory_reduced_to_byte_limit");
+    inventoryRows.pop();
+    bundle.preConsentCookiesTrackers.shown = inventoryRows.length;
+    bundle.preConsentCookiesTrackers.truncated = true;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.preConsentCookiesTrackers) {
+    markBudgetOmitted("preConsentCookiesTrackers", "evidence_inventory_omitted_to_byte_limit");
+    delete bundle.preConsentCookiesTrackers;
+    refresh();
+  }
+  while (bundle.mcpMetadata.actualBytes > maxBytes && bundle.findings.length > 1) {
+    markBudgetOmitted("additionalFindings", "findings_reduced_to_byte_limit");
+    bundle.findings.pop();
+    bundle.findingsMetadata.shown = bundle.findings.length;
+    bundle.findingsMetadata.truncated = true;
+    bundle.mcpMetadata.findingsTruncated = true;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes) {
+    markBudgetOmitted("summaryDetail", "summary_compacted_to_byte_limit");
+    bundle.summary = {
+      headline: boundedText(bundle.summary?.headline, 240) ?? null,
+      executiveSummary: null,
+      counts: bundle.summary?.counts ? { totalAutomatedFindingCount: bundle.findingsMetadata.total } : null,
+      agentInterpretation: null
+    };
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes) {
+    markBudgetOmitted("coverageDetail", "coverage_compacted_to_byte_limit");
+    bundle.coverage = compactEvidenceValue(bundle.coverage, {
+      arrayItems: 3,
+      depth: 3,
+      objectKeys: 8,
+      stringChars: 240
+    });
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.links) {
+    markBudgetOmitted("additionalLinks", "links_compacted_to_byte_limit");
+    bundle.links = Object.fromEntries(Object.entries(bundle.links).filter(([key]) => ["self", "report"].includes(key)));
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.evidenceSummary) {
+    markBudgetOmitted("evidenceDetail", "evidence_compacted_to_preserve_priority_content");
+    bundle.evidenceSummary = compactPriorityEvidenceSummary(bundle.evidenceSummary);
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.disclaimer === OBSERVATION_ONLY_DISCLAIMER) {
+    markBudgetOmitted("duplicateDisclaimer", "duplicate_disclaimer_omitted_to_byte_limit");
+    bundle.disclaimer = null;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.findings.length > 0) {
+    markBudgetOmitted("findings", "finding_omitted_to_byte_limit");
+    bundle.findings = [];
+    bundle.findingsMetadata.shown = 0;
+    bundle.findingsMetadata.truncated = bundle.findingsMetadata.total > 0;
+    bundle.mcpMetadata.findingsTruncated = bundle.findingsMetadata.total > 0;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.evidenceSummary) {
+    markBudgetOmitted("evidence", "evidence_digest_omitted_to_byte_limit");
+    delete bundle.evidenceSummary;
+    bundle.mcpMetadata.heavyEvidenceIncluded = false;
+    refresh();
+  }
+  if (bundle.mcpMetadata.truncated) {
+    const required2 = Math.min(...recommendationCandidates.filter((value) => Number.isFinite(value) && value > maxBytes));
+    bundle.mcpMetadata.nextRecommendedMaxBytes = Math.min(2e5, Math.max(maxBytes + 1e3, Math.ceil((Number.isFinite(required2) ? required2 : maxBytes + 1e3) / 1e3) * 1e3));
+    bundle.recommendedNextAction = `Retry with maxBytes=${bundle.mcpMetadata.nextRecommendedMaxBytes} or open ${bundle.reportUrl ? "the report URL" : "an available content URL"}.`;
+    refresh();
+  }
+  if (bundle.mcpMetadata.actualBytes > maxBytes) {
+    const minimal = {
+      type: bundle.type,
+      detail: bundle.detail,
+      scanId: bundle.scanId,
+      domain: bundle.domain,
+      url: bundle.url,
+      status: bundle.status,
+      score: bundle.score,
+      scoreStatus: bundle.scoreStatus,
+      scoreVersion: bundle.scoreVersion,
+      scoreUpdatedAt: bundle.scoreUpdatedAt,
+      riskLevel: bundle.riskLevel,
+      resultDisposition: bundle.resultDisposition,
+      noGo: bundle.noGo,
+      coverage: null,
+      createdAt: bundle.createdAt,
+      startedAt: bundle.startedAt,
+      completedAt: bundle.completedAt,
+      scanTimeSeconds: bundle.scanTimeSeconds,
+      timing: bundle.timing,
+      summary: {
+        headline: bundle.summary?.headline ?? null,
+        executiveSummary: null,
+        counts: bundle.summary?.counts ?? null,
+        agentInterpretation: null
+      },
+      findings: [],
+      findingsMetadata: {
+        shown: 0,
+        total: bundle.findingsMetadata.total,
+        truncated: bundle.findingsMetadata.total > 0
+      },
+      links: Object.fromEntries(Object.entries(bundle.links ?? {}).filter(([key]) => ["docs", "report", "self"].includes(key))),
+      reportUrl: bundle.reportUrl,
+      recommendedNextTool: null,
+      recommendedNextAction: bundle.recommendedNextAction,
+      error: bundle.error,
+      mcpMetadata: {
+        detail,
+        heavyEvidenceIncluded: false,
+        findingsTruncated: bundle.findingsMetadata.total > 0,
+        requestedMaxBytes: maxBytes,
+        actualBytes: 0,
+        truncated: true,
+        truncationReason: "minimal_canonical_result_returned_to_byte_limit",
+        omittedSections: [.../* @__PURE__ */ new Set([...bundle.mcpMetadata.omittedSections, "summaryDetail", "findings", "evidence"])],
+        nextRecommendedMaxBytes: bundle.mcpMetadata.nextRecommendedMaxBytes ?? Math.min(2e5, maxBytes + 1e3),
+        omittedContentAvailableViaUrl: Object.keys(contentUrls).length > 0,
+        contentUrls
+      },
+      observationOnlyDisclaimer: bundle.observationOnlyDisclaimer,
+      disclaimer: bundle.disclaimer
+    };
+    updateBundleActualBytes(minimal);
+    return minimal;
+  }
+  return bundle;
 }
 function explainFinding(report, findingId) {
   const finding = findingsFromReport(report).find((candidate) => candidate.id === findingId);
@@ -33114,8 +33852,18 @@ function explainFinding(report, findingId) {
 }
 
 // src/server.ts
-var createScanDeprecationWarningPrinted = false;
 var DEFAULT_MCP_SCAN_WAIT_MS = 45e3;
+async function retryTransientOriginFailure(operation) {
+  try {
+    return await operation();
+  } catch (error2) {
+    const retryable = error2 instanceof Error && "status" in error2 && [502, 503, 504].includes(Number(error2.status));
+    if (!retryable) {
+      throw error2;
+    }
+    return operation();
+  }
+}
 function scanCreationMetadata(value) {
   return {
     executionMode: value.executionMode,
@@ -33156,7 +33904,9 @@ function createCertScoreMcpServer(options = {}) {
     name: "certscore",
     version: CERTSCORE_MCP_VERSION
   });
-  const lightTools = /* @__PURE__ */ new Set(["scan_site", "get_scan_status", "get_scan_bundle"]);
+  const sdkCreateToolError = server.createToolError.bind(server);
+  server.createToolError = (message) => message.includes("Input validation error:") ? toInvalidArgumentsToolError(message) : sdkCreateToolError(message);
+  const lightTools = /* @__PURE__ */ new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"]);
   const registerMcpTool = server.registerTool.bind(server);
   const registerTool = (name, contract, handler) => {
     if (options.toolProfile === "light" && !lightTools.has(name)) {
@@ -33164,45 +33914,9 @@ function createCertScoreMcpServer(options = {}) {
     }
     registerMcpTool(name, contract, handler);
   };
-  async function createPulseScanTool(input) {
-    const result = await client.submitScan(input.url, {
-      detail: normalizeDetail2(input.detail),
-      format: normalizeFormat2(input.format),
-      freshness: input.freshness ?? "latest",
-      scanFrom: input.scanFrom
-    });
-    return {
-      type: "certscore_mcp_scan_created",
-      status: result.status,
-      jobId: result.jobId ?? null,
-      scanId: result.scanId ?? result.scan_id ?? null,
-      completed: result.completed ?? false,
-      statusUrl: result.statusUrl ?? result.nextCheckUrl ?? null,
-      resultUrl: result.resultUrl ?? null,
-      reportUrl: result.reportUrl ?? null,
-      pulse: result.pulse ?? null,
-      resultDisposition: result.resultDisposition ?? result.pulse?.resultDisposition ?? null,
-      noGo: result.noGo ?? result.pulse?.noGo ?? null
-    };
-  }
-  registerTool(
-    "create_scan",
-    toolContract("create_scan"),
-    async (input) => {
-      try {
-        if (!createScanDeprecationWarningPrinted) {
-          createScanDeprecationWarningPrinted = true;
-          console.error("[certscore-mcp] create_scan is deprecated in the 0.2.x line. Use scan_site for new integrations.");
-        }
-        return toToolResult(await createPulseScanTool(input));
-      } catch (error2) {
-        return toToolError(error2);
-      }
-    }
-  );
   registerTool(
-    "scan_site",
-    toolContract("scan_site"),
+    "certscore_scan_site",
+    toolContract("certscore_scan_site"),
     async (input) => {
       try {
         const created = await client.scans.create(input.url, {
@@ -33210,30 +33924,35 @@ function createCertScoreMcpServer(options = {}) {
           scanFrom: input.scanFrom
         });
         if (input.waitForCompletion === false || created.type === "certscore_scan") {
-          return toToolResult(created);
+          return toToolResult(withMcpAgentGuidance(created));
         }
         try {
           const completed = await client.scans.wait(created, {
             maxWaitMs: Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1e3 : DEFAULT_MCP_SCAN_WAIT_MS, DEFAULT_MCP_SCAN_WAIT_MS)
           });
-          return toToolResult({
+          return toToolResult(withMcpAgentGuidance({
             ...completed,
-            ...scanCreationMetadata(created),
-            recommendedNextTool: "get_scan_bundle"
-          });
+            ...scanCreationMetadata(created)
+          }));
         } catch (error2) {
-          if (!(error2 instanceof CertScoreTimeoutError)) {
-            throw error2;
-          }
           const scanId = created.scanId ?? created.scan_id;
-          if (scanId) {
-            return toToolResult({
-              ...await client.scans.status(scanId),
-              ...scanCreationMetadata(created),
-              recommendedNextTool: "get_scan_status"
-            });
+          console.warn(JSON.stringify({
+            event: "mcp.certscore_scan_site.wait_deferred",
+            errorName: error2 instanceof Error ? error2.name : "UnknownError",
+            jobId: created.jobId ?? null,
+            scanId: scanId ?? null,
+            status: created.status ?? null
+          }));
+          if (error2 instanceof CertScoreTimeoutError && scanId) {
+            try {
+              return toToolResult(withMcpAgentGuidance({
+                ...await client.scans.status(scanId),
+                ...scanCreationMetadata(created)
+              }));
+            } catch {
+            }
           }
-          return toToolResult(created);
+          return toToolResult(withMcpAgentGuidance(created));
         }
       } catch (error2) {
         return toToolError(error2);
@@ -33241,8 +33960,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_scan",
-    toolContract("get_scan"),
+    "certscore_get_scan",
+    toolContract("certscore_get_scan"),
     async ({ scanId }) => {
       try {
         return toToolResult(await client.scans.get(scanId));
@@ -33252,54 +33971,48 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_scan_status",
-    toolContract("get_scan_status"),
-    async ({ jobId, scanId }) => {
+    "certscore_get_scan_status",
+    toolContract("certscore_get_scan_status"),
+    async ({ scanId }) => {
       try {
-        if (scanId) {
-          const status2 = await client.scans.status(scanId);
-          const needsTerminalHydration = status2.status === "completed" || status2.status === "completed_limited";
-          if (needsTerminalHydration) {
-            try {
-              const scan = await client.scans.get(scanId);
-              return toToolResult({
-                ...status2,
-                type: "certscore_scan_job",
-                status: scan.status,
-                domain: scan.domain,
-                resultDisposition: scan.resultDisposition,
-                noGo: scan.noGo,
-                startedAt: scan.startedAt,
-                completedAt: scan.completedAt,
-                scanTimeSeconds: scan.scanTimeSeconds,
-                recommendedNextTool: "get_scan_bundle"
-              });
-            } catch {
-            }
+        const status = await client.scans.status(scanId);
+        const needsTerminalHydration = status.status === "completed" || status.status === "completed_limited";
+        if (needsTerminalHydration) {
+          try {
+            const scan = await client.scans.get(scanId);
+            return toToolResult(withMcpAgentGuidance({
+              ...status,
+              type: "certscore_scan_job",
+              status: scan.status,
+              domain: scan.domain,
+              url: scan.url ?? null,
+              resultDisposition: scan.resultDisposition,
+              noGo: scan.noGo,
+              createdAt: scan.createdAt ?? null,
+              startedAt: scan.startedAt,
+              completedAt: scan.completedAt,
+              scanTimeSeconds: scan.scanTimeSeconds,
+              score: scan.score ?? null,
+              scoreStatus: scan.scoreStatus,
+              scoreVersion: scan.scoreVersion ?? null,
+              scoreUpdatedAt: scan.scoreUpdatedAt ?? null,
+              riskLevel: scan.riskLevel ?? null,
+              coverage: scan.coverage ?? null,
+              reportUrl: scan.links?.report ?? status.reportUrl ?? null,
+              links: { ...status.links, ...scan.links }
+            }));
+          } catch {
           }
-          return toToolResult(status2);
-        }
-        if (!jobId) {
-          return toToolResult({
-            error: {
-              name: "InvalidToolInput",
-              message: "Provide either scanId for API v2 scan status or jobId for Pulse job status."
-            }
-          });
         }
-        const status = await client.getJobStatus(jobId);
-        return toToolResult({
-          ...status,
-          scanId: scanIdFromStatus(status)
-        });
+        return toToolResult(withMcpAgentGuidance(status));
       } catch (error2) {
         return toToolError(error2);
       }
     }
   );
   registerTool(
-    "get_report",
-    toolContract("get_report"),
+    "certscore_get_report",
+    toolContract("certscore_get_report"),
     async ({ scanId, detail, format }) => {
       try {
         const normalizedFormat = normalizeFormat2(format);
@@ -33317,8 +34030,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_evidence",
-    toolContract("get_evidence"),
+    "certscore_get_evidence",
+    toolContract("certscore_get_evidence"),
     async ({ scanId }) => {
       try {
         return toToolResult(boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" })));
@@ -33328,20 +34041,37 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_scan_bundle",
-    toolContract("get_scan_bundle"),
-    async ({ scanId, maxFindings, maxPreConsentRows }) => {
+    "certscore_get_scan_bundle",
+    toolContract("certscore_get_scan_bundle"),
+    async ({ scanId, detail = "summary", maxBytes, maxFindings, maxPreConsentRows }) => {
       try {
-        const [scan, report, evidence, findings, preConsentCookiesTrackers] = await Promise.all([
-          client.scans.get(scanId),
-          client.getScan(scanId, { detail: "summary", format: "json" }),
-          client.getScan(scanId, { detail: "evidence", format: "json" }),
-          client.findings.list(scanId),
-          client.scans.preConsentCookiesTrackers(scanId)
+        const scan = await retryTransientOriginFailure(() => client.scans.get(scanId));
+        if (scan.status === "completed_limited" && scan.resultDisposition === "no_go") {
+          return toToolResult(buildScanBundle({
+            detail,
+            evidence: null,
+            findings: { type: "certscore_finding_list", scanId, findings: [] },
+            maxBytes,
+            maxFindings,
+            maxPreConsentRows,
+            preConsentCookiesTrackers: null,
+            report: null,
+            scan
+          }));
+        }
+        const includeEvidence = detail === "evidence" || detail === "full";
+        const reportDetail = detail === "full" ? "full" : includeEvidence ? "evidence" : "summary";
+        const [report, findings, preConsentCookiesTrackers] = await Promise.all([
+          retryTransientOriginFailure(() => client.getScan(scanId, { detail: reportDetail, format: "json" })),
+          retryTransientOriginFailure(() => client.findings.list(scanId)),
+          includeEvidence ? retryTransientOriginFailure(() => client.scans.preConsentCookiesTrackers(scanId)) : Promise.resolve(null)
         ]);
+        const evidence = includeEvidence ? report : null;
         return toToolResult(buildScanBundle({
+          detail,
           evidence,
           findings,
+          maxBytes,
           maxFindings,
           maxPreConsentRows,
           preConsentCookiesTrackers,
@@ -33354,8 +34084,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "export_findings",
-    toolContract("export_findings"),
+    "certscore_export_findings",
+    toolContract("certscore_export_findings"),
     async ({ scanId }) => {
       try {
         const report = await client.getScan(scanId, { detail: "full", format: "json" });
@@ -33366,8 +34096,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "list_findings",
-    toolContract("list_findings"),
+    "certscore_list_findings",
+    toolContract("certscore_list_findings"),
     async ({ limit, offset, scanId }) => {
       try {
         return toToolResult(paginateFindingList(await client.findings.list(scanId), { limit, offset }));
@@ -33377,8 +34107,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_pre_consent_cookies_trackers",
-    toolContract("get_pre_consent_cookies_trackers"),
+    "certscore_get_pre_consent_cookies_trackers",
+    toolContract("certscore_get_pre_consent_cookies_trackers"),
     async ({ maxRows, scanId }) => {
       try {
         return toToolResult(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }));
@@ -33388,8 +34118,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "explain_finding",
-    toolContract("explain_finding"),
+    "certscore_explain_finding",
+    toolContract("certscore_explain_finding"),
     async ({ scanId, findingId }) => {
       try {
         return toToolResult(await client.findings.explain(scanId, findingId));
@@ -33399,8 +34129,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_latest_domain_scan",
-    toolContract("get_latest_domain_scan"),
+    "certscore_get_latest_domain_scan",
+    toolContract("certscore_get_latest_domain_scan"),
     async ({ domain: domain2, scanFrom }) => {
       try {
         return toToolResult(await client.domains.latest(domain2, { scanFrom }));
@@ -33410,8 +34140,8 @@ function createCertScoreMcpServer(options = {}) {
     }
   );
   registerTool(
-    "get_latest_domain_pre_consent_cookies_trackers",
-    toolContract("get_latest_domain_pre_consent_cookies_trackers"),
+    "certscore_get_latest_domain_pre_consent_cookies_trackers",
+    toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"),
     async ({ domain: domain2, maxRows, scanFrom }) => {
       try {
         return toToolResult(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain2, { scanFrom }), { maxRows }));