mcpscraper-cli 0.50.1 → 0.51.0

package/dist/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { fileURLToPath } from "url";
 import { mkdirSync, realpathSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -10,7 +10,7 @@ import { randomUUID } from "crypto";
 import { ScraperClient, ScraperApiError } from "mcpscraper-sdk";
 
 // src/version.ts
-var CLI_VERSION = "0.50.1";
+var CLI_VERSION = "0.51.0";
 
 // src/generated-tools.ts
 var MCP_TOOL_CATALOG = [
@@ -151,7 +151,7 @@ var MCP_TOOL_CATALOG = [
               "type": "boolean"
             },
             "index": {
-              "description": "Ordered zero-based or one-based position defined by the surrounding collection.",
+              "description": "Whether this scope permits indexing Memory content.",
               "type": "boolean"
             },
             "admin": {
@@ -432,7 +432,7 @@ var MCP_TOOL_CATALOG = [
               "type": "boolean"
             },
             "index": {
-              "description": "Ordered zero-based or one-based position defined by the surrounding collection.",
+              "description": "Whether this scope permits indexing Memory content.",
               "type": "boolean"
             },
             "admin": {
@@ -893,7 +893,7 @@ var MCP_TOOL_CATALOG = [
           "type": "string",
           "minLength": 1,
           "maxLength": 180,
-          "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+          "description": "Required utm_source value identifying the acquisition source, such as google or a newsletter name."
         },
         "medium": {
           "type": "string",
@@ -913,7 +913,7 @@ var MCP_TOOL_CATALOG = [
           "maxLength": 240
         },
         "content": {
-          "description": "Complete content to route, validate, or store; do not substitute a partial excerpt when full content is required.",
+          "description": "Optional utm_content label identifying the ad creative or link variant; this is not document content.",
           "type": "string",
           "maxLength": 240
         },
@@ -2361,10 +2361,10 @@ var MCP_TOOL_CATALOG = [
                           "type": "string",
                           "minLength": 1,
                           "maxLength": 160,
-                          "description": "Optional normalized analytics event-name filter."
+                          "description": "Required canonical event name that this score predicate must match."
                         },
                         "withinDays": {
-                          "description": "Optional bounded lookback window in days.",
+                          "description": "Lookback window in days for this predicate; required for event_recency and optional for other supported predicates.",
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 3650
@@ -2388,16 +2388,16 @@ var MCP_TOOL_CATALOG = [
                           "type": "string",
                           "minLength": 1,
                           "maxLength": 160,
-                          "description": "Optional normalized analytics event-name filter."
+                          "description": "Required canonical event name that this score predicate must match."
                         },
                         "minimum": {
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 1e3,
-                          "description": "Overall lower bound for the governed score or range."
+                          "description": "Minimum number of matching events required by an event_frequency predicate."
                         },
                         "withinDays": {
-                          "description": "Optional bounded lookback window in days.",
+                          "description": "Lookback window in days for this predicate; required for event_recency and optional for other supported predicates.",
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 3650
@@ -2422,13 +2422,13 @@ var MCP_TOOL_CATALOG = [
                           "type": "string",
                           "minLength": 1,
                           "maxLength": 160,
-                          "description": "Optional normalized analytics event-name filter."
+                          "description": "Required canonical event name that this score predicate must match."
                         },
                         "withinDays": {
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 3650,
-                          "description": "Optional bounded lookback window in days."
+                          "description": "Lookback window in days for this predicate; required for event_recency and optional for other supported predicates."
                         }
                       },
                       "required": [
@@ -2453,7 +2453,7 @@ var MCP_TOOL_CATALOG = [
                           "description": "Exact path value used by this tool; preserve its leading slash or vault-relative form as required."
                         },
                         "withinDays": {
-                          "description": "Optional bounded lookback window in days.",
+                          "description": "Lookback window in days for this predicate; required for event_recency and optional for other supported predicates.",
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 3650
@@ -2522,7 +2522,7 @@ var MCP_TOOL_CATALOG = [
                           "description": "Canonical call or pipeline outcome matched by this rule."
                         },
                         "withinDays": {
-                          "description": "Optional bounded lookback window in days.",
+                          "description": "Lookback window in days for this predicate; required for event_recency and optional for other supported predicates.",
                           "type": "integer",
                           "minimum": 1,
                           "maximum": 3650
@@ -2992,8 +2992,7 @@ var MCP_TOOL_CATALOG = [
                   "entered",
                   "advanced",
                   "median_time_seconds"
-                ],
-                "description": "Allowlisted report column selected for sorting."
+                ]
               },
               "description": "Ordered allowlisted columns for the selected report family."
             },
@@ -3525,7 +3524,7 @@ var MCP_TOOL_CATALOG = [
           "description": "Analytics Site id returned by analytics_list_sites."
         },
         "fields": {
-          "description": "Ordered form-field definitions to render and validate for submissions.",
+          "description": "Optional allowlisted CRM export columns; advertising identifiers require the advertising_measurement purpose acknowledgement.",
           "minItems": 1,
           "maxItems": 16,
           "type": "array",
@@ -8808,7 +8807,7 @@ var MCP_TOOL_CATALOG = [
           "type": "string",
           "minLength": 1,
           "maxLength": 80,
-          "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+          "description": "Required source-system name for the event being recorded; this is provenance, not a report filter."
         },
         "sourceAccountRef": {
           "type": "string",
@@ -8839,7 +8838,7 @@ var MCP_TOOL_CATALOG = [
         "eventName": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9_]{1,79}$",
-          "description": "Optional normalized analytics event-name filter."
+          "description": "Required canonical name for the event being recorded; use lowercase letters, digits, and underscores starting with a letter."
         },
         "occurredAt": {
           "type": "string",
@@ -9098,7 +9097,7 @@ var MCP_TOOL_CATALOG = [
                     "type": "string",
                     "minLength": 1,
                     "maxLength": 160,
-                    "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+                    "description": "Required canonical source event name used by this activation mapping."
                   },
                   "providerEvent": {
                     "type": "string",
@@ -10494,6 +10493,104 @@ var MCP_TOOL_CATALOG = [
       "openWorldHint": false
     }
   },
+  {
+    "name": "artifact_describe",
+    "category": "artifacts",
+    "title": "Describe Retained File",
+    "description": "Inspect owned artifactId MIME, bytes, SHA-256, capabilities, expiry and download access. Denies foreign or expired files.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Artifact ID returned by a completed MCP result. Access remains bound to this authenticated caller."
+        }
+      },
+      "required": [
+        "artifactId"
+      ],
+      "$schema": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "annotations": {
+      "title": "Describe Retained File",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
+  },
+  {
+    "name": "artifact_download",
+    "category": "artifacts",
+    "title": "Download Retained File",
+    "description": "Get or renew owned artifactId downloads without reacquisition. Links expire in 15 minutes; retention is separate. Local paths are server-side; client access is unqualified. Denies expired or foreign files.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Artifact ID returned by a completed MCP result. Access remains bound to this authenticated caller."
+        }
+      },
+      "required": [
+        "artifactId"
+      ],
+      "$schema": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "annotations": {
+      "title": "Download Retained File",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": false
+    }
+  },
+  {
+    "name": "artifact_read",
+    "category": "artifacts",
+    "title": "Read Retained File",
+    "description": "Read owned retained text by artifactId. Follow nextOffset until null for complete UTF-8 content. Binary files need artifact_download or a format reader. Denies expired or foreign files; no reacquisition.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Artifact ID returned by a completed MCP result. Access remains bound to this authenticated caller."
+        },
+        "offset": {
+          "default": 0,
+          "description": "UTF-8 byte offset; use the exact nextOffset from the previous read.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxBytes": {
+          "default": 8e3,
+          "description": "Requested maximum bytes. The common serialized response budget may return a smaller window; follow nextOffset until null for the complete file.",
+          "type": "integer",
+          "minimum": 4,
+          "maximum": 1e5
+        }
+      },
+      "required": [
+        "artifactId"
+      ],
+      "$schema": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "annotations": {
+      "title": "Read Retained File",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
+  },
   {
     "name": "audit_site",
     "category": "web",
@@ -10877,7 +10974,7 @@ var MCP_TOOL_CATALOG = [
     "name": "browser_open",
     "category": "browser",
     "title": "Open Browser Session",
-    "description": "Open a hosted browser session you can drive. By default it is direct/no-proxy. Pass a saved profile name for authenticated sites, or serp_identity to load that identity's saved browser state and fixed network address. Returns a session_id used by all other browser_* tools.",
+    "description": "Open a hosted browser session you can drive. By default it is direct/no-proxy. Pass a saved profile name for authenticated sites, or serp_identity to load that identity's saved browser state and fixed network address. Returns a session_id used by all other browser_* tools. Billed at 120 Credits per minute for the entire time the session is open, including idle time and waiting. Call browser_close with the session_id when finished to stop billing; browser_list_sessions can recover a lost ID.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -12376,7 +12473,7 @@ var MCP_TOOL_CATALOG = [
                       "format": "uri"
                     },
                     "source": {
-                      "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                      "description": "Source or publisher name for this citation, preserved as attribution.",
                       "type": "string",
                       "maxLength": 240
                     },
@@ -13404,7 +13501,7 @@ var MCP_TOOL_CATALOG = [
                       "format": "uri"
                     },
                     "source": {
-                      "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                      "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                       "type": "string",
                       "maxLength": 240
                     },
@@ -13548,7 +13645,7 @@ var MCP_TOOL_CATALOG = [
                       "format": "uri"
                     },
                     "source": {
-                      "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                      "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                       "type": "string",
                       "maxLength": 240
                     },
@@ -13680,7 +13777,7 @@ var MCP_TOOL_CATALOG = [
                     "format": "uri"
                   },
                   "source": {
-                    "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                    "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                     "type": "string",
                     "maxLength": 240
                   },
@@ -14329,7 +14426,7 @@ var MCP_TOOL_CATALOG = [
                       "format": "uri"
                     },
                     "source": {
-                      "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                      "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                       "type": "string",
                       "maxLength": 240
                     },
@@ -14473,7 +14570,7 @@ var MCP_TOOL_CATALOG = [
                       "format": "uri"
                     },
                     "source": {
-                      "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                      "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                       "type": "string",
                       "maxLength": 240
                     },
@@ -14605,7 +14702,7 @@ var MCP_TOOL_CATALOG = [
                     "format": "uri"
                   },
                   "source": {
-                    "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended.",
+                    "description": "Source or publisher name for this citation or claim reference, preserved as attribution.",
                     "type": "string",
                     "maxLength": 240
                   },
@@ -15380,35 +15477,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "socialLinks": {
                       "type": "boolean",
-                      "description": "Curated public social profile links for the publication identity."
+                      "description": "Whether the renderer includes social profile links."
                     },
                     "authority": {
                       "type": "boolean",
-                      "description": "Source authority or ownership context supporting this content."
+                      "description": "Whether the renderer includes the authority section."
                     },
                     "consultation": {
                       "type": "boolean",
-                      "description": "Consultation-call presentation and link settings."
+                      "description": "Whether the renderer includes the consultation call-to-action."
                     },
                     "learning": {
                       "type": "boolean",
-                      "description": "Learning-section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the learning section."
                     },
                     "services": {
                       "type": "boolean",
-                      "description": "Source-backed services associated with the business listing."
+                      "description": "Whether the renderer includes the services section."
                     },
                     "proof": {
                       "type": "boolean",
-                      "description": "Proof-section content and evidence references."
+                      "description": "Whether the renderer includes the proof section."
                     },
                     "finalCta": {
                       "type": "boolean",
-                      "description": "Final call-to-action content shown after the authored collection."
+                      "description": "Whether the renderer includes the final call-to-action."
                     }
                   },
                   "required": [
@@ -15537,7 +15634,7 @@ var MCP_TOOL_CATALOG = [
                         "modern-sans",
                         "humanist-sans"
                       ],
-                      "description": "Registered self-contained display-font family selected for prominent headings."
+                      "description": "Registered self-contained body-font family selected for article and paragraph text."
                     }
                   },
                   "required": [
@@ -15551,35 +15648,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "socialLinks": {
                       "type": "boolean",
-                      "description": "Curated public social profile links for the publication identity."
+                      "description": "Whether the renderer includes social profile links."
                     },
                     "authority": {
                       "type": "boolean",
-                      "description": "Source authority or ownership context supporting this content."
+                      "description": "Whether the renderer includes the authority section."
                     },
                     "consultation": {
                       "type": "boolean",
-                      "description": "Consultation-call presentation and link settings."
+                      "description": "Whether the renderer includes the consultation call-to-action."
                     },
                     "learning": {
                       "type": "boolean",
-                      "description": "Learning-section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the learning section."
                     },
                     "services": {
                       "type": "boolean",
-                      "description": "Source-backed services associated with the business listing."
+                      "description": "Whether the renderer includes the services section."
                     },
                     "proof": {
                       "type": "boolean",
-                      "description": "Proof-section content and evidence references."
+                      "description": "Whether the renderer includes the proof section."
                     },
                     "finalCta": {
                       "type": "boolean",
-                      "description": "Final call-to-action content shown after the authored collection."
+                      "description": "Whether the renderer includes the final call-to-action."
                     }
                   },
                   "required": [
@@ -15669,35 +15766,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "breakingTicker": {
                       "type": "boolean",
-                      "description": "Optional short breaking-news ticker shown by the renderer."
+                      "description": "Whether the renderer includes the breaking-news ticker."
                     },
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "leadGrid": {
                       "type": "boolean",
-                      "description": "Lead-story grid configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the lead-story grid."
                     },
                     "latestNews": {
                       "type": "boolean",
-                      "description": "Latest-news section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the latest-news section."
                     },
                     "categorySections": {
                       "type": "boolean",
-                      "description": "Ordered category sections and their assigned article references."
+                      "description": "Whether the renderer includes article sections grouped by category."
                     },
                     "newsletter": {
                       "type": "boolean",
-                      "description": "Newsletter-callout presentation and subscription link settings."
+                      "description": "Whether the renderer includes the newsletter call-to-action."
                     },
                     "pressRoom": {
                       "type": "boolean",
-                      "description": "Press-room section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the press-room section."
                     },
                     "trustFooter": {
                       "type": "boolean",
-                      "description": "Trust and provenance footer configuration for the rendered site."
+                      "description": "Whether the renderer includes the trust and provenance footer."
                     }
                   },
                   "required": [
@@ -16487,7 +16584,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-activity-append",
     "category": "crm",
     "title": "Append CRM Activity",
-    "description": "Append one idempotent governed CRM activity to canonical Communication, linked only to stable CRM\u2026",
+    "description": "Append one idempotent governed CRM activity to canonical Communication, linked only to stable CRM entity IDs. Use for actual calls, meetings, messages, forms, conversions, or notes about a managed relationship; never pass a Research record ID. This is native Memory CRM and does not write to an external provider.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16500,12 +16597,12 @@ var MCP_TOOL_CATALOG = [
         "entityId": {
           "type": "string",
           "format": "uuid",
-          "description": "Existing governed entity identifier for this relation or edit."
+          "description": "Optional stable ID for this new activity work record, not a CRM person or organization ID."
         },
         "personEntityId": {
           "type": "string",
           "format": "uuid",
-          "description": "Stable CRM Person entity identifier; Research identifiers are rejected."
+          "description": "CRM Person entity ID to associate with this activity."
         },
         "entityIds": {
           "type": "array",
@@ -16515,7 +16612,7 @@ var MCP_TOOL_CATALOG = [
           },
           "maxItems": 100,
           "default": [],
-          "description": "Stable CRM entity identifiers associated with this CRM activity, task, or deal."
+          "description": "CRM person or organization entity IDs associated with this activity; at least one association is required."
         },
         "activityType": {
           "type": "string",
@@ -16563,7 +16660,7 @@ var MCP_TOOL_CATALOG = [
         "source": {
           "type": "object",
           "additionalProperties": {},
-          "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+          "description": "Optional source provenance stored with the CRM activity; this is not a record filter."
         },
         "props": {
           "type": "object",
@@ -16591,14 +16688,14 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-counterpart-apply",
     "category": "crm",
     "title": "Apply CRM Counterpart Link",
-    "description": "Apply an unexpired owner-scoped counterpart link preview using its exact handle and digest. The\u2026",
+    "description": "Apply an unexpired owner-scoped counterpart link preview using its exact handle and digest. The operation is idempotent, copies no fields, and keeps the Research and CRM records independently editable.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "planId": {
           "type": "string",
           "format": "uuid",
-          "description": "Durable CRM provisioning-plan identifier returned by the planning operation."
+          "description": "Exact owner-scoped counterpart plan identifier returned by crm-counterpart-preview; use its matching unexpired planHandle and digest."
         },
         "planHandle": {
           "type": "string",
@@ -16639,7 +16736,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-counterpart-preview",
     "category": "crm",
     "title": "Preview CRM Counterpart Link",
-    "description": "Preview an explicit link between one Research record and one CRM record of the same kind. Link-only is\u2026",
+    "description": "Preview an explicit link between one Research record and one CRM record of the same kind. Link-only is the safe default and the only mode in this release: copiedFields is always empty, and neither record is promoted, merged, relocated, or synchronized. The returned owner-scoped handle and digest expire.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16693,7 +16790,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-deal-transition",
     "category": "crm",
     "title": "Transition CRM Deal",
-    "description": "Apply one governed deal-stage transition after enforcing the pipeline\u2019s allowed forward/backward moves\u2026",
+    "description": "Apply one governed deal-stage transition after enforcing the pipeline\u2019s allowed forward/backward moves, required fields, probability, and won/lost semantics. Returns an audit receipt and rejects stale revisions.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16727,7 +16824,7 @@ var MCP_TOOL_CATALOG = [
           "type": "object",
           "additionalProperties": {},
           "default": {},
-          "description": "Ordered form-field definitions to render and validate for submissions."
+          "description": "Deal field values to apply during this stage transition, including values required by the destination stage."
         }
       },
       "required": [
@@ -16752,7 +16849,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-deal-upsert",
     "category": "crm",
     "title": "Upsert CRM Deal",
-    "description": "Create or revision-check a canonical Deal associated only with stable CRM people or organizations. A\u2026",
+    "description": "Create or revision-check a Deal for an actual commercial opportunity associated with CRM people or organizations. Read crm-pipeline-list for pipelineId, stageId, and probability. From crm-work-search with objectKind:deal, use workId as dealId and revision as baseRevision. Use baseRevision:0 for creation and keep idempotencyKey/input unchanged on retry.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16764,7 +16861,7 @@ var MCP_TOOL_CATALOG = [
         "baseRevision": {
           "type": "integer",
           "minimum": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a deal; for an edit, supply dealId and the current positive revision read from crm-work-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -16808,12 +16905,12 @@ var MCP_TOOL_CATALOG = [
           "type": "number",
           "minimum": 0,
           "maximum": 1,
-          "description": "Deal probability from zero through one hundred for the selected governed stage."
+          "description": "Deal probability from 0 through 1; must equal the selected stage probability returned by crm-pipeline-list."
         },
         "party": {
           "type": "string",
           "format": "uuid",
-          "description": "Stable CRM person or organization party associated with the deal."
+          "description": "Stable CRM person or organization party for the deal; this identifier must also appear in entityIds."
         },
         "enteredAt": {
           "type": "string",
@@ -16877,7 +16974,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-duplicate-search",
     "category": "crm",
     "title": "Search CRM Duplicates",
-    "description": "Search reviewable duplicate candidates within one CRM person or organization domain using stable\u2026",
+    "description": "Search reviewable duplicate candidates within one CRM person or organization domain using stable owner-scoped evidence. This never merges, links, or promotes records and never searches Research records.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16936,7 +17033,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-import-apply",
     "category": "crm",
     "title": "Apply CRM Import",
-    "description": "Apply an unexpired CRM import preview with its exact owner-scoped handle, digest, explicit confirmation\u2026",
+    "description": "Apply an unexpired CRM import preview with its exact owner-scoped handle, digest, explicit confirmation token, and idempotency key. Upload or preview alone can never apply rows. Research domains are unreachable.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16990,7 +17087,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-import-preview",
     "category": "crm",
     "title": "Preview CRM Import",
-    "description": "Preview a CRM-owned import before any row is applied. Rows may target only CRM People or CRM\u2026",
+    "description": "Preview a CRM-owned import before any row is applied. Rows may target only CRM People or CRM Organizations. Returns validation issues, duplicate candidates, an owner-scoped expiring handle, and an exact digest; raw rows remain in Memory-owned storage and never enter X-Ray.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17070,7 +17167,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-merge-apply",
     "category": "crm",
     "title": "Apply CRM Merge",
-    "description": "Apply an explicitly owner-confirmed, unexpired CRM merge plan with its exact handle, digest, and\u2026",
+    "description": "Apply an explicitly owner-confirmed, unexpired CRM merge plan with its exact handle, digest, and idempotency key. The duplicate becomes a reversible archived alias; canonical source history is retained. This destructive operation is disabled without owner scope and confirmation.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17124,7 +17221,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-merge-preview",
     "category": "crm",
     "title": "Preview CRM Merge",
-    "description": "Preview a reversible duplicate merge inside one CRM domain. Shows field conflicts and affected\u2026",
+    "description": "Preview a reversible duplicate merge inside one CRM domain. Shows field conflicts and affected associations; the duplicate will become an archived alias and source history will not be deleted. Preview does not apply the merge.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17172,7 +17269,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-organization-get",
     "category": "crm",
     "title": "Get CRM Organization",
-    "description": "Get one managed CRM Organization by stable entity ID with aliases, associations, and optional Research\u2026",
+    "description": "Get one managed CRM Organization by stable entity ID with aliases, associations, and optional Research counterpart ID. Linking does not synchronize fields.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17200,7 +17297,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-organization-search",
     "category": "crm",
     "title": "Search CRM Organizations",
-    "description": "Search owner-managed CRM Organizations such as prospect accounts, customers, employers, vendors\u2026",
+    "description": "Search owner-managed CRM Organizations such as prospect accounts, customers, employers, vendors, partners, communities, or publications. Never returns Research Organizations and never infers an account solely from an email domain.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17282,7 +17379,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-organization-upsert",
     "category": "crm",
     "title": "Upsert CRM Organization",
-    "description": "Create or revision-check a managed CRM Organization. Relationship type is required while commercial\u2026",
+    "description": "Create or revision-check a managed CRM Organization. Relationship type is required while commercial lifecycle is optional. Rejects Research claims/citations/roles/topics, does not infer an account from email, and does not activate an external provider.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17294,7 +17391,7 @@ var MCP_TOOL_CATALOG = [
         "baseRevision": {
           "type": "integer",
           "minimum": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a CRM Organization; for an edit, supply entityId and the current positive revision read from crm-organization-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -17450,7 +17547,7 @@ var MCP_TOOL_CATALOG = [
                   "type": "null"
                 }
               ],
-              "description": "Original source URL or opaque artifact reference preserved as image provenance."
+              "description": "Source URL, retained artifact reference, or other identifier for this CRM field provenance."
             },
             "observedAt": {
               "type": "string",
@@ -17500,7 +17597,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-person-get",
     "category": "crm",
     "title": "Get CRM Person",
-    "description": "Get one owner-managed CRM Person by stable entity ID with its governed relationship record, aliases\u2026",
+    "description": "Get one owner-managed CRM Person by stable entity ID with its governed relationship record, aliases, associations, and optional Research counterpart ID. It does not copy Research fields or expose provider setup.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17528,7 +17625,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-person-search",
     "category": "crm",
     "title": "Search CRM People",
-    "description": "Search owner-managed CRM People: prospects, customers, friends, coworkers, collaborators, vendors\u2026",
+    "description": "Search owner-managed CRM People: prospects, customers, friends, coworkers, collaborators, vendors, partners, advisors, media, community contacts, or other relationships. This is not research search and never returns Research People.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17610,7 +17707,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-person-upsert",
     "category": "crm",
     "title": "Upsert CRM Person",
-    "description": "Create or revision-check a managed CRM Person. Relationship type is required, but sales lifecycle and\u2026",
+    "description": "Create or revision-check a managed CRM Person. Relationship type is required, but sales lifecycle and deals are optional so friends, coworkers, and collaborators are first-class. Rejects Research claims/citations/roles/topics and never activates an external CRM provider.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17623,7 +17720,7 @@ var MCP_TOOL_CATALOG = [
           "type": "integer",
           "minimum": 0,
           "default": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a CRM Person; for an edit, supply entityId and the current positive revision read from crm-person-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -17779,7 +17876,7 @@ var MCP_TOOL_CATALOG = [
             "observedAt"
           ],
           "additionalProperties": false,
-          "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+          "description": "Optional governed form-source receipt associated with this CRM Person; this records provenance rather than filtering records."
         },
         "props": {
           "type": "object",
@@ -17823,7 +17920,7 @@ var MCP_TOOL_CATALOG = [
                   "type": "null"
                 }
               ],
-              "description": "Original source URL or opaque artifact reference preserved as image provenance."
+              "description": "Source URL, form submission reference, retained artifact reference, or other identifier for this CRM field provenance."
             },
             "observedAt": {
               "type": "string",
@@ -17848,7 +17945,7 @@ var MCP_TOOL_CATALOG = [
             "observedAt"
           ],
           "additionalProperties": false,
-          "description": "Field authority, sensitivity, source, observation time, and confidence recorded with this governed write."
+          "description": "Supply explicit unchanged lineage, including observedAt, for reliable idempotency replay. If both lineage and source are omitted, a timestamp is generated on every call; the same key prevents another write but a retry may report an idempotency conflict."
         }
       },
       "required": [
@@ -17871,7 +17968,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-pipeline-list",
     "category": "crm",
     "title": "List CRM Pipelines",
-    "description": "List owner-scoped native CRM deal pipelines with ordered stages, required fields, allowed transitions\u2026",
+    "description": "List owner-scoped native CRM deal pipelines with ordered stages, required fields, allowed transitions, probabilities, and versions. Use pipelineId, stageId, and probability for crm-deal-upsert, or version as crm-pipeline-upsert baseVersion. This reads native Memory CRM, not an external provider.",
     "inputSchema": {
       "type": "object",
       "properties": {},
@@ -17890,7 +17987,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-pipeline-upsert",
     "category": "crm",
     "title": "Upsert CRM Pipeline",
-    "description": "Create or revision-check an owner-scoped native CRM deal pipeline with governed stages and transitions\u2026",
+    "description": "Create or revise a native CRM deal pipeline with its complete ordered stages and transitions. Use crm-pipeline-list to obtain pipelineId and current baseVersion for edits; use baseVersion:0 for creation. Creation has no replay key: after an unknown outcome inspect crm-pipeline-list before retrying, or you may create duplicates. This changes native Memory CRM only.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -17992,7 +18089,7 @@ var MCP_TOOL_CATALOG = [
       "title": "Upsert CRM Pipeline",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -18000,7 +18097,7 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-quality-list",
     "category": "crm",
     "title": "List CRM Quality Issues",
-    "description": "List owner-scoped relationship quality issues for classification, invalid names, duplicates, imports\u2026",
+    "description": "List owner-scoped relationship quality issues for classification, invalid names, duplicates, imports, merges, or canonical work. This is an audit queue only: it never auto-classifies, auto-merges, or activates providers.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -18014,7 +18111,7 @@ var MCP_TOOL_CATALOG = [
             "merges",
             "work"
           ],
-          "description": "Governance queue to list: classification, naming, identity, duplicates, or delivery."
+          "description": "Governance queue to list: classification, naming, duplicates, imports, merges, or work."
         },
         "limit": {
           "type": "integer",
@@ -18039,25 +18136,25 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-task-upsert",
     "category": "crm",
     "title": "Upsert CRM Task",
-    "description": "Create or revision-check a canonical Task linked only to stable CRM entity IDs. Tasks remain in the\u2026",
+    "description": "Create or revision-check a canonical Task associated with CRM people or organizations. From crm-work-search with objectKind:task, use workId as taskId and revision as baseRevision; use baseRevision:0 for new tasks. Keep idempotencyKey and input unchanged on retry. This writes the shared Tasks authority.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "taskId": {
           "type": "string",
           "format": "uuid",
-          "description": "Stable CRM Task entity identifier for create or revision-checked update."
+          "description": "Task workId returned by crm-work-search; omit to create a new task."
         },
         "entityId": {
           "type": "string",
           "format": "uuid",
-          "description": "Existing governed entity identifier for this relation or edit."
+          "description": "Compatibility alias for taskId, not a CRM relationship ID; taskId takes precedence."
         },
         "baseRevision": {
           "type": "integer",
           "minimum": 0,
           "default": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a Task; for an edit, supply taskId or entityId and the current positive revision read from crm-work-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -18124,7 +18221,7 @@ var MCP_TOOL_CATALOG = [
         "source": {
           "type": "object",
           "additionalProperties": {},
-          "description": "Optional source or provenance constraint appropriate to this tool; omit when no source restriction is intended."
+          "description": "Optional source provenance stored with the Task; this is not a record filter."
         },
         "props": {
           "type": "object",
@@ -18152,261 +18249,129 @@ var MCP_TOOL_CATALOG = [
     "name": "crm-work-search",
     "category": "crm",
     "title": "Search CRM Work",
-    "description": "Search owner-scoped canonical CRM activities, tasks, or deals in deterministic updated-time order\u2026",
+    "description": "Search owner-scoped CRM activities, tasks, or deals in updated-time order. Select exactly one objectKind and use only its valid filters; follow pageInfo.endCursor for more. Returned workId identifies the work record; entityIds identify its CRM relationships. Long content and fields may be truncated. This reads native Memory CRM, not an external provider.",
     "inputSchema": {
       "type": "object",
-      "properties": {},
-      "anyOf": [
-        {
-          "type": "object",
-          "properties": {
-            "apiKey": {
-              "type": "string",
-              "description": "Caller API key. Omit when the MCP transport already authenticated this request."
-            },
-            "sessionId": {
-              "type": "string",
-              "description": "Optional MCP session identifier used for active account context."
-            },
-            "entityId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional stable CRM person or organization entity ID associated with the work record."
-            },
-            "entityIds": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "format": "uuid"
-              },
-              "minItems": 1,
-              "maxItems": 10,
-              "description": "Optional stable CRM entity IDs that must all be associated with the work record."
-            },
-            "workId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional exact canonical CRM activity, task, or deal work ID."
-            },
-            "query": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 300,
-              "description": "Optional case-insensitive title search."
-            },
-            "cursor": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 2048,
-              "description": "Opaque cursor returned by the previous crm-work-search page."
-            },
-            "limit": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 100,
-              "default": 25,
-              "description": "Maximum work records to return before cursor pagination."
-            },
-            "objectKind": {
-              "type": "string",
-              "const": "activity",
-              "description": "Search only canonical CRM activity records."
-            }
+      "properties": {
+        "entityId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Optional stable CRM person or organization entity ID associated with the work record."
+        },
+        "entityIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uuid"
           },
-          "required": [
-            "objectKind"
+          "minItems": 1,
+          "maxItems": 10,
+          "description": "Optional stable CRM entity IDs that must all be associated with the work record."
+        },
+        "workId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Optional exact canonical CRM activity, task, or deal work ID."
+        },
+        "query": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "Optional case-insensitive title search."
+        },
+        "cursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "Opaque cursor returned by the previous crm-work-search page."
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 25,
+          "description": "Maximum work records to return before cursor pagination."
+        },
+        "objectKind": {
+          "type": "string",
+          "enum": [
+            "activity",
+            "task",
+            "deal"
           ],
-          "additionalProperties": false
+          "description": "Search exactly one canonical CRM work kind."
         },
-        {
-          "type": "object",
-          "properties": {
-            "apiKey": {
-              "type": "string",
-              "description": "Caller API key. Omit when the MCP transport already authenticated this request."
-            },
-            "sessionId": {
-              "type": "string",
-              "description": "Optional MCP session identifier used for active account context."
-            },
-            "entityId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional stable CRM person or organization entity ID associated with the work record."
-            },
-            "entityIds": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "format": "uuid"
-              },
-              "minItems": 1,
-              "maxItems": 10,
-              "description": "Optional stable CRM entity IDs that must all be associated with the work record."
-            },
-            "workId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional exact canonical CRM activity, task, or deal work ID."
-            },
-            "query": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 300,
-              "description": "Optional case-insensitive title search."
-            },
-            "cursor": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 2048,
-              "description": "Opaque cursor returned by the previous crm-work-search page."
-            },
-            "limit": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 100,
-              "default": 25,
-              "description": "Maximum work records to return before cursor pagination."
-            },
-            "objectKind": {
-              "type": "string",
-              "const": "task",
-              "description": "Search only canonical Task records through the CRM lens."
-            },
-            "taskStatuses": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "enum": [
-                  "todo",
-                  "in_progress",
-                  "blocked",
-                  "done",
-                  "cancelled"
-                ]
-              },
-              "minItems": 1,
-              "maxItems": 100,
-              "description": "Optional canonical Task statuses to include."
-            },
-            "dueBefore": {
-              "type": "string",
-              "format": "date-time",
-              "description": "Inclusive upper due-time bound for canonical Tasks."
-            },
-            "dueAfter": {
-              "type": "string",
-              "format": "date-time",
-              "description": "Inclusive lower due-time bound for canonical Tasks."
-            },
-            "dueUnscheduled": {
-              "type": "boolean",
-              "description": "Set true to return only canonical Tasks without a due date."
-            },
-            "taskOwnerId": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 200,
-              "description": "Exact owner identifier stored on the canonical Task."
-            },
-            "dealId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Exact native CRM deal UUID linked from the canonical Task."
-            }
+        "taskStatuses": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "todo",
+              "in_progress",
+              "blocked",
+              "done",
+              "cancelled"
+            ]
           },
-          "required": [
-            "objectKind"
-          ],
-          "additionalProperties": false
+          "minItems": 1,
+          "maxItems": 100,
+          "description": "Task-only statuses to include."
         },
-        {
-          "type": "object",
-          "properties": {
-            "apiKey": {
-              "type": "string",
-              "description": "Caller API key. Omit when the MCP transport already authenticated this request."
-            },
-            "sessionId": {
-              "type": "string",
-              "description": "Optional MCP session identifier used for active account context."
-            },
-            "entityId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional stable CRM person or organization entity ID associated with the work record."
-            },
-            "entityIds": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "format": "uuid"
-              },
-              "minItems": 1,
-              "maxItems": 10,
-              "description": "Optional stable CRM entity IDs that must all be associated with the work record."
-            },
-            "workId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional exact canonical CRM activity, task, or deal work ID."
-            },
-            "query": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 300,
-              "description": "Optional case-insensitive title search."
-            },
-            "cursor": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 2048,
-              "description": "Opaque cursor returned by the previous crm-work-search page."
-            },
-            "limit": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 100,
-              "default": 25,
-              "description": "Maximum work records to return before cursor pagination."
-            },
-            "objectKind": {
-              "type": "string",
-              "const": "deal",
-              "description": "Search only native CRM deal records."
-            },
-            "pipelineId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Optional exact native CRM pipeline UUID."
-            },
-            "stageIds": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "format": "uuid"
-              },
-              "minItems": 1,
-              "maxItems": 100,
-              "description": "Optional native CRM stage UUIDs to include."
-            },
-            "minValue": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Optional inclusive minimum deal value in the stored currency."
-            },
-            "maxValue": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Optional inclusive maximum deal value in the stored currency."
-            }
+        "dueBefore": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Task-only inclusive upper due-time bound."
+        },
+        "dueAfter": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Task-only inclusive lower due-time bound."
+        },
+        "dueUnscheduled": {
+          "type": "boolean",
+          "description": "Task-only filter for records without a due date."
+        },
+        "taskOwnerId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Task-only exact owner identifier."
+        },
+        "dealId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Task-only native CRM deal UUID."
+        },
+        "pipelineId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Deal-only native CRM pipeline UUID."
+        },
+        "stageIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uuid"
           },
-          "required": [
-            "objectKind"
-          ],
-          "additionalProperties": false
+          "minItems": 1,
+          "maxItems": 100,
+          "description": "Deal-only native CRM stage UUIDs."
+        },
+        "minValue": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Deal-only inclusive minimum value."
+        },
+        "maxValue": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Deal-only inclusive maximum value."
         }
+      },
+      "required": [
+        "objectKind"
       ],
+      "additionalProperties": false,
       "$schema": "http://json-schema.org/draft-07/schema#"
     },
     "annotations": {
@@ -18660,9 +18625,9 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Directory Workflow: Markets + Maps",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": false,
+      "idempotentHint": true,
       "openWorldHint": true
     }
   },
@@ -20854,7 +20819,7 @@ var MCP_TOOL_CATALOG = [
     "name": "harvest_paa",
     "category": "search",
     "title": "Google PAA + SERP Harvest",
-    "description": "Expand one Google People Also Ask SERP into questions, answers, every preserved source, AI Overview evidence, ranking URLs, and entity IDs. Set pages to 2 to add the second organic-results page when available; PAA is still expanded once on the preserved first page, and pagination reports what was captured. maxQuestions is a target count, not traversal depth. Results distinguish target_reached, proven frontier_exhausted, interruption, and recovery_exhausted; a failed click or browser timeout is never reported as exhaustion. This compatibility tool waits; use harvest_paa_start plus harvest_paa_status for long runs. Optional SERP modules require their include flags. Use gl and location for regional context. Costs 400 Credits per harvest plus 10 Credits per question actually returned; unused hold is refunded. After a timeout or unknown response, reuse the same idempotencyKey. Call credits_info for current pricing and balance.",
+    "description": "Expand one Google People Also Ask SERP into full captured answers, every source with available titles/descriptions, organic snippets, AI Overview evidence, ranking URLs, and entity IDs. Unfinished answer expansion is partial. Set pages to 2 for a second organic page when available; PAA expands once on page one, and pagination reports captured coverage. maxQuestions is a target count, not traversal depth. Results distinguish target_reached, proven frontier_exhausted, interruption, and recovery_exhausted; failed clicks and timeouts never prove exhaustion. This tool waits; use harvest_paa_start and harvest_paa_status for long runs. Optional SERP modules require include flags. Use gl and location for regional context. Costs 400 Credits per harvest plus 10 Credits per question actually returned; unused hold is refunded. After a timeout or unknown response, reuse the same idempotencyKey. Call credits_info for current pricing and balance.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -21069,7 +21034,7 @@ var MCP_TOOL_CATALOG = [
     "name": "harvest_paa_status",
     "category": "other",
     "title": "Check Durable Google PAA Harvest",
-    "description": "Poll an owner-scoped harvest_paa_start job. Returns the job/operation/task correlation ID, saved progress, automatic-recovery count, target and discovery status, material completeness, bounded organic-page pagination, recent per-control interaction outcomes with 0.7/1.0/1.4-second confirmation telemetry, provider-session-correlated attempts, terminal rows, and billing. Page-two outcomes describe organic results only; the PAA graph always comes from the preserved first page. frontier_exhausted means every observed eligible PAA control was processed plus three healthy no-growth confirmations; interruption never means exhaustion. Polling never starts or bills another run.",
+    "description": "Poll an owner-scoped harvest_paa_start job for saved answers and source descriptions, progress, recovery count, target/discovery status, material completeness, pagination, interaction outcomes, correlated provider attempts, terminal rows, and billing. Unfinished answer expansion is partial. Page two adds organic results; PAA comes from page one. frontier_exhausted requires every observed eligible PAA control processed plus three healthy no-growth confirmations; interruption never means exhaustion. Polling never starts or bills another run.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -22319,7 +22284,7 @@ var MCP_TOOL_CATALOG = [
     "name": "library-ingest",
     "category": "library",
     "title": "Library Ingest",
-    "description": "Deposit a scrape, transcript, or generated output into the tenant Library vault for later semantic recall. Content is embedded for per-tenant search and best-effort mirrored to a local vault when configured. Requires write scope on the target vault.",
+    "description": "Deposit the complete text of a scrape, transcript, or generated output into the tenant Library vault and index it for semantic recall. Requires write scope on the target vault. Preserve capturedAt and title when retrying: omitting capturedAt generates a new timestamp and can create another note. After an unknown outcome, inspect the saved note before repeating.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -22343,7 +22308,7 @@ var MCP_TOOL_CATALOG = [
           "description": "Provenance of the content, e.g. a URL or tool name. Must be non-empty."
         },
         "capturedAt": {
-          "description": "ISO-8601 capture timestamp. Optional; defaults to now. Also seeds the deterministic storage path.",
+          "description": "ISO-8601 capture timestamp. Defaults to now and seeds the storage path with title. Preserve this timestamp and title on retries; omitting it can create another note.",
           "type": "string"
         },
         "summary": {
@@ -22394,7 +22359,7 @@ var MCP_TOOL_CATALOG = [
       "title": "Library Ingest",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": true
     }
   },
@@ -22727,7 +22692,7 @@ var MCP_TOOL_CATALOG = [
     "name": "local_sourcebook_refresh",
     "category": "directory",
     "title": "Refresh a Local Sourcebook Listing",
-    "description": "Queue a new broad crawl and review/media acquisition pass for a listing owned by the authenticated MCP Scraper account. A refresh costs 2 Credits total, including acquisition; idempotent retries are not charged twice, and a replayed retry still re-runs the acquisition, so a failed listing is always recoverable. Read local_sourcebook_submission_status first: a refresh repeats the same acquisition, so fix whatever acquisitionError reports before spending another pass. The last published revision remains public until the refreshed evidence revision completes and auto-publishes.",
+    "description": "Queue a new broad crawl and review/media acquisition pass for a listing owned by the authenticated MCP Scraper account. A refresh costs 2 Credits total, including acquisition. Read local_sourcebook_submission_status first and inspect acquisitionError after a failed attempt. After an unknown response, check status before calling again: this tool has no caller retry key, and another accepted call can start another acquisition. Listings already queued or enriching reject refreshes. The last published revision remains public until refreshed evidence completes and auto-publishes.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -22744,7 +22709,7 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Refresh a Local Sourcebook Listing",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
       "idempotentHint": false,
       "openWorldHint": true
@@ -23008,9 +22973,9 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Capture Governed Local Sourcebook Listing",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": false,
+      "idempotentHint": true,
       "openWorldHint": true
     }
   },
@@ -23214,7 +23179,7 @@ var MCP_TOOL_CATALOG = [
     "name": "maps_place_intel",
     "category": "maps",
     "title": "Google Maps Business Profile Details",
-    "description": 'Deep-dive one known/named Google Business Profile: rating, reviews, category, address, phone, website, full hours, About attributes, entity IDs/CID, configured services/areas, and optional photos. Use include:["all"] for every supported field group, with maxReviews and maxImages as limits; existing includeReviews, includeServices, and includeImages flags also work. Set includeImages:true for a provenance-aware manifest, bounded AI image blocks, and an owner-scoped ZIP; choose imageScope:"owner" for listing-owner photos only. Not for category searches or multi-business prospect lists; use maps_search for those. Split business name from location.',
+    "description": 'Inspect one named Google Business Profile: rating, reviews, category, address, phone, website, hours, About attributes, entity IDs/CID, services/areas, and optional photos when available. Use include:["all"] or includeReviews/includeServices/includeImages; maxReviews and maxImages bound collection. Page saved reviews/images with maps_place_status and returned cursors. includeImages:true supplies a manifest, bounded AI image blocks, and an owner-scoped ZIP; imageScope:"owner" selects listing-owner photos. For category searches or multi-business lists use maps_search. Split business name from location.',
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -23249,7 +23214,7 @@ var MCP_TOOL_CATALOG = [
         },
         "maxReviews": {
           "default": 50,
-          "description": "Max review cards when includeReviews is true. Default 50, maximum 1,000. Collection is resumable; actual availability depends on the profile.",
+          "description": "Max review cards when includeReviews is true. Default 50, maximum 1,000. Availability depends on the profile. Partial or interrupted runs can resume.",
           "type": "integer",
           "minimum": 1,
           "maximum": 1e3
@@ -23322,7 +23287,7 @@ var MCP_TOOL_CATALOG = [
     "name": "maps_place_resume",
     "category": "maps",
     "title": "Resume Google Maps Place Run",
-    "description": "Explicitly resume a partial Maps place run using a fresh idempotency key. This may launch a new paid provider attempt and requires a new maximum credit authorization. Repeating the same key only reads its status.",
+    "description": "Start another paid acquisition attempt for a partial or interrupted Maps place run after its previous billing is reconciled. Read maps_place_status first. Use a new resumeIdempotencyKey for this intended attempt; repeating the same key reads the existing run without starting or charging another attempt. The server reserves the declared maximum credits again before acquisition.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -23347,9 +23312,9 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Resume Google Maps Place Run",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": false,
+      "idempotentHint": true,
       "openWorldHint": true
     }
   },
@@ -23392,8 +23357,8 @@ var MCP_TOOL_CATALOG = [
       "title": "Google Maps Place Run Status",
       "readOnlyHint": true,
       "destructiveHint": false,
-      "idempotentHint": false,
-      "openWorldHint": true
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -23546,7 +23511,7 @@ var MCP_TOOL_CATALOG = [
     "name": "memory-capture",
     "category": "capture",
     "title": "Capture Governed Memory",
-    "description": "Strict normal-create path for durable memory. Before capture, list the complete tag vocabulary, call prepare-memory-write, run hybrid memory-search for related notes, and read the strongest link candidates. This tool refuses incomplete notes and invalid relationship-domain writes: projects need a project kind, tasks may be independent Inbox todos but must use a matched project when linked, deals need a known party, and draft emails need a pending approval state. It writes through memory-put, registers canonical tags, and verifies persisted content and props. Reserve memory-put for low-level migrations or deliberate edits.",
+    "description": "Strict normal-create path for ordinary durable memory. Before capture, list the complete tag vocabulary, call prepare-memory-write, run hybrid memory-search for related notes, and read the strongest link candidates. Research People/Organizations and CRM People/Organizations are rejected and must use their specialized tools. Projects need a project kind, tasks may be independent Inbox todos but must use a matched project when linked, deals need a known party, and draft emails need pending approval. It writes through memory-put, registers canonical tags, and verifies persisted content and props.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -23925,12 +23890,12 @@ var MCP_TOOL_CATALOG = [
     "name": "memory-put",
     "category": "memory",
     "title": "Put Memory Note",
-    "description": "Create or deliberately edit one note at a stable vault+path. On an existing note, first call memory-get, merge the requested change into its full body, and pass that complete body plus baseRevision: content is replace-all, while supplied props patch the stored props. A conflict returns the current body for reconciliation; never retry the stale full body unchanged. Use purpose-built tools instead of rewriting system-managed Agent Inbox, optimizer, or channel backing notes. For normal new People, Organizations, Deals, Projects, Tasks, or Communication records, use prepare-memory-write then memory-capture. For row-shaped datasets use table tools. Ordinary vaults are indexed and shareable; store real secrets only in a secure vault. Requires write scope.",
+    "description": "Create or deliberately edit one ordinary note at a stable vault+path. On an existing note, first call memory-get, merge the requested change into its full body, and pass that complete body plus baseRevision: content is replace-all, while supplied props patch the stored props. A conflict returns the current body for reconciliation; never retry the stale full body unchanged. Use purpose-built tools instead of rewriting system-managed Agent Inbox, optimizer, or channel backing notes. Research People/Organizations and CRM People/Organizations cannot be written here; use their specialized research-* or crm-* tools. For new Deals, Projects, Tasks, or Communication records, use prepare-memory-write then memory-capture. For row-shaped datasets use table tools. Ordinary vaults are indexed and shareable; store real secrets only in a secure vault. Requires write scope.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "vault": {
-          "description": "Vault to write to. Optional; defaults to the session active vault, then the first vault the caller is entitled to. On a default-provisioned account, pick the vault whose job matches the content (see the server instructions for the full 16-vault guide) rather than defaulting blindly \u2014 e.g. a lesson learned goes in Knowledge, the raw source it came from goes in Library, a broken feature goes in Issues, a named real-world initiative goes in Projects. Do not use this low-level tool to create ordinary People, Organizations, Deals, Projects, Tasks, or Communication records: first use prepare-memory-write then memory-capture so relationships and approval state are validated.",
+          "description": "Vault to write to. Optional; defaults to the session active vault, then the first vault the caller is entitled to. Pick the vault whose job matches the content; use prepare-memory-write for the live vault contract or list-vaults for vault inventory rather than defaulting blindly \u2014 e.g. a lesson learned goes in Knowledge, the raw source it came from goes in Library, a broken feature goes in Issues, a named real-world initiative goes in Projects. Research People/Organizations and CRM People/Organizations require their specialized tools and are always rejected here. For Deals, Projects, Tasks, or Communication records, first use prepare-memory-write then memory-capture so relationships and approval state are validated.",
           "type": "string"
         },
         "path": {
@@ -24773,7 +24738,7 @@ var MCP_TOOL_CATALOG = [
     "name": "prepare-memory-write",
     "category": "capture",
     "title": "Prepare Memory Write",
-    "description": "Mandatory planning pass for a normal new memory. First inspect the complete tag vocabulary with list-memory-tags; then this pass routes the note, returns the live template and natural vault relationships, resolves proposed tags, and shortlists interlinks. For People, Organizations, Deals, Projects, Tasks, and Communication, it also returns relationship and approval guidance: search existing records before linking, but do not invent a project or party. A Task can remain an independent Inbox todo. Use hybrid memory-search (3 focused queries, 50 fused candidates, bounded graph expansion, rerank to 30 by default) and read strong related notes before capture. This is an explicit AI workflow directive, not a claim of persisted call-order enforcement.",
+    "description": "Mandatory planning pass for ordinary non-entity memory. First inspect the complete tag vocabulary with list-memory-tags; then this pass routes the note, returns the live template and natural vault relationships, resolves proposed tags, and shortlists interlinks. Research People/Organizations and CRM People/Organizations are intentionally rejected here: use the matching research-*-capture or crm-*-upsert tool so generic writes cannot cross their authority boundary. Deals, Projects, Tasks, and Communication retain relationship and approval guidance. A Task can remain an independent Inbox todo. Use hybrid memory-search and read strong related notes before capture.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -24881,17 +24846,17 @@ var MCP_TOOL_CATALOG = [
     "name": "provision-defaults",
     "category": "vaults",
     "title": "Provision Default Vaults",
-    "description": "Provision the standard 16-vault memory structure (Ideas, Examples and Inspirations, Knowledge, Library, People, Organizations, Deals, Communication, Calendar, Tasks, Projects, Issues, Improvement Log, Experiments, Sprint, Skills) for an identity. Idempotent \u2014 existing records are untouched and existing vault contracts are refreshed. Optionally issues a fresh API key entitled to all 16. Requires admin scope.",
+    "description": "Provision the current default Memory vault structure for an identity. Requires admin scope. Repeated provisioning preserves existing records and refreshes vault contracts. With issueKey=true, every call issues a fresh key entitled to the default vaults; do not replay key issuance after an unknown outcome.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "granteeIdentity": {
           "type": "string",
           "minLength": 1,
-          "description": "Identity that should OWN the 16 default vaults (e.g. an email or user id)."
+          "description": "Identity that should own the current default vaults, such as an email or user id."
         },
         "issueKey": {
-          "description": "When true, also issue a new API key for the identity entitled to all 16 vaults and return its secret once. Default false.",
+          "description": "When true, issue a fresh API key for the default vaults and return its secret once. Default false. Repeating this call issues another key.",
           "type": "boolean"
         },
         "plan": {
@@ -24914,7 +24879,7 @@ var MCP_TOOL_CATALOG = [
       "title": "Provision Default Vaults",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -25250,6 +25215,12 @@ var MCP_TOOL_CATALOG = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "idempotencyKey": {
+          "description": "One logical request identity. Retry identical inputs with the same key to replay or recover without repeating provider work. Omit for a fresh intent; use the key returned with the result or transport error for retries.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
         "url": {
           "type": "string",
           "minLength": 1,
@@ -25283,6 +25254,12 @@ var MCP_TOOL_CATALOG = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "idempotencyKey": {
+          "description": "One logical request identity. Retry identical inputs with the same key to replay or recover without repeating provider work. Omit for a fresh intent; use the key returned with the result or transport error for retries.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
         "topic": {
           "type": "string",
           "minLength": 1,
@@ -25527,7 +25504,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-organization-capture",
     "category": "research",
     "title": "Capture Research Organization",
-    "description": "Create or revision-check a sourced Research Organization. Requires evidence and rejects CRM\u2026",
+    "description": "Create or revision-check a sourced Research Organization. Requires evidence and rejects CRM relationship, lifecycle, owner, consent, outreach, deal, and task state. This tool never creates a CRM account.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25539,7 +25516,7 @@ var MCP_TOOL_CATALOG = [
         "baseRevision": {
           "type": "integer",
           "minimum": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a Research Organization; for an edit, supply the current positive revision read from research-organization-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -25568,7 +25545,7 @@ var MCP_TOOL_CATALOG = [
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 2e3,
-                "description": "Original source URL or opaque artifact reference preserved as image provenance."
+                "description": "Source URL, retained artifact reference, or other source identifier supporting the Research evidence or field provenance."
               },
               "claim": {
                 "type": "string",
@@ -25648,7 +25625,7 @@ var MCP_TOOL_CATALOG = [
                   "type": "null"
                 }
               ],
-              "description": "Original source URL or opaque artifact reference preserved as image provenance."
+              "description": "Source URL, retained artifact reference, or other source identifier supporting the Research evidence or field provenance."
             },
             "observedAt": {
               "type": "string",
@@ -25699,7 +25676,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-organization-get",
     "category": "research",
     "title": "Get Research Organization",
-    "description": "Get one sourced Research Organization by stable entity ID with aliases, associations, and optional\u2026",
+    "description": "Get one sourced Research Organization by stable entity ID with aliases, associations, and optional explicit CRM counterpart link. Linking never copies fields.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25727,7 +25704,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-organization-search",
     "category": "research",
     "title": "Search Research Organizations",
-    "description": "Search sourced Research Organizations studied as knowledge. Never infer an organization from an email\u2026",
+    "description": "Search sourced Research Organizations studied as knowledge. Never infer an organization from an email domain and never use this for prospect/customer/vendor relationship operations; use crm-organization-search for managed accounts.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25744,7 +25721,7 @@ var MCP_TOOL_CATALOG = [
         "role": {
           "type": "string",
           "maxLength": 200,
-          "description": "Primary conversion or supporting observation role for this enabled mapping."
+          "description": "Optional sourced Research role to match on knowledge subjects; this is not a CRM relationship type."
         },
         "cursor": {
           "type": "string",
@@ -25773,7 +25750,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-person-capture",
     "category": "research",
     "title": "Capture Research Person",
-    "description": "Create or revision-check an independently governed Research Person for sourced knowledge, including\u2026",
+    "description": "Create or revision-check an independently governed Research Person for sourced knowledge, including historical figures. Requires evidence and rejects relationship type, lifecycle, owner, consent, outreach, deal, and task state. An email may be retained only as sourced evidence and never promotes the subject into CRM.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25785,7 +25762,7 @@ var MCP_TOOL_CATALOG = [
         "baseRevision": {
           "type": "integer",
           "minimum": 0,
-          "description": "Last revision read by the caller; supply it to reject an update if the record changed meanwhile."
+          "description": "Use 0 to create a Research Person; for an edit, supply the current positive revision read from research-person-get."
         },
         "idempotencyKey": {
           "type": "string",
@@ -25814,7 +25791,7 @@ var MCP_TOOL_CATALOG = [
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 2e3,
-                "description": "Original source URL or opaque artifact reference preserved as image provenance."
+                "description": "Source URL, retained artifact reference, or other source identifier supporting the Research evidence or field provenance."
               },
               "claim": {
                 "type": "string",
@@ -25894,7 +25871,7 @@ var MCP_TOOL_CATALOG = [
                   "type": "null"
                 }
               ],
-              "description": "Original source URL or opaque artifact reference preserved as image provenance."
+              "description": "Source URL, retained artifact reference, or other source identifier supporting the Research evidence or field provenance."
             },
             "observedAt": {
               "type": "string",
@@ -25945,7 +25922,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-person-get",
     "category": "research",
     "title": "Get Research Person",
-    "description": "Get one sourced Research Person by stable entity ID with aliases, associations, and an optional\u2026",
+    "description": "Get one sourced Research Person by stable entity ID with aliases, associations, and an optional explicit CRM counterpart link. This does not expose CRM operational state or copy counterpart fields.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25973,7 +25950,7 @@ var MCP_TOOL_CATALOG = [
     "name": "research-person-search",
     "category": "research",
     "title": "Search Research People",
-    "description": "Search sourced Research People, including historical figures and living subjects studied as knowledge\u2026",
+    "description": "Search sourced Research People, including historical figures and living subjects studied as knowledge. Never use this to find or manage contacts, prospects, customers, friends, coworkers, outreach, deals, or tasks; use crm-person-search for managed relationships. Results are owner-scoped, cursor-paged, and deterministically ordered.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -25990,7 +25967,7 @@ var MCP_TOOL_CATALOG = [
         "role": {
           "type": "string",
           "maxLength": 200,
-          "description": "Primary conversion or supporting observation role for this enabled mapping."
+          "description": "Optional sourced Research role to match on knowledge subjects; this is not a CRM relationship type."
         },
         "cursor": {
           "type": "string",
@@ -26075,7 +26052,7 @@ var MCP_TOOL_CATALOG = [
     "name": "resolve-memory-tags",
     "category": "tags",
     "title": "Resolve Memory Tags",
-    "description": "Resolve proposed concepts against the live tag vocabulary. Always inspect the complete vocabulary with list-memory-tags first. Returns reuse, review, create, or omit: spelling and singular/plural variants resolve to the canonical tag silently, while close and semantically related tags come back as ranked candidates for you to choose from. A new tag is appropriate only when no equivalent exists and the concept is central and reusable.",
+    "description": "Resolve proposed concepts against the live tag vocabulary. Inspect the complete vocabulary with list-memory-tags first. Returns reuse, review, create, or omit: spelling variants reuse canonical tags, while related tags return ranked candidates for review. With accept and write permission, saves the proposed spelling as an alias of the selected canonical tag. Create a new tag only when no equivalent exists and the concept is central and reusable.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -26128,7 +26105,7 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Resolve Memory Tags",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
       "idempotentHint": true,
       "openWorldHint": false
@@ -26323,7 +26300,7 @@ var MCP_TOOL_CATALOG = [
     "name": "search_serp",
     "category": "search",
     "title": "Google SERP Lookup",
-    "description": "Search Google. Light mode returns organic listings. Set mode:full on an unfiltered one-page search to request available same-page local-pack, forum, video, AI, entity, and PAA-preview features; includeLocalPack alone does not enable local-pack extraction. Feature status shows presence and completeness. One page is the default. Set pages:2 only when the user asks for two pages. Set recency:week or recency:month for Google's past-week or past-month filter. Filtered searches use a managed browser and return organic results only at 35 Credits per delivered page (70 for two). Unfiltered searches use browser as final backup. Browser/two-page results mark rich features unsupported. If page 2 fails, available page 1 is marked partial and billed for one page. Unfiltered light costs 20 Credits per delivered page, or 35 if a backup supplies it; one-page full costs 35; unfiltered two-page full costs 40 for organic results. Full does not open result sites, expand PAA, or open Maps profiles. Reuse the same idempotencyKey after an uncertain response. A saved serpIdentity keeps its 60-Credit search rate and cannot be combined with full mode. Call credits_info for current pricing and balance.",
+    "description": "Search Google. Light mode returns organic listings. Set mode:full on an unfiltered one-page search to request available same-page local-pack, forum, video, AI, entity, and PAA-preview features; includeLocalPack alone does not enable local-pack extraction. Feature status shows presence and completeness. One page is the default. Set pages:2 only when the user asks for two pages. Set recency:week or recency:month for Google's past-week or past-month filter. Filtered searches use a managed browser and return organic results only at 35 Credits per delivered page (70 for two). Unfiltered light tries twice, then an API fallback. Browser/two-page results mark rich features unsupported. If page 2 fails, available page 1 is marked partial and billed for one page. Unfiltered light costs 20 Credits per delivered page, or 35 if a backup supplies it; one-page full costs 35; unfiltered two-page full costs 40 for organic results. Full does not open result sites, expand PAA, or open Maps profiles. Reuse the same idempotencyKey after an uncertain response. A saved serpIdentity keeps its 60-Credit search rate and cannot be combined with full mode. Call credits_info for current pricing and balance.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -27480,8 +27457,7 @@ var MCP_TOOL_CATALOG = [
                 "showSourceRail",
                 "showGeneratedAt"
               ],
-              "additionalProperties": false,
-              "description": "Validated renderer configuration for the new immutable template version; arbitrary code is rejected."
+              "additionalProperties": false
             },
             {
               "type": "object",
@@ -27510,35 +27486,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "socialLinks": {
                       "type": "boolean",
-                      "description": "Curated public social profile links for the publication identity."
+                      "description": "Whether the renderer includes social profile links."
                     },
                     "authority": {
                       "type": "boolean",
-                      "description": "Source authority or ownership context supporting this content."
+                      "description": "Whether the renderer includes the authority section."
                     },
                     "consultation": {
                       "type": "boolean",
-                      "description": "Consultation-call presentation and link settings."
+                      "description": "Whether the renderer includes the consultation call-to-action."
                     },
                     "learning": {
                       "type": "boolean",
-                      "description": "Learning-section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the learning section."
                     },
                     "services": {
                       "type": "boolean",
-                      "description": "Source-backed services associated with the business listing."
+                      "description": "Whether the renderer includes the services section."
                     },
                     "proof": {
                       "type": "boolean",
-                      "description": "Proof-section content and evidence references."
+                      "description": "Whether the renderer includes the proof section."
                     },
                     "finalCta": {
                       "type": "boolean",
-                      "description": "Final call-to-action content shown after the authored collection."
+                      "description": "Whether the renderer includes the final call-to-action."
                     }
                   },
                   "required": [
@@ -27560,8 +27536,7 @@ var MCP_TOOL_CATALOG = [
                 "showGeneratedAt",
                 "featureFlags"
               ],
-              "additionalProperties": false,
-              "description": "Validated renderer configuration for the new immutable template version; arbitrary code is rejected."
+              "additionalProperties": false
             },
             {
               "type": "object",
@@ -27633,7 +27608,7 @@ var MCP_TOOL_CATALOG = [
                         "modern-sans",
                         "humanist-sans"
                       ],
-                      "description": "Registered self-contained display-font family selected for prominent headings."
+                      "description": "Registered self-contained body-font family selected for article and paragraph text."
                     }
                   },
                   "required": [
@@ -27647,35 +27622,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "socialLinks": {
                       "type": "boolean",
-                      "description": "Curated public social profile links for the publication identity."
+                      "description": "Whether the renderer includes social profile links."
                     },
                     "authority": {
                       "type": "boolean",
-                      "description": "Source authority or ownership context supporting this content."
+                      "description": "Whether the renderer includes the authority section."
                     },
                     "consultation": {
                       "type": "boolean",
-                      "description": "Consultation-call presentation and link settings."
+                      "description": "Whether the renderer includes the consultation call-to-action."
                     },
                     "learning": {
                       "type": "boolean",
-                      "description": "Learning-section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the learning section."
                     },
                     "services": {
                       "type": "boolean",
-                      "description": "Source-backed services associated with the business listing."
+                      "description": "Whether the renderer includes the services section."
                     },
                     "proof": {
                       "type": "boolean",
-                      "description": "Proof-section content and evidence references."
+                      "description": "Whether the renderer includes the proof section."
                     },
                     "finalCta": {
                       "type": "boolean",
-                      "description": "Final call-to-action content shown after the authored collection."
+                      "description": "Whether the renderer includes the final call-to-action."
                     }
                   },
                   "required": [
@@ -27697,8 +27672,7 @@ var MCP_TOOL_CATALOG = [
                 "showGeneratedAt",
                 "featureFlags"
               ],
-              "additionalProperties": false,
-              "description": "Validated renderer configuration for the new immutable template version; arbitrary code is rejected."
+              "additionalProperties": false
             },
             {
               "type": "object",
@@ -27731,35 +27705,35 @@ var MCP_TOOL_CATALOG = [
                   "properties": {
                     "breakingTicker": {
                       "type": "boolean",
-                      "description": "Optional short breaking-news ticker shown by the renderer."
+                      "description": "Whether the renderer includes the breaking-news ticker."
                     },
                     "navigation": {
                       "type": "boolean",
-                      "description": "Validated navigation labels and destinations for the rendered site."
+                      "description": "Whether the renderer includes the navigation section."
                     },
                     "leadGrid": {
                       "type": "boolean",
-                      "description": "Lead-story grid configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the lead-story grid."
                     },
                     "latestNews": {
                       "type": "boolean",
-                      "description": "Latest-news section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the latest-news section."
                     },
                     "categorySections": {
                       "type": "boolean",
-                      "description": "Ordered category sections and their assigned article references."
+                      "description": "Whether the renderer includes article sections grouped by category."
                     },
                     "newsletter": {
                       "type": "boolean",
-                      "description": "Newsletter-callout presentation and subscription link settings."
+                      "description": "Whether the renderer includes the newsletter call-to-action."
                     },
                     "pressRoom": {
                       "type": "boolean",
-                      "description": "Press-room section configuration for the editorial renderer."
+                      "description": "Whether the renderer includes the press-room section."
                     },
                     "trustFooter": {
                       "type": "boolean",
-                      "description": "Trust and provenance footer configuration for the rendered site."
+                      "description": "Whether the renderer includes the trust and provenance footer."
                     }
                   },
                   "required": [
@@ -27782,8 +27756,7 @@ var MCP_TOOL_CATALOG = [
                 "showBylines",
                 "featureFlags"
               ],
-              "additionalProperties": false,
-              "description": "Validated renderer configuration for the new immutable template version; arbitrary code is rejected."
+              "additionalProperties": false
             },
             {
               "type": "object",
@@ -27857,8 +27830,7 @@ var MCP_TOOL_CATALOG = [
                 "showGeneratedAt",
                 "featureFlags"
               ],
-              "additionalProperties": false,
-              "description": "Validated renderer configuration for the new immutable template version; arbitrary code is rejected."
+              "additionalProperties": false
             }
           ]
         },
@@ -28412,14 +28384,14 @@ var MCP_TOOL_CATALOG = [
     "name": "video_frame_analysis",
     "category": "video",
     "title": "Video Breakdown (frame-by-frame + transcript)",
-    "description": "Produce a deep frame-by-frame + transcript breakdown of a video \u2014 pacing, hook, visual style, and how to replicate it. Accepts a YouTube, Facebook, Instagram, TikTok, or Vimeo URL directly (downloaded for you), or a direct video file URL (.mp4/.webm/.mov). Costs $1 per 120 frames requested (max 480 = $4; refunded down if the video can't use them; refunded fully on failure): returns a runId immediately; poll video_frame_analysis_status until done. Videos up to 30 minutes.",
+    "description": "Analyze a video's visuals and transcript: pacing, hook, style, and how to replicate it. For spoken text only, use the platform transcription tool. Accepts YouTube, Facebook, Instagram, TikTok, or Vimeo URLs, or direct video files (.mp4/.webm/.mov), up to 60 minutes. Reserves 6667 Credits per requested 120-frame tier, up to 480 frames. Unused frame tiers are refunded; a failed run's frame charge is refunded. Analysis-model usage is billed separately, including usage before a failure. Returns a runId immediately; poll video_frame_analysis_status until done or failed for the report and settlement. Call credits_info for current rates and balance.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "sourceUrl": {
           "type": "string",
           "minLength": 1,
-          "description": "A YouTube, Facebook, Instagram, TikTok, or Vimeo URL (downloaded automatically), or a direct video file URL (.mp4/.webm/.mov). Videos up to 30 minutes are supported."
+          "description": "A YouTube, Facebook, Instagram, TikTok, or Vimeo URL (downloaded automatically), or a direct video file URL (.mp4/.webm/.mov). Videos up to 60 minutes are supported."
         },
         "intervalS": {
           "description": "Preferred seconds between sampled frames (1-30, default 2). Automatically widened for long videos so the whole duration is covered within the frame budget.",
@@ -28428,7 +28400,7 @@ var MCP_TOOL_CATALOG = [
           "maximum": 30
         },
         "maxFrames": {
-          "description": "Max frames analyzed (<=480, default 120). $1 per 120 frames requested \u2014 120=$1 \u2026 480=$4 \u2014 automatically refunded down if the video cannot use them (minimum 1s between frames). Frames are spread evenly across the whole video.",
+          "description": "Max frames analyzed (<=480, default 120). Reserves the number of 120-frame tiers requested; unused tiers are refunded. Analysis-model usage is billed separately. Frames are spread evenly across the whole video, with at least 1 second between frames.",
           "type": "integer",
           "minimum": 1,
           "maximum": 480
@@ -28465,7 +28437,7 @@ var MCP_TOOL_CATALOG = [
     "name": "video_frame_analysis_status",
     "category": "video",
     "title": "Video Breakdown Status",
-    "description": 'Check progress of a video breakdown started with video_frame_analysis, using its runId. Free to call. When status is "done" it returns the full report and vault path; stop polling on "done" or "failed". Reports the billed tier reconciliation when done.',
+    "description": "Check the original runId returned by video_frame_analysis without starting another analysis. Returns progress and, when done, the full report and Memory path. Terminal checks reconcile frame-tier refunds and settle incurred analysis-model usage; a failed run can still have model-usage charges. Repeated checks do not duplicate settlement. Stop polling on done or failed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -28482,7 +28454,7 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Video Breakdown Status",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
       "idempotentHint": true,
       "openWorldHint": false
@@ -28492,14 +28464,14 @@ var MCP_TOOL_CATALOG = [
     "name": "video-analyze-start",
     "category": "video",
     "title": "Start Video Breakdown",
-    "description": "Start a deep async breakdown of a video: samples frames, transcribes audio, and runs parallel analyses (summary, pacing, WPM, topic outline, key points, hook analysis, visual style, replication recipe) into one saved report. Returns a runId immediately \u2014 poll video-analyze-status. Accepts a YouTube, Facebook, Instagram, TikTok, or Vimeo URL directly (downloaded for you), or a direct video file URL (.mp4/.webm/.mov). Videos up to 1 hour.",
+    "description": "Queue a video breakdown directly in Memory and save its report to a writable vault. Prefer video_frame_analysis for standard Scraper analysis with published credit pricing. Accepts supported social video or direct file URLs, up to 60 minutes; samples frames, transcribes audio and analyzes pacing, topics, hooks and visual style. Each call creates a new run. Preserve the returned runId and poll video-analyze-status rather than starting replacement work after an unknown outcome.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "sourceUrl": {
           "type": "string",
           "format": "uri",
-          "description": "A YouTube, Facebook, Instagram, TikTok, or Vimeo URL (downloaded automatically), or a direct video file URL (.mp4/.webm/.mov/.gif)."
+          "description": "A YouTube, Facebook, Instagram, TikTok, or Vimeo URL, or a direct video file URL (.mp4/.webm/.mov/.gif). Maximum duration: 60 minutes."
         },
         "intervalS": {
           "description": "Preferred seconds between sampled frames (1-30). Default 2. For long videos the interval is automatically widened so the whole video is covered within the frame budget. Lower = denser sampling where the video is short enough to allow it.",
@@ -28544,7 +28516,7 @@ var MCP_TOOL_CATALOG = [
     "name": "video-analyze-status",
     "category": "video",
     "title": "Video Breakdown Status",
-    "description": "Check the status of a video breakdown started with video-analyze-start. Returns phase and frame progress; when done, returns the saved report's vault path and markdown. Poll every few seconds until done or failed.",
+    "description": "Inspect an existing Memory video breakdown using its runId. Returns phase, frame progress and reported analysis-model costUsd; when done, returns the saved report path and Markdown. Can mark a stale run as failed; does not start new analysis. For runs started with video_frame_analysis, use video_frame_analysis_status to reconcile the original Scraper charges and refunds.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -28560,7 +28532,7 @@ var MCP_TOOL_CATALOG = [
     },
     "annotations": {
       "title": "Video Breakdown Status",
-      "readOnlyHint": true,
+      "readOnlyHint": false,
       "destructiveHint": false,
       "idempotentHint": true,
       "openWorldHint": false
@@ -28842,7 +28814,7 @@ var MCP_TOOL_CATALOG = [
     "name": "youtube_transcribe",
     "category": "youtube",
     "title": "YouTube Transcription",
-    "description": "Fetch and transcribe captions from a YouTube video. Pass videoId from youtube_harvest, or a url the user pasted. Returns full transcript, timestamped chunks, and word count.",
+    "description": "Get a YouTube video's full transcript, timestamped chunks, and word count. Tries available captions first, then speech-to-text from resolved audio when captions cannot be retrieved and audio retrieval is available. Pass a videoId returned by youtube_harvest or the user's URL; set language for non-English speech. Costs 200 Credits plus 2 per rounded-up minute of video whichever transcription path succeeds. The duration hold is reconciled after completion and refunded on failure. Call credits_info for current rates and balance.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -29178,6 +29150,15 @@ async function run(fn) {
     process.exitCode = 1;
   }
 }
+function observedInstallChannel(executablePath = process.argv[1]) {
+  if (!executablePath) return void 0;
+  let resolvedPath = executablePath;
+  try {
+    resolvedPath = realpathSync(executablePath);
+  } catch {
+  }
+  return [executablePath, resolvedPath].some((path) => path.replace(/\\/g, "/").includes("/_npx/")) ? "npx" : void 0;
+}
 function createProgram(fetchImpl = globalThis.fetch) {
   function resolveApiKey(cmd) {
     const opts = cmd.optsWithGlobals();
@@ -29188,11 +29169,36 @@ function createProgram(fetchImpl = globalThis.fetch) {
     }
     return key;
   }
-  function client(cmd) {
-    return new ScraperClient({ apiKey: resolveApiKey(cmd), fetch: fetchImpl });
+  function client(cmd, surface = "rest") {
+    const opts = cmd.optsWithGlobals();
+    if (opts.baseUrl !== void 0) {
+      let baseUrl;
+      try {
+        baseUrl = new URL(opts.baseUrl);
+      } catch {
+        throw new Error("--base-url must be an HTTP(S) URL without credentials, query or fragment");
+      }
+      if (!["http:", "https:"].includes(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash) {
+        throw new Error("--base-url must be an HTTP(S) URL without credentials, query or fragment");
+      }
+    }
+    if (opts.aiModel !== void 0 && !/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,79}$/.test(opts.aiModel)) {
+      throw new Error("--ai-model must be a model identifier of 1\u201380 letters, digits, dots, underscores, colons, slashes or hyphens, starting with a letter or digit");
+    }
+    return new ScraperClient({
+      apiKey: resolveApiKey(cmd),
+      baseUrl: opts.baseUrl?.replace(/\/+$/, ""),
+      fetch: fetchImpl,
+      clientAttribution: {
+        surface,
+        installChannel: opts.installChannel ?? observedInstallChannel(),
+        aiClient: opts.aiClient,
+        aiModel: opts.aiModel
+      }
+    });
   }
   const program = new Command();
-  program.name("mcpscraper").description(`CLI for all ${MCP_TOOL_COUNT} mcpscraper.dev MCP tools plus ergonomic shortcuts`).version(CLI_VERSION).option("--api-key <key>", "mcpscraper.dev API key (or set MCPSCRAPER_API_KEY)");
+  program.name("mcpscraper").description(`CLI for all ${MCP_TOOL_COUNT} mcpscraper.dev MCP tools plus ergonomic shortcuts`).version(CLI_VERSION).option("--api-key <key>", "mcpscraper.dev API key (or set MCPSCRAPER_API_KEY)").addOption(new Option("--base-url <url>", "API base URL for a selected deployment (or MCPSCRAPER_BASE_URL)").env("MCPSCRAPER_BASE_URL")).addOption(new Option("--install-channel <channel>", "declared installation channel (or MCP_SCRAPER_INSTALL_CHANNEL)").choices(["npx", "npm", "source", "mcpb"]).env("MCP_SCRAPER_INSTALL_CHANNEL")).addOption(new Option("--ai-client <client>", "declared AI client (or MCP_SCRAPER_AI_CLIENT)").choices(["claude", "claude-desktop", "claude-code", "chatgpt", "codex", "cursor", "gemini", "other"]).env("MCP_SCRAPER_AI_CLIENT")).addOption(new Option("--ai-model <model>", "declared model identifier (or MCP_SCRAPER_AI_MODEL)").env("MCP_SCRAPER_AI_MODEL"));
   program.command("search <query>").description("Run a Google SERP search").option("--location <location>", "geographic location to search from").option("--json", "print the complete JSON result (inline binary data is saved and replaced with file metadata)").action(async (query, opts, cmd) => {
     await run(async () => {
       const result = await client(cmd).searchSerp({
@@ -29375,7 +29381,7 @@ ${catalog.length}/${MCP_TOOL_COUNT} tools`);
     if (!tool) throw new Error(`Unknown tool "${name}". Run "mcpscraper tools list" for all ${MCP_TOOL_COUNT} names.`);
     console.log(JSON.stringify(tool, null, 2));
   });
-  tools.command("call <name>").description(`Call any of the ${MCP_TOOL_COUNT} MCP tools by exact wire name`).option("--args <json>", "tool arguments as a JSON object", "{}").option("--yes", "confirm a tool marked destructive").option("--media-dir <path>", "directory for inline MCP images (defaults to ~/Downloads/mcp-scraper)").option("--json", "print raw JSON").action(async (name, opts, cmd) => {
+  tools.command("call <name>").description(`Call any of the ${MCP_TOOL_COUNT} MCP tools by exact wire name`).option("--args <json>", "tool arguments as a JSON object", "{}").option("--yes", "confirm a tool marked destructive").option("--media-dir <path>", "directory for inline MCP images (defaults to ~/Downloads/mcp-scraper)").option("--json", "print raw JSON").option("--raw-result", "preserve the MCP envelope, metadata and resource links; inline binary becomes saved-file metadata").action(async (name, opts, cmd) => {
     await run(async () => {
       const tool = MCP_TOOL_CATALOG.find((entry) => entry.name === name);
       if (!tool) throw new Error(`Unknown tool "${name}". Run "mcpscraper tools list" for all ${MCP_TOOL_COUNT} names.`);
@@ -29383,9 +29389,10 @@ ${catalog.length}/${MCP_TOOL_COUNT} tools`);
       if (annotations.destructiveHint && !opts.yes) {
         throw new Error(`Tool "${name}" is marked destructive. Re-run with --yes to confirm.`);
       }
-      const rawResult = await client(cmd).tools.callToolResult(name, parseToolArgs(opts.args));
-      const result = printableToolResult(saveToolMedia(name, rawResult, opts.mediaDir));
-      if (opts.json || typeof result !== "string") console.log(JSON.stringify(result, null, 2));
+      const rawResult = await client(cmd, "mcp-http").tools.callToolResult(name, parseToolArgs(opts.args));
+      const savedResult = saveToolMedia(name, rawResult, opts.mediaDir);
+      const result = opts.rawResult ? savedResult : printableToolResult(savedResult);
+      if (opts.json || opts.rawResult || typeof result !== "string") console.log(JSON.stringify(result, null, 2));
       else console.log(result);
     });
   });
@@ -29405,5 +29412,6 @@ if (isMain) {
 }
 export {
   createProgram,
-  isMainModule
+  isMainModule,
+  observedInstallChannel
 };