@leadbay/mcp 0.5.0 → 0.6.1

package/dist/{chunk-MCTWP5F2.js → chunk-NLG7GUZ3.js}

@@ -535,6 +535,13 @@ function parseRetryAfter(value) {
 // ../core/dist/tools/login.js
 var login = {
   name: "leadbay_login",
+  annotations: {
+    title: "Mint a Leadbay bearer token",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Log in to Leadbay with email and password. Auto-detects region (us|fr) \u2014 the user does not need to know which backend their account lives on. When to use: at the start of a session if no token is preconfigured (cfg.token / LEADBAY_TOKEN). When NOT to use: if a token is already preconfigured (you'll just overwrite it). The user needs a Leadbay account \u2014 they can register at https://wow.leadbay.ai/?register=true",
   inputSchema: {
     type: "object",
@@ -542,7 +549,8 @@ var login = {
       email: { type: "string", description: "Leadbay account email address" },
       password: { type: "string", description: "Leadbay account password" }
     },
-    required: ["email", "password"]
+    required: ["email", "password"],
+    additionalProperties: false
   },
   execute: async (client, params, ctx) => {
     const cleanPassword = params.password.replace(/\\(.)/g, "$1");
@@ -578,10 +586,37 @@ var login = {
 // ../core/dist/tools/list-lenses.js
 var listLenses = {
   name: "leadbay_list_lenses",
+  annotations: {
+    title: "List active lenses",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "List all available Leadbay lenses (saved lead search configurations). Each lens defines a different target market or buyer segment. The lens with is_last_active=true is used by default for lead discovery. When to use: when the user wants to switch lens or asks 'what lenses do I have'. When NOT to use: in normal flow \u2014 composites auto-resolve the active lens via /me.last_requested_lens.",
   inputSchema: {
     type: "object",
-    properties: {}
+    properties: {},
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      lenses: {
+        type: "array",
+        description: "Available lenses. Each: {id, name, is_last_active, description}.",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "number" },
+            name: { type: "string" },
+            is_last_active: { type: "boolean" },
+            description: { type: ["string", "null"] }
+          }
+        }
+      }
+    },
+    required: ["lenses"]
   },
   execute: async (client) => {
     const lenses = await client.request("GET", "/lenses");
@@ -599,6 +634,13 @@ var listLenses = {
 // ../core/dist/tools/discover-leads.js
 var discoverLeads = {
   name: "leadbay_discover_leads",
+  annotations: {
+    title: "Discover leads in a lens",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Get AI-recommended leads from Leadbay. Returns paginated lead summaries with scores, AI summaries, tags, and recommended contacts. When to use: low-level when you need raw paginated wishlist access without the qualification_summary attached by leadbay_pull_leads. When NOT to use: as the agent's default lead-discovery entry point \u2014 use leadbay_pull_leads, which adds a one-line qualification summary per lead.",
   inputSchema: {
     type: "object",
@@ -615,13 +657,18 @@ var discoverLeads = {
         type: "number",
         description: "Results per page, max 50 (default: 20)"
       }
-    }
+    },
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
     const page = params.page ?? 0;
     const count = Math.min(params.count ?? 20, 50);
     const res = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=${count}&page=${page}&contacts=true`);
+    const totalPages = res.pagination?.pages ?? 0;
+    const currentPage = res.pagination?.page ?? page;
+    const hasMore = currentPage < totalPages - 1;
+    const nextPage = hasMore ? currentPage + 1 : null;
     return {
       leads: res.items.map((lead) => ({
         id: lead.id,
@@ -641,7 +688,9 @@ var discoverLeads = {
         recommended_contact_title: lead.recommended_contact_title ?? null,
         recommended_contact: lead.recommended_contact ?? null
       })),
-      pagination: res.pagination
+      pagination: res.pagination,
+      has_more: hasMore,
+      next_page: nextPage
     };
   }
 };
@@ -649,6 +698,13 @@ var discoverLeads = {
 // ../core/dist/tools/get-lead-profile.js
 var getLeadProfile = {
   name: "leadbay_get_lead_profile",
+  annotations: {
+    title: "Read a lead profile",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Get a full lead profile including company details, AI qualification scores, web insights, and contacts. When to use: low-level \u2014 for fine-grained access to the raw shape of the lead profile. When NOT to use: as the agent's default lead-detail tool \u2014 use leadbay_research_lead, which structures the data top-down (qualification first, then signals, then firmographics, then contacts, then engagement) and reshapes web_fetch.content into a stable array form.",
   inputSchema: {
     type: "object",
@@ -662,7 +718,30 @@ var getLeadProfile = {
         description: "Lens ID (optional, auto-resolves to active lens)"
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      lead: {
+        type: "object",
+        description: "Lead basics: id, name, score, ai_agent_lead_score, location, description, short_description, size, website, logo, ai_summary, split_ai_summary, tags, phone_numbers, keywords, contacts_count, recommended_contact_title, recommended_contact, web_fetch_in_progress."
+      },
+      qualification: {
+        type: ["array", "null"],
+        description: "Per-question AI qualification answers ({question, score, response, computed_at, outdated_at}), or null if none.",
+        items: { type: "object" }
+      },
+      contacts: {
+        type: "array",
+        description: "Merged org+paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}.",
+        items: { type: "object" }
+      },
+      web_insights: { description: "Latest /web_fetch content (string) or null." },
+      web_insights_fetched_at: { description: "ISO timestamp of /web_fetch (string) or null." }
+    },
+    required: ["lead", "contacts"]
   },
   execute: async (client, params) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
@@ -751,6 +830,13 @@ var getLeadProfile = {
 // ../core/dist/tools/get-contacts.js
 var getContacts = {
   name: "leadbay_get_contacts",
+  annotations: {
+    title: "Read enriched contacts",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Get contacts for a lead, including enriched email and phone data. Returns both organization contacts and enrichable contacts with IDs. When to use: to check enrichment status (contact.enrichment.done) on individual leads after a bulk enrichment was launched, or to find the contact_id needed by leadbay_enrich_contacts. When NOT to use: as a substitute for leadbay_research_lead, which already includes enriched contacts in its return.",
   inputSchema: {
     type: "object",
@@ -760,7 +846,8 @@ var getContacts = {
         description: "Lead UUID (required)"
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const [orgResult, paidResult] = await Promise.allSettled([
@@ -803,8 +890,26 @@ var getContacts = {
 // ../core/dist/tools/get-quota.js
 var getQuota = {
   name: "leadbay_get_quota",
+  annotations: {
+    title: "Read quota status",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read remaining quota / spend across daily, weekly, monthly windows for the org's resources (llm_completion, ai_rescore, web_fetch). Each entry shows current_units vs max_units and resets_at. When to use: after a 429 error, to explain to the user which window was hit and when it resets. When NOT to use: as a pre-flight gate before bulk operations \u2014 operations themselves return 429 with hints; this tool is for diagnostics, not gating.",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      plan: { type: ["string", "null"], description: "Org plan tier (e.g., FREE, PRO)." },
+      windows: {
+        type: "array",
+        description: "Per-resource per-window limits. Each: {resource, window, current_units, max_units, resets_at}.",
+        items: { type: "object" }
+      }
+    }
+  },
   execute: async (client) => {
     const orgId = await client.resolveOrgId();
     return await client.request("GET", `/organizations/${orgId}/quota_status`);
@@ -814,10 +919,41 @@ var getQuota = {
 // ../core/dist/tools/get-taste-profile.js
 var getTasteProfile = {
   name: "leadbay_get_taste_profile",
+  annotations: {
+    title: "Read the org's taste profile",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Get the user's Ideal Buyer Profile, purchase intent tags, and qualification questions. When to use: at the very start of a session to understand what kind of leads the user is looking for. Data is cached. When NOT to use: per-lead \u2014 leadbay_research_lead already includes the per-lead qualification answers (which are scored against these org-level questions).",
   inputSchema: {
     type: "object",
-    properties: {}
+    properties: {},
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      ideal_buyer_profile: {
+        description: "Ideal Buyer Profile {summary, key_characteristics, anti_patterns} or null when none."
+      },
+      purchase_intent_tags: {
+        type: "array",
+        description: "Tags describing buying signals. Each: {display_name, description, score, reasoning}.",
+        items: { type: "object" }
+      },
+      qualification_questions: {
+        type: "array",
+        description: "Questions Leadbay asks for each lead. Each: {question}.",
+        items: { type: "object" }
+      },
+      hint: {
+        type: "string",
+        description: "Operator note when the taste profile is empty (no_profile state)."
+      }
+    },
+    required: ["purchase_intent_tags", "qualification_questions"]
   },
   execute: async (client) => {
     const profile = await client.resolveTasteProfile();
@@ -847,6 +983,13 @@ var getTasteProfile = {
 // ../core/dist/tools/qualify-lead.js
 var qualifyLead = {
   name: "leadbay_qualify_lead",
+  annotations: {
+    title: "Qualify a single lead",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Trigger AI qualification for a single lead (web fetch + AI rescore). The operation is asynchronous \u2014 results take ~60s. When to use: low-level. When NOT to use: as the agent's bulk-qualify path \u2014 use leadbay_bulk_qualify_leads, which paginates past already-qualified leads, fan-outs, polls, and bails out cleanly on 429.",
   optional: true,
   inputSchema: {
@@ -861,7 +1004,8 @@ var qualifyLead = {
         description: "Force re-fetch even if recent data exists (default: false)"
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const force = params.forceFetch ?? false;
@@ -876,6 +1020,13 @@ var qualifyLead = {
 // ../core/dist/tools/enrich-contacts.js
 var enrichContacts = {
   name: "leadbay_enrich_contacts",
+  annotations: {
+    title: "Enrich contacts for a lead",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Order email and/or phone enrichment for a specific contact. When to use: when you have a specific contact_id (from leadbay_get_contacts) and want to enrich just that one. When NOT to use: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow.",
   optional: true,
   inputSchema: {
@@ -898,7 +1049,8 @@ var enrichContacts = {
         description: "Enrich phone number (default: true)"
       }
     },
-    required: ["leadId", "contactId"]
+    required: ["leadId", "contactId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const email = params.email ?? true;
@@ -942,6 +1094,13 @@ var enrichContacts = {
 // ../core/dist/tools/add-note.js
 var addNote = {
   name: "leadbay_add_note",
+  annotations: {
+    title: "Add a note on a lead",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Add a note to a lead. Notes are visible to the whole organization in Leadbay. When to use: low-level \u2014 for free-form notes not tied to outreach actions. When NOT to use: to log an outreach action \u2014 use leadbay_report_outreach, which requires verification (gmail/calendar/user_confirmed) to prevent hallucinated outreach poisoning the SDR pipeline.",
   optional: true,
   inputSchema: {
@@ -956,7 +1115,17 @@ var addNote = {
         description: "Note text (max 4095 characters)"
       }
     },
-    required: ["leadId", "note"]
+    required: ["leadId", "note"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "Note id assigned by the backend." },
+      note: { type: "string", description: "Echoed note text (truncated to 4095 chars)." },
+      created_at: { type: "string", description: "ISO timestamp of creation." }
+    },
+    required: ["id", "note", "created_at"]
   },
   execute: async (client, params) => {
     if (!params.note || params.note.trim().length === 0) {
@@ -975,6 +1144,13 @@ var addNote = {
 // ../core/dist/tools/get-lead-activities.js
 var getLeadActivities = {
   name: "leadbay_get_lead_activities",
+  annotations: {
+    title: "Read a lead's activity feed",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Get prospecting activity history for a lead (emails sent, calls made, status changes, notes). When to use: to avoid redundant outreach and understand where this lead is in the sales process. When NOT to use: when leadbay_research_lead has already been called \u2014 it includes recent prospecting actions in its engagement block.",
   inputSchema: {
     type: "object",
@@ -988,7 +1164,29 @@ var getLeadActivities = {
         description: "Number of activities to return, max 100 (default: 50)"
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      activities: {
+        type: "array",
+        description: "Activity entries. Each: {type, date}. Older activities trimmed by `count`.",
+        items: {
+          type: "object",
+          properties: {
+            type: { type: "string" },
+            date: { type: "string" }
+          }
+        }
+      },
+      total: {
+        type: "number",
+        description: "Total activity count for this lead (across all pages)."
+      }
+    },
+    required: ["activities", "total"]
   },
   execute: async (client, params) => {
     const count = Math.min(params.count ?? 50, 100);
@@ -1006,13 +1204,21 @@ var getLeadActivities = {
 // ../core/dist/tools/get-lens-filter.js
 var getLensFilter = {
   name: "leadbay_get_lens_filter",
+  annotations: {
+    title: "Read lens filter",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the firmographic filter (sectors, sizes, locations) currently applied to a lens. When to use: before adjusting an audience \u2014 see what's already restricted so changes are diffs, not full replacements. When NOT to use: to actually apply changes \u2014 use the leadbay_adjust_audience composite, which handles permissions transparently.",
   inputSchema: {
     type: "object",
     properties: {
       lensId: { type: "number", description: "Lens id (required)" }
     },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     return await client.request("GET", `/lenses/${params.lensId}/filter`);
@@ -1022,11 +1228,19 @@ var getLensFilter = {
 // ../core/dist/tools/get-lens-scoring.js
 var getLensScoring = {
   name: "leadbay_get_lens_scoring",
+  annotations: {
+    title: "Read lens scoring",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the AI-scoring criteria configured on a lens (what makes a lead score 100 vs 30). When to use: when explaining why a lead got the score it did. When NOT to use: to mutate scoring \u2014 that's an admin/setup operation, not part of the agent loop.",
   inputSchema: {
     type: "object",
     properties: { lensId: { type: "number", description: "Lens id (required)" } },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     return await client.request("GET", `/lenses/${params.lensId}/scoring`);
@@ -1036,6 +1250,13 @@ var getLensScoring = {
 // ../core/dist/tools/list-sectors.js
 var listSectors = {
   name: "leadbay_list_sectors",
+  annotations: {
+    title: "List sector taxonomy",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "List the sector taxonomy (id + display name in the requested language). When to use: to resolve a free-text sector name (e.g. 'Healthcare') into the sector ids that leadbay_adjust_audience needs. Default: lang follows the caller's language; includeInvisible=false returns ~1,091 visible sectors. When NOT to use: when you already have sector ids \u2014 pass them directly.",
   inputSchema: {
     type: "object",
@@ -1045,7 +1266,8 @@ var listSectors = {
         type: "boolean",
         description: "Include sectors hidden from the UI (default false; ~91k items if true)"
       }
-    }
+    },
+    additionalProperties: false
   },
   execute: async (client, params) => {
     let lang = params.lang;
@@ -1066,8 +1288,36 @@ var listSectors = {
 // ../core/dist/tools/get-user-prompt.js
 var getUserPrompt = {
   name: "leadbay_get_user_prompt",
+  annotations: {
+    title: "Read user prompt",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the org's intelligence-refinement prompt (free-text instruction that steers lead recommendations beyond firmographics). Returns null if none is set (the backend returns 204 in that case). When to use: to know what's currently steering the agent's recommendations before suggesting a refine. When NOT to use: to set/change the prompt \u2014 use leadbay_refine_prompt.",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      prompt: {
+        description: "Free-text instruction (string) or null when unset."
+      },
+      set: {
+        type: "boolean",
+        description: "True when a prompt is set; false when nothing has been configured."
+      },
+      // When the backend returns a populated UserPromptPayload, additional
+      // fields may be spread into the response. The asserter is permissive
+      // — declare common fields here so the conformance check accepts the
+      // backend's full shape.
+      user_prompt: {
+        description: "Backend-form copy of the prompt text (when set)."
+      },
+      created_at: { type: ["string", "null"] },
+      updated_at: { type: ["string", "null"] }
+    }
+  },
   execute: async (client) => {
     const orgId = await client.resolveOrgId();
     const prompt = await client.request("GET", `/organizations/${orgId}/user_prompt`);
@@ -1078,8 +1328,38 @@ var getUserPrompt = {
 // ../core/dist/tools/get-clarification.js
 var getClarification = {
   name: "leadbay_get_clarification",
+  annotations: {
+    title: "Read pending clarification",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Check whether Leadbay has a pending clarification question \u2014 a question raised when refining the intelligence prompt produced contradictory or ambiguous criteria. Returns null when nothing is pending (the backend returns 204). When to use: after leadbay_refine_prompt, to see if Leadbay needs the user to disambiguate. When NOT to use: to answer the question \u2014 use leadbay_answer_clarification.",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      pending: {
+        type: "boolean",
+        description: "False when no clarification is pending (and `clarification` is null)."
+      },
+      clarification: {
+        description: "ClarificationPayload (object) when pending, otherwise null."
+      },
+      // When the backend returns a populated ClarificationPayload, the keys
+      // are spread directly into the response. The asserter is permissive —
+      // declare the union of keys here so the conformance check doesn't
+      // flag drift.
+      id: { type: "string", description: "Clarification id (when pending)." },
+      question: { type: "string", description: "Question text (when pending)." },
+      options: {
+        type: "array",
+        description: "Picker options (when pending). Each: {id, label}.",
+        items: { type: "object" }
+      }
+    }
+  },
   execute: async (client) => {
     const orgId = await client.resolveOrgId();
     const c = await client.request("GET", `/organizations/${orgId}/clarifications`);
@@ -1090,11 +1370,19 @@ var getClarification = {
 // ../core/dist/tools/get-lead-notes.js
 var getLeadNotes = {
   name: "leadbay_get_lead_notes",
+  annotations: {
+    title: "Read lead notes",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read existing notes on a lead \u2014 context the human team or prior agent runs have already captured. When to use: before adding a note via leadbay_report_outreach, to avoid duplicating or overwriting context the SDR already wrote. When NOT to use: when the lead summary's notes_count is 0 \u2014 there's nothing to fetch.",
   inputSchema: {
     type: "object",
     properties: { leadId: { type: "string", description: "Lead UUID (required)" } },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     return await client.request("GET", `/leads/${params.leadId}/notes`);
@@ -1104,6 +1392,13 @@ var getLeadNotes = {
 // ../core/dist/tools/get-epilogue-responses.js
 var getEpilogueResponses = {
   name: "leadbay_get_epilogue_responses",
+  annotations: {
+    title: "Read epilogue responses",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the lead's epilogue history \u2014 what status (still chasing, meeting booked, etc.) was set when, and by whom. When to use: to see the lead's outreach progression before deciding the next step. When NOT to use: when the lead summary's epilogue_actions_count is 0.",
   inputSchema: {
     type: "object",
@@ -1112,7 +1407,8 @@ var getEpilogueResponses = {
       count: { type: "number", description: "Items per page (1-200, default 20)" },
       page: { type: "number", description: "Page number, 0-indexed (default 0)" }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const count = params.count ?? 20;
@@ -1124,6 +1420,13 @@ var getEpilogueResponses = {
 // ../core/dist/tools/get-prospecting-actions.js
 var getProspectingActions = {
   name: "leadbay_get_prospecting_actions",
+  annotations: {
+    title: "Read prospecting actions",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the CRM-style activity log for a lead (calls, emails, meetings \u2014 actions performed by humans or prior agent runs). When to use: before contacting the lead, to avoid duplicating outreach the team already did. When NOT to use: when the lead summary's prospecting_actions_count is 0.",
   inputSchema: {
     type: "object",
@@ -1132,7 +1435,8 @@ var getProspectingActions = {
       count: { type: "number", description: "Items per page (1-200, default 20)" },
       page: { type: "number", description: "Page number, 0-indexed (default 0)" }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const count = params.count ?? 20;
@@ -1144,11 +1448,40 @@ var getProspectingActions = {
 // ../core/dist/tools/get-web-fetch.js
 var getWebFetch = {
   name: "leadbay_get_web_fetch",
+  annotations: {
+    title: "Read web-fetch result",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Read the AI-generated web-research summary for a lead \u2014 company profile, business signals, prospecting clues, each with sources and 'hot' flags marking high-signal recent items. The content is dictioned by emoji-prefixed section labels in the raw API. When to use: when the agent already qualified this lead and wants the underlying research to reason from. When NOT to use: as the first read on a lead \u2014 the leadbay_research_lead composite bundles this with qualification answers and reshapes the dict into a stable array form.",
   inputSchema: {
     type: "object",
     properties: { leadId: { type: "string", description: "Lead UUID (required)" } },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Raw LeadWebFetchPayload as returned by /leads/{id}/web_fetch. Permissive shape \u2014 backend dict structure is documented in detail by leadbay_research_lead which reshapes it.",
+    properties: {
+      content: {
+        description: "Backend dict content (object or string), or null when no fetch yet."
+      },
+      fetch_at: {
+        description: "ISO timestamp of the most recent fetch (string or null)."
+      },
+      status: {
+        type: "string",
+        description: "'pending' | 'complete' | 'failed' (when present)."
+      },
+      signals: {
+        type: "array",
+        description: "Optional reshaped signals when the backend returns them.",
+        items: { type: "object" }
+      }
+    }
   },
   execute: async (client, params) => {
     return await client.request("GET", `/leads/${params.leadId}/web_fetch`);
@@ -1158,8 +1491,15 @@ var getWebFetch = {
 // ../core/dist/tools/get-selection-ids.js
 var getSelectionIds = {
   name: "leadbay_get_selection_ids",
+  annotations: {
+    title: "Read selection ids",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "List the lead ids currently in the user's selection (the transient set that bulk operations like enrichment act on). When to use: to verify the selection state before/after bulk ops if a composite call has misbehaved. When NOT to use: in the normal flow \u2014 leadbay_enrich_titles manages selection lifecycle automatically (select \u2192 action \u2192 clear).",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     return await client.request("GET", "/leads/selection/ids");
   }
@@ -1168,8 +1508,15 @@ var getSelectionIds = {
 // ../core/dist/tools/get-enrichment-job-titles.js
 var getEnrichmentJobTitles = {
   name: "leadbay_get_enrichment_job_titles",
+  annotations: {
+    title: "Read enrichment job titles",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "List the actual job titles present across the leads currently in the user's selection \u2014 the candidate set the user can ask to enrich. When to use: after leadbay_select_leads, to know which titles are even available before launching a bulk enrichment. When NOT to use: standalone \u2014 the selection must already be populated, otherwise the result is an empty array. leadbay_enrich_titles wraps this whole flow when you don't need to inspect the title list manually.",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     return await client.request("GET", "/leads/selection/enrichment/job_titles");
   }
@@ -2071,6 +2418,16 @@ function reconcileOneChunk(prep, chunk, matched, notImported) {
 }
 var importLeads = {
   name: "leadbay_import_leads",
+  annotations: {
+    title: "Import leads from list/file",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Backend dedupes by domain/registry id; same input set ⇒ same lead set
+    // (no duplicate leads are created). bulk-store also keys on the
+    // input-hash → returns the same importId on retry.
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Import leads into Leadbay's CRM via the file-import wizard. Returns stable Leadbay leadIds for downstream chaining into leadbay_bulk_qualify_leads / leadbay_research_lead.\n\nTWO MODES:\n  A) Domain-list shortcut \u2014 pass `domains: [{domain, name?}]`. The tool builds a 2-column CSV (LEAD_NAME, LEAD_WEBSITE) and imports with the default mapping. Output: { leads: [{domain, leadId, name}], not_imported: [{domain, reason}], importIds, _meta }.\n  B) Custom records + mapping \u2014 pass `records: [{Col1, Col2, ...}]` plus `mappings.fields: {Col1: 'LEAD_NAME', Col2: 'LEAD_WEBSITE', ...}`. The tool synthesizes a CSV from the union of record keys (deterministic order) and POSTs the caller-supplied mapping to the wizard. mappings.fields must include LEAD_NAME or LEAD_WEBSITE (the resolver needs at least one). Output: { leads: [{rowId, domain?, leadId, name}], not_imported: [{rowId, domain?, reason}], importIds, _meta }. `rowId` round-trips your input order.\n\nPass exactly one of `domains` / `records`. Reserved column MCP_ROW_ID (any case) cannot appear in records or mappings \u2014 the tool injects it for stable reconciliation.\n\n\u26A0\uFE0F MUTATES USER STATE. Each call:\n  - creates a row in the user's CRM-imports list (visible in the web UI)\n  - touches onboarding state (startFileless, onboarding step \u2192 PROCESSING)\nSuitable for occasional automation. NOT suitable for high-cadence (>5 calls/day) \u2014 wait for the backend programmatic endpoint (issue: leadbay/backend prolonged-import-with-crawl).\n\n\u2139\uFE0F Monitor-tab membership: imported leads are NOT auto-promoted to the user's Monitor view. Lens-scoring decides \u2014 only above-threshold leads get `in_monitor: true` server-side.\n\nWhen to use: you have a list of company domains from another system (CRM, analytics, email correspondents) and need stable Leadbay leadIds; or you have CRM-shaped rows with custom columns (sector, location, status, etc.) and want to drive the wizard with explicit field mappings.\nWhen NOT to use: for prospect discovery (use leadbay_pull_leads); for one specific company's profile (use leadbay_research_company); when you can't tolerate the side effects above.\n\nCustom fields: pass org-defined custom field mappings as 'CUSTOM.<id>' (raw wire format) in `mappings.fields`, OR use the ergonomic `mappings.custom_fields` shorthand: `{ColName: 8}` (numeric id) or `{ColName: 'priority_test'}` (field name). Discover available custom fields via leadbay_list_mappable_fields.\n\nRequires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role on the Leadbay account; active billing.",
   write: true,
   version: "0.3.0",
@@ -2092,7 +2449,10 @@ var importLeads = {
               description: "Optional display name override; defaults to the domain."
             }
           },
-          required: ["domain"]
+          required: ["domain"],
+          // Domain entries are a closed shape — agents passing extra keys
+          // (e.g., `leadId: "..."`) would silently no-op. Reject explicitly.
+          additionalProperties: false
         }
       },
       records: {
@@ -2135,9 +2495,41 @@ var importLeads = {
         type: "number",
         description: `Overall cap across all phases (default ${DEFAULT_TOTAL_BUDGET_MS}ms).`
       }
-    }
+    },
     // Neither field is "required" at the schema level; xor + presence is
     // enforced in execute() so we can produce specific error codes.
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      leads: {
+        type: "array",
+        description: "Imported leads. Domains mode: [{domain, leadId, name}]. Records mode: [{rowId, domain?, leadId, name}].",
+        items: { type: "object" }
+      },
+      not_imported: {
+        type: "array",
+        description: "Inputs that did NOT yield a leadId. Each entry has a `reason` ('malformed', 'NO_MATCH', 'TIMEOUT', etc.) plus the input echo.",
+        items: { type: "object" }
+      },
+      importIds: {
+        type: "array",
+        description: "Backend file-import handles (one per chunk of \u2264100 rows).",
+        items: { type: "string" }
+      },
+      region: { type: "string" },
+      cancelled: {
+        type: "boolean",
+        description: "True when ctx.signal aborted the call mid-flight."
+      },
+      dry_run: {
+        type: "boolean",
+        description: "True when dry_run:true was passed (preprocess only, no CRM commit)."
+      },
+      _meta: { type: "object" }
+    },
+    required: ["leads", "not_imported", "importIds", "region", "_meta"]
   },
   execute: async (client, params, ctx) => {
     const signal = ctx?.signal;
@@ -2349,6 +2741,13 @@ var PREVIEW_SAMPLE_CAP = 50;
 var PREPROCESS_BUDGET_MS = 6e4;
 var listMappableFields = {
   name: "leadbay_list_mappable_fields",
+  annotations: {
+    title: "List CRM-import mappable fields",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "List every CRM field the agent can target when calling leadbay_import_leads or leadbay_import_and_qualify. Returns two arrays: `standard_fields` (Leadbay's built-in StandardCrmFieldType enum \u2014 LEAD_NAME, LEAD_WEBSITE, LEAD_STATUS, contact + location + sector fields) and `custom_fields` (this org's user-defined fields \u2014 id, name, type, and the literal `mapping_value` you pass in `mappings.fields`). For custom fields, `mapping_value` is the wire-format string `CUSTOM.<id>` \u2014 pass it verbatim.\n\nOptional `for_records` param: pass a sample of CSV-shaped rows and the tool also runs the wizard's preprocess on them, attaching `mapping_hints` (per-column AI-confidence suggestions) and `custom_field_candidates` (custom fields that match unmapped columns by exact / case-insensitive / fuzzy name) to the response. Saves a separate preview round-trip when the agent already has data in hand.\n\nWhen to use: before authoring an import mapping, especially when the CSV has columns that aren't obvious matches for standard fields. When NOT to use: when you already know the mapping \u2014 this call is cheap (~50ms with no for_records, ~5\u201310s with) but unnecessary if the agent has already cached the catalog within the same conversation.",
   inputSchema: {
     type: "object",
@@ -2361,6 +2760,44 @@ var listMappableFields = {
     },
     additionalProperties: false
   },
+  outputSchema: {
+    type: "object",
+    properties: {
+      standard_fields: {
+        type: "array",
+        description: "Built-in StandardCrmFieldType entries (LEAD_NAME, LEAD_WEBSITE, contact + location + sector). Each: {name, description, mapping_value}.",
+        items: { type: "object" }
+      },
+      custom_fields: {
+        type: "array",
+        description: "Org-defined custom fields. Each: {id, name, type, description, mapping_value:'CUSTOM.<id>'}.",
+        items: { type: "object" }
+      },
+      mapping_hints: {
+        type: "array",
+        description: "Per-column AI-confidence suggestions (only when for_records was passed). Each: {column, target, confidence, reason}.",
+        items: { type: "object" }
+      },
+      custom_field_candidates: {
+        type: "array",
+        description: "Custom fields matching unmapped columns by exact / case-insensitive / fuzzy name (only when for_records was passed).",
+        items: { type: "object" }
+      },
+      sample_rows: {
+        type: "array",
+        description: "First few rows of the preprocessed sample (only when for_records was passed).",
+        items: { type: "object" }
+      },
+      notes: {
+        type: "array",
+        description: "Operator notes (e.g., preprocess timeout, sample-size truncation).",
+        items: { type: "string" }
+      },
+      region: { type: "string" },
+      _meta: { type: "object" }
+    },
+    required: ["standard_fields", "custom_fields", "region", "_meta"]
+  },
   execute: async (client, params, ctx) => {
     const signal = ctx?.signal;
     const customs = await client.request("GET", "/crm/custom_fields");
@@ -2466,6 +2903,13 @@ function coerceCsvValue(v) {
 // ../core/dist/tools/select-leads.js
 var selectLeads = {
   name: "leadbay_select_leads",
+  annotations: {
+    title: "Select leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Add leads to the user's transient selection (used by selection-scoped bulk operations). When to use: low-level. The user's selection is a per-token global state \u2014 be careful when invoking directly. When NOT to use: in normal flow \u2014 leadbay_enrich_titles wraps select \u2192 action \u2192 clear in one call with proper Mutex protection. Calling this directly without acquiring the selection lock can clobber concurrent composite calls.",
   optional: true,
   write: true,
@@ -2480,7 +2924,18 @@ var selectLeads = {
         maxItems: 1e3
       }
     },
-    required: ["leadIds"]
+    required: ["leadIds"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      selected: {
+        type: "number",
+        description: "How many leadIds the call added to the selection (echoes input length)."
+      }
+    },
+    required: ["selected"]
   },
   execute: async (client, params) => {
     const qs = params.leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
@@ -2492,6 +2947,13 @@ var selectLeads = {
 // ../core/dist/tools/deselect-leads.js
 var deselectLeads = {
   name: "leadbay_deselect_leads",
+  annotations: {
+    title: "Deselect leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Remove leads from the user's transient selection. When to use: when narrowing a previously-built selection without clearing it entirely. When NOT to use: in normal flow \u2014 leadbay_enrich_titles handles selection lifecycle.",
   optional: true,
   write: true,
@@ -2505,7 +2967,8 @@ var deselectLeads = {
         minItems: 1
       }
     },
-    required: ["leadIds"]
+    required: ["leadIds"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const qs = params.leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
@@ -2517,10 +2980,17 @@ var deselectLeads = {
 // ../core/dist/tools/clear-selection.js
 var clearSelection = {
   name: "leadbay_clear_selection",
+  annotations: {
+    title: "Clear selection",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Clear the user's transient selection. When to use: cleanup after manual selection work, or recovery from a stuck composite. When NOT to use: in normal flow \u2014 composites clear in their own finally blocks.",
   optional: true,
   write: true,
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     await client.requestVoid("POST", "/leads/selection/clear");
     return { cleared: true };
@@ -2530,13 +3000,21 @@ var clearSelection = {
 // ../core/dist/tools/set-active-lens.js
 var setActiveLens = {
   name: "leadbay_set_active_lens",
+  annotations: {
+    title: "Set active lens",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Mark a lens as last-used. Subsequent /me reads return it as last_requested_lens, so all composite tools default to it. When to use: after the user explicitly switched contexts (e.g. created a new lens via leadbay_create_lens). When NOT to use: in normal flow \u2014 leadbay_pull_leads and leadbay_adjust_audience auto-set the right lens.",
   optional: true,
   write: true,
   inputSchema: {
     type: "object",
     properties: { lensId: { type: "number", description: "Lens id (required)" } },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     await client.requestVoid("POST", `/lenses/${params.lensId}/update_last_requested`);
@@ -2549,6 +3027,13 @@ var setActiveLens = {
 // ../core/dist/tools/create-lens.js
 var createLens = {
   name: "leadbay_create_lens",
+  annotations: {
+    title: "Create a new lens",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Create a new user-level lens by cloning an existing lens's filter/scoring as the starting point. When to use: when adjust_audience determined the current lens cannot be edited (e.g. it's the org default). When NOT to use: to update an existing lens \u2014 use leadbay_update_lens or leadbay_update_lens_filter.",
   optional: true,
   write: true,
@@ -2559,7 +3044,21 @@ var createLens = {
       name: { type: "string", description: "Display name for the new lens" },
       description: { type: "string" }
     },
-    required: ["base", "name"]
+    required: ["base", "name"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Full LensPayload as returned by the backend. Permissive shape \u2014 backend may add fields over time.",
+    properties: {
+      id: { type: "number", description: "New lens id." },
+      name: { type: "string" },
+      description: { type: ["string", "null"] },
+      is_default: { type: "boolean" },
+      is_last_active: { type: "boolean" },
+      user_id: { type: ["string", "number", "null"] }
+    },
+    required: ["id", "name"]
   },
   execute: async (client, params) => {
     const lens = await client.request("POST", "/lenses", {
@@ -2575,6 +3074,13 @@ var createLens = {
 // ../core/dist/tools/update-lens.js
 var updateLens = {
   name: "leadbay_update_lens",
+  annotations: {
+    title: "Update a lens",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Update lens metadata (name, description, mode flags). Does NOT change the audience filter \u2014 use leadbay_update_lens_filter for that. When to use: rename a lens or toggle multi_product_mode/use_hq_only. When NOT to use: to change which leads the lens shows \u2014 that's a filter operation.",
   optional: true,
   write: true,
@@ -2587,7 +3093,8 @@ var updateLens = {
       multi_product_mode: { type: "boolean" },
       use_hq_only: { type: "boolean" }
     },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const { lensId, ...body } = params;
@@ -2600,6 +3107,13 @@ var updateLens = {
 // ../core/dist/tools/update-lens-filter.js
 var updateLensFilter = {
   name: "leadbay_update_lens_filter",
+  annotations: {
+    title: "Update lens filter",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Replace the audience filter (sectors, sizes, locations) on a lens. Body is the full Filter object \u2014 this is a REPLACE, not a merge. Returns 400 'default_lens' if applied to the org default lens (clone it first). When to use: low-level mutation when you've already prepared the merged filter. When NOT to use: from agent flow \u2014 use leadbay_adjust_audience, which handles draft-vs-direct routing, permission fallback, and the merge logic so unrelated criteria aren't dropped.",
   optional: true,
   write: true,
@@ -2616,7 +3130,8 @@ var updateLensFilter = {
         description: "If true, return the call shape that WOULD be sent without contacting the backend"
       }
     },
-    required: ["lensId", "filter"]
+    required: ["lensId", "filter"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     if (params.dry_run) {
@@ -2638,13 +3153,21 @@ var updateLensFilter = {
 // ../core/dist/tools/create-lens-draft.js
 var createLensDraft = {
   name: "leadbay_create_lens_draft",
+  annotations: {
+    title: "Create a lens draft",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Create (or fetch existing) draft of an org-level lens. Idempotent \u2014 same user calling twice returns the same draft. The returned lens has draft_of set to the original lens id. When to use: when a non-admin needs to modify an org-level lens \u2014 make a draft, edit the draft. When NOT to use: from agent flow \u2014 leadbay_adjust_audience handles the draft-routing transparently.",
   optional: true,
   write: true,
   inputSchema: {
     type: "object",
     properties: { lensId: { type: "number", description: "Lens id of the org-level lens to draft" } },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     return await client.request("POST", `/lenses/${params.lensId}/draft`);
@@ -2654,13 +3177,21 @@ var createLensDraft = {
 // ../core/dist/tools/promote-lens.js
 var promoteLens = {
   name: "leadbay_promote_lens",
+  annotations: {
+    title: "Promote a lens draft to active",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Promote a user-level lens (or draft) to org-level so all teammates see it. Admin-only. When to use: rare \u2014 when an admin user has built a lens (or refined a draft) and wants to share it org-wide. When NOT to use: as a non-admin (will fail with 403); for personal lens changes (those stay user-scoped).",
   optional: true,
   write: true,
   inputSchema: {
     type: "object",
     properties: { lensId: { type: "number" } },
-    required: ["lensId"]
+    required: ["lensId"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     await client.requestVoid("POST", `/lenses/${params.lensId}/promote`);
@@ -2672,6 +3203,13 @@ var promoteLens = {
 // ../core/dist/tools/set-user-prompt.js
 var setUserPrompt = {
   name: "leadbay_set_user_prompt",
+  annotations: {
+    title: "Set the user prompt",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Set the org's intelligence-refinement prompt \u2014 free-text instruction that steers Leadbay's lead recommendations beyond firmographics. Admin-only. Setting this clears any pending clarification and triggers a full intelligence regeneration (web search + high-reasoning). When to use: low-level. When NOT to use: from agent flow \u2014 use leadbay_refine_prompt, which polls for follow-up clarifications.",
   optional: true,
   write: true,
@@ -2684,7 +3222,8 @@ var setUserPrompt = {
         description: "If true, return the call shape that WOULD be sent without contacting the backend"
       }
     },
-    required: ["prompt"]
+    required: ["prompt"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const orgId = await client.resolveOrgId();
@@ -2709,10 +3248,17 @@ var setUserPrompt = {
 // ../core/dist/tools/clear-user-prompt.js
 var clearUserPrompt = {
   name: "leadbay_clear_user_prompt",
+  annotations: {
+    title: "Clear the user prompt",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Remove the org's intelligence-refinement prompt (revert to AI-only generation). Admin-only. Triggers full intelligence regeneration. When to use: when a refinement turned out to be the wrong direction. When NOT to use: to replace with a different prompt \u2014 just call leadbay_refine_prompt; that overwrites.",
   optional: true,
   write: true,
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     const orgId = await client.resolveOrgId();
     await client.requestVoid("DELETE", `/organizations/${orgId}/user_prompt`);
@@ -2724,6 +3270,13 @@ var clearUserPrompt = {
 // ../core/dist/tools/pick-clarification.js
 var pickClarification = {
   name: "leadbay_pick_clarification",
+  annotations: {
+    title: "Pick a clarification answer",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Answer the pending clarification question \u2014 either by picking one of the offered options (option_id) or by typing a free-text answer. The answer is stored as the new user_prompt and triggers regeneration. Admin-only. When to use: low-level. When NOT to use: from agent flow \u2014 use leadbay_answer_clarification.",
   optional: true,
   write: true,
@@ -2732,7 +3285,18 @@ var pickClarification = {
     properties: {
       option_id: { type: "string", description: "Id of one of the clarification's options" },
       text_answer: { type: "string", description: "Free-text answer (overrides option_id if both are set)" }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      answered: {
+        type: "boolean",
+        description: "True when the answer was recorded; intelligence regeneration begins."
+      }
+    },
+    required: ["answered"]
   },
   execute: async (client, params) => {
     if (!params.option_id && !params.text_answer) {
@@ -2753,10 +3317,17 @@ var pickClarification = {
 // ../core/dist/tools/dismiss-clarification.js
 var dismissClarification = {
   name: "leadbay_dismiss_clarification",
+  annotations: {
+    title: "Dismiss a clarification",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Dismiss the pending clarification without answering. Leadbay proceeds with its best guess. Admin-only. When to use: when the user explicitly doesn't want to answer the disambiguation. When NOT to use: as a default \u2014 answering with even a free-text reason gives Leadbay better signal.",
   optional: true,
   write: true,
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     const orgId = await client.resolveOrgId();
     await client.requestVoid("POST", `/organizations/${orgId}/dismiss_clarification`);
@@ -2779,6 +3350,13 @@ var EPILOGUE_LABEL_MAP = {
 };
 var setEpilogueStatus = {
   name: "leadbay_set_epilogue_status",
+  annotations: {
+    title: "Set lead epilogue status",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Bulk-set the outreach progress (epilogue) status across a set of leads. Status values: STILL_CHASING, COULD_NOT_REACH_STILL_TRYING, INTEREST_VALIDATED_OR_MEETING_PLANED ('meeting booked'), NOT_INTERESTED_LOST (short labels accepted; mapped to the EPILOGUE_* enum). Up to 1000 leads per call. When to use: low-level. When NOT to use: from agent flow \u2014 leadbay_report_outreach pairs this with a note + verification, which is what humans actually need to see in Leadbay.",
   optional: true,
   write: true,
@@ -2795,7 +3373,8 @@ var setEpilogueStatus = {
         description: "One of: STILL_CHASING, COULD_NOT_REACH_STILL_TRYING, INTEREST_VALIDATED_OR_MEETING_PLANED, NOT_INTERESTED_LOST"
       }
     },
-    required: ["lead_ids", "status"]
+    required: ["lead_ids", "status"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const wire = EPILOGUE_LABEL_MAP[params.status];
@@ -2818,6 +3397,13 @@ var setEpilogueStatus = {
 // ../core/dist/tools/remove-epilogue.js
 var removeEpilogue = {
   name: "leadbay_remove_epilogue",
+  annotations: {
+    title: "Remove lead epilogue",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Bulk-clear the epilogue status from a set of leads. When to use: when an outreach action was logged in error and needs to be undone. When NOT to use: to change status \u2014 call leadbay_set_epilogue_status with the new status (it overwrites).",
   optional: true,
   write: true,
@@ -2830,7 +3416,8 @@ var removeEpilogue = {
         description: "Lead UUIDs"
       }
     },
-    required: ["lead_ids"]
+    required: ["lead_ids"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     await client.requestVoid("POST", "/leads/remove_epilogue", {
@@ -2843,6 +3430,13 @@ var removeEpilogue = {
 // ../core/dist/tools/preview-bulk-enrichment.js
 var previewBulkEnrichment = {
   name: "leadbay_preview_bulk_enrichment",
+  annotations: {
+    title: "Preview bulk enrichment cost",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Preview a bulk-enrichment cost given a set of job titles applied to the current selection. Returns {selected_leads, enriched_contacts, enrichable_contacts, title_suggestions, auto_included_titles, previously_enriched_titles}. previously_enriched_titles is a newer field (in prod soon) \u2014 when present, the agent can recommend repeating those titles for new leads. When to use: between selecting leads and launching, to know what the enrichment will cost. When NOT to use: from agent flow \u2014 leadbay_enrich_titles wraps preview + launch with the right safety checks.",
   optional: true,
   write: true,
@@ -2855,7 +3449,8 @@ var previewBulkEnrichment = {
         description: "Job titles to enrich (matched against contacts in selected leads)"
       }
     },
-    required: ["titles"]
+    required: ["titles"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     return await client.request("POST", "/leads/selection/enrichment/preview", { titles: params.titles });
@@ -2865,6 +3460,13 @@ var previewBulkEnrichment = {
 // ../core/dist/tools/launch-bulk-enrichment.js
 var launchBulkEnrichment = {
   name: "leadbay_launch_bulk_enrichment",
+  annotations: {
+    title: "Launch bulk enrichment",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Launch a bulk-enrichment job against the current selection. The backend requires email=true OR phone=true (both can be true). Returns 204 with no body \u2014 there is no bulk_id and no per-job status endpoint. Track results by polling individual leads via leadbay_get_contacts after ~60s; contact.enrichment.done flips to true. When to use: low-level. When NOT to use: from agent flow \u2014 leadbay_enrich_titles handles selection lifecycle, preview, launch, and cleanup.",
   optional: true,
   write: true,
@@ -2879,7 +3481,8 @@ var launchBulkEnrichment = {
         description: "If true, return the call shape WITHOUT contacting the backend"
       }
     },
-    required: ["titles"]
+    required: ["titles"],
+    additionalProperties: false
   },
   execute: async (client, params) => {
     const email = params.email ?? true;
@@ -2920,6 +3523,13 @@ var launchBulkEnrichment = {
 // ../core/dist/composite/research-company.js
 var researchCompany = {
   name: "leadbay_research_company",
+  annotations: {
+    title: "Research a company by name",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Deep-dive research on a specific company by NAME (fuzzy match against the active lens's wishlist). When to use: when the user references a company by name and you don't yet have its lead_id. When NOT to use: when you already have the lead_id \u2014 use leadbay_research_lead directly (it bundles richer signals + better top-down ordering for the agent).",
   inputSchema: {
     type: "object",
@@ -2932,7 +3542,39 @@ var researchCompany = {
         type: "string",
         description: "Lead UUID if already known (one of companyName or leadId required). Takes precedence over companyName."
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      lead: {
+        type: "object",
+        description: "Lead profile basics (id, name, score, ai_agent_lead_score, location, description, short_description, size, website, logo, ai_summary, tags, phone_numbers, keywords, contacts_count, recommended_contact_title, recommended_contact, web_fetch_in_progress)."
+      },
+      qualification: {
+        type: ["array", "null"],
+        description: "Per-question AI qualification answers ({question, score, response, computed_at, outdated_at}), or null if none.",
+        items: { type: "object" }
+      },
+      contacts: {
+        type: "array",
+        description: "Merged org + paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}.",
+        items: { type: "object" }
+      },
+      web_insights: {
+        description: "Latest /web_fetch content (string) or null when no fetch is available."
+      },
+      web_insights_fetched_at: {
+        description: "ISO timestamp of the latest /web_fetch (string) or null."
+      },
+      recent_activities: {
+        type: "array",
+        description: "Recent activities for this lead (top 20). Each is the activity payload as returned by /leads/{id}/activities.",
+        items: { type: "object" }
+      }
+    },
+    required: ["lead", "contacts", "recent_activities"]
   },
   execute: async (client, params, ctx) => {
     if (!params.leadId && !params.companyName) {
@@ -2965,6 +3607,13 @@ var researchCompany = {
 // ../core/dist/composite/prepare-outreach.js
 var prepareOutreach = {
   name: "leadbay_prepare_outreach",
+  annotations: {
+    title: "Prepare outreach package for a lead",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Prepare an outreach package for a single lead: recommended contact + enriched contact details + AI summary. When to use: when the agent is about to draft outreach for ONE specific lead and needs the contact's email/phone. When NOT to use: across many leads \u2014 use leadbay_enrich_titles for bulk; for general lead detail use leadbay_research_lead (richer signals); to actually log the outreach action use leadbay_report_outreach (requires verification).",
   optional: true,
   inputSchema: {
@@ -2979,11 +3628,44 @@ var prepareOutreach = {
         description: "If true and credits available, trigger enrichment on the recommended contact (default: false). Enrichment is async \u2014 poll leadbay_get_contacts after ~60s."
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
   },
-  execute: async (client, params, ctx) => {
-    const contactsResult = await getContacts.execute(client, { leadId: params.leadId }, ctx);
-    const contacts = contactsResult.contacts;
+  outputSchema: {
+    type: "object",
+    properties: {
+      lead: {
+        type: ["object", "null"],
+        description: "Short lead summary for outreach context: {name, ai_summary, website}. Null if /lead profile fetch failed.",
+        properties: {
+          name: { type: "string" },
+          ai_summary: { type: ["string", "null"] },
+          website: { type: ["string", "null"] }
+        }
+      },
+      recommended_contact: {
+        type: ["object", "null"],
+        description: "Best contact to outreach to ({id, name, job_title, email, phone_number, linkedin_page}). Null when no contacts known."
+      },
+      other_contacts_count: {
+        type: "number",
+        description: "How many other contacts exist beyond the recommended one (so the agent knows there's more to discover via leadbay_get_contacts)."
+      },
+      enrichment: {
+        type: "object",
+        description: "Status of opt-in enrichment (only set when enrich:true was passed): {triggered, error, hint}.",
+        properties: {
+          triggered: { type: "boolean" },
+          error: { type: ["string", "null"] },
+          hint: { type: ["string", "null"] }
+        }
+      }
+    },
+    required: ["recommended_contact", "other_contacts_count", "enrichment"]
+  },
+  execute: async (client, params, ctx) => {
+    const contactsResult = await getContacts.execute(client, { leadId: params.leadId }, ctx);
+    const contacts = contactsResult.contacts;
     const recommended = contacts.find((c) => c.recommended) ?? contacts[0];
     let enrichmentTriggered = false;
     let enrichmentError = null;
@@ -3040,6 +3722,13 @@ function summarise(responses) {
 }
 var pullLeads = {
   name: "leadbay_pull_leads",
+  annotations: {
+    title: "Pull fresh Leadbay leads",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Pull up new leads from the user's last-active lens \u2014 the canonical 'show me today's prospects' tool. Leadbay works like an inbox: each time the user logs back in, a fresh batch is delivered, paced by how many leads they've actually acted on recently. Pulling more won't produce more; user outreach/skips/saves does. Each returned lead carries a one-line qualification_summary built from leadbay_ai_agent_responses, plus the rich tags / scores / recommended_contact_title / engagement counters / in-flight flags from the lead summary. Roughly the top 10 of the batch come pre-qualified (populated qualification_summary + ai_agent_lead_score); leads below the top ~10 carry only the basic firmographic `score` \u2014 not worse, just resource-saved by the system. Call leadbay_bulk_qualify_leads to deepen any of them on demand. When to use: as the agent's default opening move when the user wants to see leads, or as a daily check-in for what's new today. When NOT to use: when the user has named a specific lens \u2014 pass lensId to override the auto-resolution. Replaces the older leadbay_find_prospects (which is removed in v0.2.0).",
   inputSchema: {
     type: "object",
@@ -3054,7 +3743,57 @@ var pullLeads = {
         type: "boolean",
         description: "If true, include the full set of lead-summary fields. Default false: returns the trimmed agent-friendly form."
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      lens: {
+        type: "object",
+        description: "Lens metadata (id of the lens that was queried).",
+        properties: { id: { type: "number" } }
+      },
+      leads: {
+        type: "array",
+        description: "The page of leads. In default mode (verbose:false) each lead is the trimmed agent-friendly shape; in verbose:true the full LeadPayload.",
+        items: { type: "object" }
+      },
+      pagination: {
+        type: "object",
+        description: "page (0-indexed), pages (total), total (item count).",
+        properties: {
+          page: { type: "number" },
+          pages: { type: "number" },
+          total: { type: "number" }
+        }
+      },
+      has_more: {
+        type: "boolean",
+        description: "True if at least one more page exists. Spec-aligned pagination metadata."
+      },
+      next_page: {
+        type: ["number", "null"],
+        description: "0-indexed next page number, or null on the last page."
+      },
+      computing_wishlist: {
+        type: "boolean",
+        description: "True if Leadbay is still rebuilding this lens's wishlist."
+      },
+      computing_scores: {
+        type: "boolean",
+        description: "True if scoring is still running."
+      },
+      _meta: {
+        type: "object",
+        description: "Operator context: region + last-call latency.",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["lens", "leads", "pagination"]
   },
   execute: async (client, params, ctx) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
@@ -3103,6 +3842,10 @@ var pullLeads = {
       epilogue_actions_count: lead.epilogue_actions_count ?? 0,
       prospecting_actions_count: lead.prospecting_actions_count ?? 0
     };
+    const totalPages = res.pagination?.pages ?? 0;
+    const currentPage = res.pagination?.page ?? page;
+    const hasMore = currentPage < totalPages - 1;
+    const nextPage = hasMore ? currentPage + 1 : null;
     return {
       lens: { id: lensId },
       leads: res.items.map((lead) => ({
@@ -3110,6 +3853,8 @@ var pullLeads = {
         qualification_summary: summaryMap.get(lead.id) ?? null
       })),
       pagination: res.pagination,
+      has_more: hasMore,
+      next_page: nextPage,
       computing_wishlist: res.computing_wishlist,
       computing_scores: res.computing_scores,
       _meta: {
@@ -3121,6 +3866,86 @@ var pullLeads = {
 };
 
 // ../core/dist/composite/research-lead.js
+function renderResearchLeadMarkdown(shape) {
+  const out = [];
+  const firm = shape.firmographics ?? {};
+  const name = firm.name ?? "(unnamed lead)";
+  out.push(`# ${name}`);
+  if (firm.website)
+    out.push(`Website: ${firm.website}`);
+  if (firm.location)
+    out.push(`Location: ${firm.location}`);
+  if (typeof firm.score === "number" || firm.score === null) {
+    const aiScore = firm.ai_agent_lead_score;
+    out.push(`Score: ${firm.score ?? "\u2014"}` + (aiScore != null ? ` \xB7 AI: ${aiScore}` : ""));
+  }
+  if (firm.short_description)
+    out.push(`
+${firm.short_description}`);
+  const qualification = Array.isArray(shape.qualification) ? shape.qualification : [];
+  if (qualification.length > 0) {
+    out.push(`
+## Qualification`);
+    for (const q of qualification) {
+      const score = q.boost_score != null ? `${q.boost_score}` : "\u2014";
+      const resp = q.response ? String(q.response).slice(0, 200) : "\u2014";
+      out.push(`- **${q.question}** (boost ${score}): ${resp}`);
+    }
+  }
+  const signals = Array.isArray(shape.signals) ? shape.signals : [];
+  if (signals.length > 0) {
+    out.push(`
+## Signals`);
+    for (const sec of signals) {
+      const label = sec.section_label ?? "section";
+      out.push(`### ${sec.section_emoji ?? ""} ${label}`.trim());
+      const entries = Array.isArray(sec.entries) ? sec.entries : [];
+      for (const e of entries.slice(0, 5)) {
+        const text = e.text ?? e.summary ?? JSON.stringify(e).slice(0, 200);
+        const hot = e.hot === true ? " \u{1F525}" : "";
+        out.push(`- ${text}${hot}`);
+      }
+      if (entries.length > 5)
+        out.push(`- _${entries.length - 5} more \u2026_`);
+    }
+  }
+  const contacts = shape.contacts ?? {};
+  const enriched = Array.isArray(contacts.enriched) ? contacts.enriched : [];
+  if (enriched.length > 0) {
+    out.push(`
+## Contacts (enriched)`);
+    for (const c of enriched.slice(0, 10)) {
+      const fn = c.first_name ?? "";
+      const ln = c.last_name ?? "";
+      const title = c.job_title ?? "\u2014";
+      const email = c.email ?? "no email";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${email}`);
+    }
+  }
+  const engagement = shape.engagement ?? {};
+  const counts = [
+    ["notes", engagement.notes_count],
+    ["epilogue", engagement.epilogue_actions_count],
+    ["prospecting", engagement.prospecting_actions_count]
+  ];
+  const activeCounts = counts.filter(([, v]) => typeof v === "number" && v > 0);
+  if (activeCounts.length > 0 || engagement.liked || engagement.disliked) {
+    out.push(`
+## Engagement`);
+    if (engagement.liked)
+      out.push(`- liked \u2705`);
+    if (engagement.disliked)
+      out.push(`- disliked \u274C`);
+    for (const [k, v] of activeCounts) {
+      out.push(`- ${k}: ${v}`);
+    }
+  }
+  if (shape.truncated) {
+    out.push(`
+_Truncated_: ${shape.truncation_hint ?? "response trimmed"}_`);
+  }
+  return out.join("\n");
+}
 var SECTION_PRIORITY = ["profile", "signals", "clues"];
 function splitEmojiSection(key) {
   const m = key.match(/^([^\p{L}\p{N}\s]+)\s+(.+)$/u);
@@ -3155,6 +3980,13 @@ function reshapeWebFetchContent(content) {
 }
 var researchLead = {
   name: "leadbay_research_lead",
+  annotations: {
+    title: "Research a Leadbay lead in depth",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Tell me everything decision-relevant about a single lead. Bundles the lens-scoped lead profile, the AI qualification answers (the agent's knowledge-base food), the structured web-research signals (with hot flags + sources), the enriched contacts, and the recent notes/epilogue/prospecting activity in one call. Order is deliberate: qualification first, then signals, then firmographics, then contacts, then engagement. Scoring has two layers: the basic `score` (firmographic, always present, already decent) and the AI qualification layer (`ai_agent_lead_score` + per-question answers + web_fetch signals). The AI layer is pre-populated for roughly the top 10 of each daily batch, and on-demand (via leadbay_bulk_qualify_leads) for anything below that. Combine both layers when judging a lead. When to use: when picking up a single lead from leadbay_pull_leads to decide whether to act on it. When NOT to use: across many leads at once \u2014 that's leadbay_pull_leads' job. (This composite supersedes the lower-level leadbay_get_lead_profile in agent flow; the granular tool stays available for fine-grained access.)",
   inputSchema: {
     type: "object",
@@ -3167,9 +3999,108 @@ var researchLead = {
       concise: {
         type: "boolean",
         description: "If true, trim signals to hot=true items only (smaller payload). Default false."
+      },
+      response_format: {
+        type: "string",
+        enum: ["json", "markdown"],
+        description: "How the agent wants the result rendered. 'json' (default): the structured payload as text. 'markdown': a compact human-readable rendering (sections + bullets) \u2014 useful for chat-rendering clients (Cursor, Claude Desktop) where the user sees the response directly. structuredContent is emitted in both modes so capable clients still get typed access."
       }
     },
-    required: ["leadId"]
+    required: ["leadId"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      qualification: {
+        type: "array",
+        description: "Per-question AI qualification answers, ordered by mission importance. Each entry: question, boost_score (canonical -10|0|10|20), score_scale, response, computed_at. score_0_to_10 is a deprecated alias of boost_score (removed in 0.7.0).",
+        items: {
+          type: "object",
+          properties: {
+            question: { type: "string" },
+            boost_score: { type: ["number", "null"] },
+            score_scale: { type: "string" },
+            score_0_to_10: { type: ["number", "null"] },
+            response: { type: ["string", "null"] },
+            computed_at: { type: ["string", "null"] }
+          }
+        }
+      },
+      signals: {
+        type: "array",
+        description: "Web-research signals reshaped into priority-ordered sections (profile \u2192 signals \u2192 clues \u2192 other). Each entry: section_label, section_emoji, entries[]. With concise:true, only hot=true entries kept. May be auto-trimmed when truncated:true (see below).",
+        items: { type: "object" }
+      },
+      truncated: {
+        type: "boolean",
+        description: "True when the response was auto-trimmed to stay under the ~25k-char budget. Always false when concise:true is passed."
+      },
+      truncation_hint: {
+        type: ["string", "null"],
+        description: "When truncated:true, names the specific argument that would reduce the payload (typically 'concise:true')."
+      },
+      firmographics: {
+        type: "object",
+        description: "Lead profile basics. iter-30: nested additionalProperties:false closes the output-side strictness frontier \u2014 runtime returns must match exactly these keys.",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          sector_id: { type: ["number", "string", "null"] },
+          size: { type: ["string", "null"] },
+          location: { type: ["string", "null"] },
+          website: { type: ["string", "null"] },
+          description: { type: ["string", "null"] },
+          short_description: { type: ["string", "null"] },
+          keywords: { type: "array", items: { type: "string" } },
+          tags: { type: "array", items: { type: "string" } },
+          score: { type: ["number", "null"] },
+          ai_agent_lead_score: { type: ["number", "null"] },
+          social_presence: { type: ["object", "string", "null"] },
+          social_urls: { type: ["object", "array", "null"] },
+          registry_ids: { type: ["object", "array", "null"] }
+        },
+        additionalProperties: false
+      },
+      contacts: {
+        type: "object",
+        description: "Two-tier contact set: `enriched` (paid contacts known on this lens for this lead) and `org` (org-level contacts visible beyond the lens).",
+        properties: {
+          enriched: { type: "array", items: { type: "object" } },
+          org: { type: "array", items: { type: "object" } }
+        },
+        additionalProperties: false
+      },
+      engagement: {
+        type: "object",
+        description: "What humans/prior agent runs already did: liked/disliked flags, recommended_contact, counts (notes/epilogue/prospecting), and the most-recent items (recent_notes, recent_epilogue, recent_prospecting). Counts > 0 trigger conditional fan-out for the recent_* fields.",
+        properties: {
+          liked: { type: "boolean" },
+          disliked: { type: "boolean" },
+          new: { type: "boolean" },
+          recommended_contact_title: { type: ["string", "null"] },
+          recommended_contact: { type: ["object", "null"] },
+          notes_count: { type: "number" },
+          epilogue_actions_count: { type: "number" },
+          prospecting_actions_count: { type: "number" },
+          recent_notes: { type: "array", items: { type: "object" } },
+          recent_epilogue: { type: "array", items: { type: "object" } },
+          recent_prospecting: { type: "array", items: { type: "object" } }
+        },
+        additionalProperties: false
+      },
+      _meta: {
+        type: "object",
+        description: "Operator context: region (us/fr/custom), lens_id (the lens used for the lead-by-id fetch), web_fetch_in_progress (true if the backend is still hydrating signals).",
+        properties: {
+          region: { type: "string" },
+          lens_id: { type: "number" },
+          web_fetch_in_progress: { type: "boolean" }
+        },
+        additionalProperties: false
+      }
+    },
+    required: ["qualification", "signals", "firmographics", "contacts", "engagement"]
   },
   execute: async (client, params, ctx) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
@@ -3210,16 +4141,50 @@ var researchLead = {
     }
     const paidContacts = contactsR.status === "fulfilled" ? contactsR.value : [];
     const orgContacts = valOrNull(orgContactsR) ?? [];
+    const TRUNCATE_CHAR_BUDGET = 25e3;
+    let truncated = false;
+    let truncationHint = null;
+    const probeSize = (obj) => {
+      try {
+        return JSON.stringify(obj).length;
+      } catch {
+        return 0;
+      }
+    };
+    let signalsForReturn = signals;
+    if (!params.concise) {
+      const signalsSize = probeSize(signals);
+      if (signalsSize > TRUNCATE_CHAR_BUDGET) {
+        truncated = true;
+        truncationHint = "Response truncated to fit context. Pass concise:true to filter to hot signals only.";
+        signalsForReturn = signals.map((s) => ({
+          ...s,
+          entries: s.entries.slice(0, 2)
+        }));
+      }
+    }
     return {
       // 1) qualification — single most important block for "is this lead worth pursuing"
+      // boost_score is the canonical field (per AiAgentResponse.score). The valid
+      // set is the discrete -10/0/10/20 boost (see types.ts comment), NOT a 0-10
+      // average — the eval doc flagged the old `score_0_to_10` field name as
+      // misleading. We now ship `boost_score` as canonical alongside an explicit
+      // `score_scale` annotation; `score_0_to_10` is kept as a deprecated alias
+      // for one minor version (0.6.x) and removed in 0.7.0. See MIGRATION.md.
       qualification: qualR.status === "fulfilled" ? qualR.value.map((r) => ({
         question: r.question,
+        boost_score: r.score,
+        score_scale: "-10|0|10|20",
+        // Deprecated alias — same value as boost_score. Will be removed
+        // in 0.7.0; consumers should switch to boost_score.
         score_0_to_10: r.score,
         response: r.response,
         computed_at: r.computed_at
       })) : [],
-      // 2) signals — knowledge-base food
-      signals,
+      // 2) signals — knowledge-base food (may be trimmed when truncated:true)
+      signals: signalsForReturn,
+      truncated,
+      truncation_hint: truncationHint,
       // 3) firmographics
       firmographics: {
         id: lead.id,
@@ -3281,10 +4246,32 @@ var researchLead = {
     };
   }
 };
+var _innerExecute = researchLead.execute;
+researchLead.execute = async (client, params, ctx) => {
+  const result = await _innerExecute(client, params, ctx);
+  if (params.response_format !== "markdown")
+    return result;
+  if (result && typeof result === "object" && result.error === true) {
+    return result;
+  }
+  const envelope = {
+    __markdown_envelope: true,
+    markdown: renderResearchLeadMarkdown(result),
+    structured: result
+  };
+  return envelope;
+};
 
 // ../core/dist/composite/recall-ordered-titles.js
 var recallOrderedTitles = {
   name: "leadbay_recall_ordered_titles",
+  annotations: {
+    title: "Recall titles previously enriched",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Show job titles the org has previously enriched, so the agent can repeat the same titles for new leads (or skip already-saturated ones). Two implementation paths: (1) PREFERRED: a selection-scoped preview call that reads previously_enriched_titles from the backend (newer prod field). (2) FALLBACK: live aggregation across each lead's enriched contacts. The composite picks transparently. When to use: before leadbay_enrich_titles, to plan which titles to order. When NOT to use: when you already know the exact titles you want to enrich.",
   inputSchema: {
     type: "object",
@@ -3298,7 +4285,32 @@ var recallOrderedTitles = {
         type: "number",
         description: "Override the auto-resolved last-active lens when omitting leadIds (escape hatch)"
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      source: {
+        type: "string",
+        description: "'preview_field' (preferred backend path) or 'live_aggregate' (fallback aggregation across each lead's contacts)."
+      },
+      titles: {
+        type: "array",
+        description: "Titles previously enriched. preview_field path: [{title}]. live_aggregate path: [{title, leads_with_enriched, total_enriched_contacts, leads_still_having_unenriched}].",
+        items: { type: "object" }
+      },
+      available_in_selection: {
+        type: "array",
+        description: "Backend-suggested title candidates available for ordering (preview_field path only).",
+        items: { type: "object" }
+      },
+      note: {
+        type: "string",
+        description: "Operator note explaining the chosen path (e.g., empty input set, fallback in use)."
+      }
+    },
+    required: ["source", "titles"]
   },
   execute: async (client, params, ctx) => {
     let leadIds = params.leadIds;
@@ -3374,8 +4386,58 @@ var recallOrderedTitles = {
 // ../core/dist/composite/account-status.js
 var accountStatus = {
   name: "leadbay_account_status",
+  annotations: {
+    title: "Show Leadbay account + quota state",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption. When to use: at the start of a session to know what the agent can/can't do, or after a 429 to explain to the user which resource window was exhausted and when it resets. When NOT to use: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating.",
-  inputSchema: { type: "object", properties: {} },
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      user: {
+        type: "object",
+        description: "Identity & roles for the current bearer-token holder.",
+        properties: {
+          email: { type: ["string", "null"] },
+          name: { type: ["string", "null"] },
+          admin: { type: "boolean" },
+          manager: { type: "boolean" },
+          language: { type: "string" }
+        }
+      },
+      organization: {
+        type: "object",
+        description: "Org-level state and feature flags.",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          ai_agent_enabled: { type: "boolean" },
+          computing_intelligence: {
+            type: "boolean",
+            description: "True if Leadbay is mid-regenerating intelligence after a refine_prompt; new leads will reflect it shortly."
+          },
+          plan: { type: ["string", "null"] }
+        }
+      },
+      last_requested_lens: {
+        type: ["number", "null"],
+        description: "Most recent lens id the user pulled leads from."
+      },
+      quota: {
+        type: ["object", "null"],
+        description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr)."
+      },
+      _meta: {
+        type: "object",
+        properties: { region: { type: "string" } }
+      }
+    },
+    required: ["user", "organization"]
+  },
   execute: async (client, _params, ctx) => {
     const me = await client.resolveMe();
     let quota = null;
@@ -3419,6 +4481,15 @@ var DEFAULT_PER_LEAD_BUDGET_MS = 9e4;
 var DEFAULT_TOTAL_BUDGET_MS2 = 5 * 6e4;
 var bulkQualifyLeads = {
   name: "leadbay_bulk_qualify_leads",
+  annotations: {
+    title: "Bulk-qualify next N leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Same set of leads + same options ⇒ same backend job (idempotency
+    // hash); already-qualified leads are silent no-ops. Re-call is safe.
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch), polling until the answers are populated or a budget is exhausted. Already-qualified leads (those with a non-null ai_agent_lead_score) are silently no-ops on the backend, so this composite paginates past them to find fresh candidates. On 429 mid-fanout, stops launching but keeps polling already-launched leads. Context: Leadbay auto-qualifies roughly the top 10 of each daily batch. Leads below the top ~10 are NOT worse \u2014 the system is saving resources. This tool is how the agent spends more resources to go deeper on promising-looking leads the user hasn't had time to surface yet. When to use: when the user wants more qualified leads than what's currently shown, or when a lead looks promising in leadbay_pull_leads but has an empty qualification_summary. When NOT to use: to qualify a single specific lead \u2014 that's leadbay_qualify_lead (granular, advanced).",
   inputSchema: {
     type: "object",
@@ -3444,7 +4515,48 @@ var bulkQualifyLeads = {
         type: "number",
         description: `Total polling budget in ms (default ${DEFAULT_TOTAL_BUDGET_MS2})`
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      qualified: {
+        type: "array",
+        description: "Leads whose qualification finished within budget. Each entry: lead_id, qualification_summary{answered,total,avg_qualification_boost}, signals_count.",
+        items: { type: "object" }
+      },
+      still_running: {
+        type: "array",
+        description: "Leads launched but whose qualification did not complete within budget. Re-poll via leadbay_qualify_status with the bulk_id (when present).",
+        items: { type: "object" }
+      },
+      failed: {
+        type: "array",
+        description: "Leads whose web_fetch launch failed (per-lead error).",
+        items: { type: "object" }
+      },
+      quota_exceeded: {
+        type: "boolean",
+        description: "True if 429 was hit mid-fanout. Already-launched leads keep polling; further launches stopped."
+      },
+      exhausted: {
+        type: "boolean",
+        description: "True if the lens's wishlist had no more unqualified leads to qualify."
+      },
+      total_unqualified_found: { type: "number" },
+      message: { type: "string", description: "Human-readable summary; absent on the happy path." },
+      lens_id: {
+        type: "number",
+        description: "The lens id the qualification ran against. Present on every successful return."
+      },
+      _meta: {
+        type: "object",
+        description: "Operator context: region.",
+        properties: { region: { type: "string" } }
+      }
+    },
+    required: ["qualified", "still_running", "failed", "quota_exceeded"]
   },
   execute: async (client, params, ctx) => {
     const wantCount = Math.min(params.count ?? DEFAULT_COUNT, MAX_COUNT);
@@ -3516,11 +4628,33 @@ var bulkQualifyLeads = {
         }
       }
     }
+    let progressDone = 0;
+    const progressTotal = launched.length;
+    if (progressTotal > 0) {
+      ctx?.progress?.({
+        progress: 0,
+        total: progressTotal,
+        message: `Starting qualification for ${progressTotal} lead${progressTotal === 1 ? "" : "s"}`
+      });
+    }
+    const sleepWithSignal = (ms) => new Promise((resolve) => {
+      if (ctx?.signal?.aborted) {
+        resolve();
+        return;
+      }
+      const t = setTimeout(resolve, ms);
+      ctx?.signal?.addEventListener("abort", () => {
+        clearTimeout(t);
+        resolve();
+      }, { once: true });
+    });
     const results = await Promise.all(launched.map(async (leadId) => {
       const leadDeadline = Math.min(Date.now() + perLeadBudget, totalDeadline);
       let lastQual = null;
       let lastWf = null;
       while (Date.now() < leadDeadline) {
+        if (ctx?.signal?.aborted)
+          break;
         try {
           const [wfR, qualR] = await Promise.allSettled([
             client.request("GET", `/leads/${leadId}/web_fetch`),
@@ -3531,11 +4665,20 @@ var bulkQualifyLeads = {
           if (qualR.status === "fulfilled")
             lastQual = qualR.value;
           const done = lastWf !== null && lastWf.in_progress !== true && Array.isArray(lastQual) && lastQual.length > 0 && lastQual.every((r) => r.score != null);
-          if (done)
+          if (done) {
+            progressDone += 1;
+            ctx?.progress?.({
+              progress: progressDone,
+              total: progressTotal,
+              message: `Qualified lead ${leadId} (${progressDone}/${progressTotal})`
+            });
             break;
+          }
         } catch {
         }
-        await new Promise((r) => setTimeout(r, 5e3));
+        if (ctx?.signal?.aborted)
+          break;
+        await sleepWithSignal(5e3);
       }
       const stillRunning = lastWf?.in_progress === true || !lastQual || lastQual.length === 0 || lastQual.some((r) => r.score == null);
       const responses = lastQual ?? [];
@@ -3646,6 +4789,16 @@ function buildFingerprintInput(mappings) {
 }
 var importAndQualify = {
   name: "leadbay_import_and_qualify",
+  annotations: {
+    title: "Import + qualify leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Composite of import (idempotent against domain hash) + qualify (which
+    // is silent no-op for already-qualified leads). bulk-store + import
+    // hashes return same handles on retry.
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: `Composite: import a list of leads (CSV-shaped records OR a list of domains), then trigger Leadbay's AI qualification (web research + per-question scoring) on every imported leadId, and return both the import outcome and the per-lead qualification answers \u2014 in one call. Honours a total wall-clock budget; when the budget is exhausted before all leads finish qualifying, returns a \`qualify_id\` UUID handle that survives MCP restart and can be passed to leadbay_qualify_status to retrieve the rest of the answers later.
 
 Inputs:
@@ -3690,7 +4843,11 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
               description: "Optional display name override; defaults to the domain."
             }
           },
-          required: ["domain"]
+          required: ["domain"],
+          // Closed shape — extra keys silently no-op, so reject explicitly.
+          // Parallel surface to import_leads.domains[] (iter 13). Per second-
+          // opinion #2 finding #3.
+          additionalProperties: false
         }
       },
       records: {
@@ -3712,7 +4869,11 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
           },
           statuses: { type: "object", description: "Optional status string mapping." },
           default_status: { type: ["string", "null"], description: "Optional default status." }
-        }
+        },
+        // mappings has a closed shape (fields/custom_fields/statuses/default_status).
+        // Inner objects (fields, custom_fields, statuses) keep open shapes
+        // because their keys are user-defined CSV column names.
+        additionalProperties: false
       },
       per_lead_budget_ms: {
         type: "number",
@@ -3737,7 +4898,105 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
         type: "boolean",
         description: "When true (default), skips web_fetch launch on leads whose ai_agent_lead_score is already non-null. Saves quota. Set false to force fresh re-qualification."
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Two return shapes: kind:'preview' (when dry_run='preview') with mapping hints; kind:'result' (default) with imported + qualified leads + qualify_id handle.",
+    properties: {
+      kind: {
+        type: "string",
+        description: "'result' (full flow) or 'preview' (dry_run='preview' mapping diagnostics)."
+      },
+      // preview-shape keys
+      mapping_hints: {
+        type: "array",
+        description: "Per-column AI-confidence suggestions (preview shape).",
+        items: { type: "object" }
+      },
+      custom_field_candidates: {
+        type: "array",
+        description: "Org custom fields that match unmapped columns (preview shape).",
+        items: { type: "object" }
+      },
+      sample_rows: {
+        type: "array",
+        description: "First few rows of the preprocessed sample (preview shape).",
+        items: { type: "object" }
+      },
+      notes: {
+        type: "array",
+        description: "Operator notes (e.g., catalog fetch errors).",
+        items: { type: "string" }
+      },
+      import_id: {
+        type: "string",
+        description: "Backend file-import handle (preview shape)."
+      },
+      // result-shape keys
+      dry_run: { type: "boolean", description: "True when dry_run:true was passed." },
+      chosen_budgets: {
+        type: "object",
+        description: "Adaptive budgets the composite selected (when caller didn't override): {per_lead_budget_ms, total_budget_ms, per_phase_budget_ms, wall_clock_estimate_ms, strategy}."
+      },
+      qualify_id: {
+        type: ["string", "null"],
+        description: "UUIDv4 handle for polling via leadbay_qualify_status. Null when no leads were qualified."
+      },
+      import_ids: {
+        type: "array",
+        description: "Backend file-import handles (one per chunk).",
+        items: { type: "string" }
+      },
+      imported: {
+        type: "array",
+        description: "Leads that landed in CRM. Each: {leadId, domain?, name, rowId?}.",
+        items: { type: "object" }
+      },
+      not_imported: {
+        type: "array",
+        description: "Inputs that didn't land. Each has a `reason` plus the input echo.",
+        items: { type: "object" }
+      },
+      qualified: {
+        type: "array",
+        description: "Leads whose qualification settled within budgets.",
+        items: { type: "object" }
+      },
+      still_running: {
+        type: "array",
+        description: "Leads still being qualified at deadline; agent calls leadbay_qualify_status with qualify_id.",
+        items: { type: "object" }
+      },
+      failed: {
+        type: "array",
+        description: "Per-lead errors observed during qualification.",
+        items: { type: "object" }
+      },
+      quota_exceeded: { type: "boolean" },
+      skipped_already_qualified: {
+        type: "array",
+        description: "Lead ids skipped because ai_agent_lead_score was already non-null (skip_already_qualified=true).",
+        items: { type: "string" }
+      },
+      not_in_lens: {
+        type: "array",
+        description: "Lead ids that aren't members of the active lens \u2014 backend won't qualify them.",
+        items: { type: "string" }
+      },
+      reused: {
+        type: "boolean",
+        description: "True when an identical qualify_id was launched within the idempotency window."
+      },
+      seconds_since_original: { type: "number" },
+      cancelled: { type: "boolean", description: "True when ctx.signal aborted mid-flight." },
+      budget_exhausted: { type: "boolean", description: "True when total_budget_ms hit before all leads finished." },
+      quota_blocked: { type: "boolean", description: "True when quota was exhausted before launching all leads." },
+      region: { type: "string" },
+      _meta: { type: "object" }
+    },
+    required: ["kind", "region", "_meta"]
   },
   execute: async (client, params, ctx) => {
     const signal = ctx?.signal;
@@ -3756,6 +5015,11 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
     if (!ctx?.bulkTracker) {
       throw client.makeError("BULK_TRACKER_UNAVAILABLE", "No BulkTracker configured on this MCP instance", "leadbay_import_and_qualify needs a BulkTracker (qualify_id persistence). Upgrade to @leadbay/mcp \u22650.5.0 or set LEADBAY_BULK_STORE_ALLOW_MEMORY=1.", "");
     }
+    ctx?.progress?.({
+      progress: 1,
+      total: 3,
+      message: "Importing leads (phase 1/3 \u2014 preprocess + commit)"
+    });
     const importResult = await importLeads.execute(client, {
       domains: params.domains,
       records: params.records,
@@ -3825,6 +5089,11 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
         }
       };
     }
+    ctx?.progress?.({
+      progress: 2,
+      total: 3,
+      message: "Import committed; preparing qualification (phase 2/3)"
+    });
     const lensId = params.lensId ?? await client.resolveDefaultLens();
     const leadIdsFromImported = imported.map((l) => l.leadId);
     const leadIdSet = new Set(leadIdsFromImported);
@@ -3877,6 +5146,11 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
     } catch (err) {
       ctx?.logger?.warn?.(`qualify: question order unavailable (${err?.code ?? err?.message ?? "unknown"}) \u2014 falling back to alphabetical`);
     }
+    ctx?.progress?.({
+      progress: 3,
+      total: 3,
+      message: `Qualifying ${leadIds.length} lead${leadIds.length === 1 ? "" : "s"} (phase 3/3)`
+    });
     const fanOut = await fanOutWebFetchAndPoll(client, leadIds, {
       perLeadBudgetMs: perLeadBudget,
       totalDeadlineMs: totalDeadline,
@@ -3886,6 +5160,13 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
       skipAlreadyQualifiedLaunch: skipAlreadyQualified,
       ...questionOrder ? { questionOrder } : {}
     });
+    if (fanOut.cancelled) {
+      try {
+        await ctx.bulkTracker.markCancelled(reservation.record.bulk_id);
+      } catch (err) {
+        ctx?.logger?.warn?.(`import_and_qualify: tracker.markCancelled failed: ${err?.message ?? err}`);
+      }
+    }
     const qualified = fanOut.results.filter((r) => !r._stillRunning).map(({ _stillRunning, ...rest }) => rest);
     const notInLensSet = new Set(fanOut.not_in_lens);
     const stillRunningIds = new Set([
@@ -3963,6 +5244,11 @@ async function runPreview(client, params, ctx, perPhaseBudget, _totalBudget) {
   const upload = await client.requestRawBinary("POST", `/imports?file_name=${encodeURIComponent(fileName)}`, "text/csv", csv);
   const importId = upload.id;
   const signal = ctx?.signal;
+  ctx?.progress?.({
+    progress: 1,
+    total: 3,
+    message: "Preprocessing import (phase 1/3)"
+  });
   const deadline = Date.now() + perPhaseBudget;
   let fileImport = null;
   while (Date.now() < deadline) {
@@ -3972,6 +5258,11 @@ async function runPreview(client, params, ctx, perPhaseBudget, _totalBudget) {
     const r = await client.request("GET", `/imports/${importId}`);
     if (r.pre_processing?.finished) {
       fileImport = r;
+      ctx?.progress?.({
+        progress: 2,
+        total: 3,
+        message: "Preprocess complete; committing import (phase 2/3)"
+      });
       break;
     }
     await new Promise((res) => {
@@ -4411,6 +5702,18 @@ var LocalBulkStore = class {
       this.logger?.info?.(`bulk.launch_failed bulk_id=${bulk_id}`);
     });
   }
+  async markCancelled(bulk_id) {
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      const idx = all.findIndex((r) => r.bulk_id === bulk_id);
+      if (idx < 0) {
+        return;
+      }
+      all[idx] = { ...all[idx], status: "cancelled" };
+      await this.writeAll(all);
+      this.logger?.info?.(`bulk.cancelled bulk_id=${bulk_id}`);
+    });
+  }
   async get(bulk_id) {
     return this.mutex.run(async () => {
       const all = this.prune(await this.readAll());
@@ -4470,6 +5773,13 @@ async function createDefaultBulkStore(opts = {}) {
 // ../core/dist/composite/qualify-status.js
 var qualifyStatus = {
   name: "leadbay_qualify_status",
+  annotations: {
+    title: "Poll import-and-qualify status",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Retrieve the current state of an import_and_qualify launch by `qualify_id`. Returns the same `qualified[]` / `still_running[]` shape as the original composite, refreshed against the backend at call time. The handle is persisted to ~/.leadbay/bulks.json with a 30-day TTL and survives MCP restart.\n\nWhen to use: after leadbay_import_and_qualify returned a qualify_id with non-empty `still_running[]`, call this tool a few minutes later (or hours) to retrieve the now-completed qualifications without re-running the import or re-spending qualify quota.\nWhen NOT to use: as a substitute for leadbay_research_lead \u2014 that's a deeper per-lead profile and includes contacts. This tool is purely the qualification answers + signals_count.",
   inputSchema: {
     type: "object",
@@ -4479,7 +5789,70 @@ var qualifyStatus = {
         description: "UUIDv4 returned by leadbay_import_and_qualify when at least one lead was still running."
       }
     },
-    required: ["qualify_id"]
+    required: ["qualify_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      qualify_id: { type: "string", description: "Echoed UUIDv4 handle." },
+      launched_at: { type: "string", description: "ISO timestamp of original launch." },
+      status: { type: "string", description: "'launched' on success (other states surface as error envelopes)." },
+      import_ids: {
+        type: "array",
+        description: "Underlying file-import handle ids (one per chunk).",
+        items: { type: "string" }
+      },
+      lens_id: { type: "number", description: "Lens id the qualification ran against." },
+      lead_ids: {
+        type: "array",
+        description: "Lead UUIDs covered by this qualify_id (echoed from launch).",
+        items: { type: "string" }
+      },
+      qualified: {
+        type: "array",
+        description: "Leads whose qualification has settled. Each entry: {lead_id, qualification_summary, signals_count, ...}.",
+        items: { type: "object" }
+      },
+      still_running: {
+        type: "array",
+        description: "Leads still being qualified at refresh time.",
+        items: { type: "object" }
+      },
+      failed: {
+        type: "array",
+        description: "Per-lead errors observed at refresh (e.g., 404 on /web_fetch + /ai_agent_responses).",
+        items: { type: "object" }
+      },
+      not_in_lens: {
+        type: "array",
+        description: "Lead ids that exist in the org but aren't members of the active lens \u2014 backend won't qualify them; agent should stop polling.",
+        items: { type: "string" }
+      },
+      per_lead_budget_ms: {
+        type: "number",
+        description: "Caller-supplied per-lead timeout (informational only at status time)."
+      },
+      total_budget_ms: {
+        type: "number",
+        description: "Caller-supplied total timeout (informational only at status time)."
+      },
+      region: { type: "string" },
+      _meta: { type: "object" }
+    },
+    required: [
+      "qualify_id",
+      "status",
+      "import_ids",
+      "lens_id",
+      "lead_ids",
+      "qualified",
+      "still_running",
+      "failed",
+      "not_in_lens",
+      "region",
+      "_meta"
+    ]
   },
   execute: async (client, params, ctx) => {
     if (!isValidBulkId(params.qualify_id)) {
@@ -4502,18 +5875,36 @@ var qualifyStatus = {
     if (record.status === "failed") {
       throw client.makeError("BULK_LAUNCH_FAILED", "The original import_and_qualify launch failed; no qualifications were ordered", "Call leadbay_import_and_qualify again \u2014 the failed record won't block a fresh launch.", "");
     }
+    if (record.status === "cancelled") {
+      throw client.makeError("BULK_CANCELLED", "The qualify run was cancelled (ctx.signal aborted by the client mid-flight); no further qualifications are in flight", "Call leadbay_import_and_qualify again with the same input to relaunch \u2014 the cancelled record won't block a fresh launch.", "");
+    }
+    ctx?.progress?.({
+      progress: 1,
+      total: 3,
+      message: "Loading qualification questions\u2026"
+    });
     let questionOrder = void 0;
     try {
       const taste = await client.resolveTasteProfile();
       questionOrder = buildQuestionOrder(taste.qualificationQuestions ?? []);
     } catch {
     }
+    ctx?.progress?.({
+      progress: 2,
+      total: 3,
+      message: `Checking lens membership for ${record.lead_ids.length} lead${record.lead_ids.length === 1 ? "" : "s"}\u2026`
+    });
     let notInLensSet = /* @__PURE__ */ new Set();
     try {
       const pre = await prequalifiedLeads(client, record.lead_ids, record.lens_id, ctx);
       notInLensSet = pre.not_in_lens;
     } catch {
     }
+    ctx?.progress?.({
+      progress: 3,
+      total: 3,
+      message: `Refreshing qualification state for ${record.lead_ids.length} lead${record.lead_ids.length === 1 ? "" : "s"}\u2026`
+    });
     const fresh = await refreshLeadStates(client, record.lead_ids, questionOrder);
     const failed = [];
     const qualified = [];
@@ -4564,6 +5955,18 @@ var qualifyStatus = {
 var DEFAULT_CANDIDATE_COUNT = 25;
 var enrichTitles = {
   name: "leadbay_enrich_titles",
+  annotations: {
+    title: "Enrich contact titles across leads",
+    readOnlyHint: false,
+    // Mode A (no titles): non-destructive preview returning candidates.
+    // Mode B (with titles): launches enrichment job. Net classification is
+    // destructive because the dominant flow mutates state.
+    destructiveHint: true,
+    // Idempotent against the same selection + titles set (same hash → same
+    // bulk_id; backend silently no-ops on already-enriched contacts).
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Order contact enrichments by job title across many leads. Contacts are NOT returned by default with a lead (Leadbay keeps enrichment out-of-band to control cost); the agent requests them on demand via this tool when it's ready to actually reach out. Two modes: (A) NO titles param \u2014 returns the available titles + Leadbay's title_suggestions + auto_included_titles + a count of enrichable contacts, so the agent can ask the user which titles to enrich. (B) titles given \u2014 calls preview, then launches if there's anything enrichable. On 429 returns {status:'quota_exceeded'} cleanly. Selection lifecycle is wrapped in a try/finally so the user's selection is left clean even on error. When to use: as the agent's go-to enrichment entry point, immediately before proposing outreach. When NOT to use: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular). Speculatively, before the user has committed to outreaching \u2014 enrichment spends credits.",
   inputSchema: {
     type: "object",
@@ -4592,6 +5995,100 @@ var enrichTitles = {
         type: "boolean",
         description: "If true, don't launch \u2014 only preview."
       }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Branchy return shape; the `mode` (or `status`) field tells the agent which branch it got. Modes: 'discover' (no titles passed), 'preview_only' (no enrichable contacts), 'dry_run', 'already_launched' (idempotent reuse), 'launched_tracker_pending' (rare, soft-fail), 'launched' (happy path). Status: 'quota_exceeded' (429).",
+    properties: {
+      mode: {
+        type: "string",
+        description: "'discover' | 'preview_only' | 'dry_run' | 'already_launched' | 'launched_tracker_pending' | 'launched'."
+      },
+      status: {
+        type: "string",
+        description: "'quota_exceeded' on 429. Otherwise mode is set instead."
+      },
+      available_titles: {
+        type: "array",
+        description: "Titles available across the selection (discover/preview_only modes).",
+        items: { type: "string" }
+      },
+      recommendations: {
+        type: "array",
+        description: "Backend's title_suggestions (discover mode).",
+        items: { type: "string" }
+      },
+      auto_included: {
+        type: "array",
+        description: "Backend's auto_included_titles (discover mode).",
+        items: { type: "string" }
+      },
+      previously_enriched: {
+        type: "array",
+        description: "Titles previously enriched on this selection (discover mode).",
+        items: { type: "string" }
+      },
+      enrichable_contacts: {
+        type: "number",
+        description: "Count of enrichable contacts at preview time."
+      },
+      selected_lead_count: {
+        type: "number",
+        description: "How many leads the selection covers."
+      },
+      preview: {
+        type: "object",
+        description: "Backend BulkEnrichPreview payload (preview_only/dry_run/launched modes)."
+      },
+      launched: {
+        type: "boolean",
+        description: "True when an enrichment job is in flight on the backend."
+      },
+      would_launch: {
+        type: "object",
+        description: "What dry_run WOULD have launched (titles, email, phone)."
+      },
+      re_used: {
+        type: "boolean",
+        description: "True when an identical bulk was launched within the idempotency window (already_launched mode)."
+      },
+      bulk_id: {
+        type: "string",
+        description: "UUIDv4 to poll via leadbay_bulk_enrich_status."
+      },
+      launched_at: {
+        type: "string",
+        description: "ISO timestamp of the (re-used or fresh) launch."
+      },
+      durability: {
+        type: "string",
+        description: "'file' (persisted bulks.json) or 'memory'."
+      },
+      seconds_since_original_launch: {
+        type: "number",
+        description: "Age of the re-used bulk record (already_launched mode)."
+      },
+      titles: {
+        type: "array",
+        description: "Titles ordered (echoed at launch).",
+        items: { type: "string" }
+      },
+      email: { type: "boolean" },
+      phone: { type: "boolean" },
+      message: {
+        type: "string",
+        description: "Operator-facing summary of what happened."
+      },
+      next_action: {
+        type: "string",
+        description: "Concrete next-step instruction for the agent."
+      },
+      retry_after_seconds: {
+        type: ["number", "null"],
+        description: "Seconds until quota resets (quota_exceeded status)."
+      }
     }
   },
   execute: async (client, params, ctx) => {
@@ -4622,11 +6119,21 @@ var enrichTitles = {
         hint: "Pass leadIds explicitly or wait for the wishlist to compute"
       };
     }
+    ctx?.progress?.({
+      progress: 1,
+      total: 3,
+      message: `Selecting ${leadIds.length} lead${leadIds.length === 1 ? "" : "s"}\u2026`
+    });
     await client.acquireSelectionLock();
     try {
       const qs = leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
       await client.requestVoid("POST", `/leads/selection/select?${qs}`);
       try {
+        ctx?.progress?.({
+          progress: 2,
+          total: 3,
+          message: "Previewing enrichment (titles + counts)\u2026"
+        });
         const availableTitles = await client.request("GET", "/leads/selection/enrichment/job_titles");
         if (!params.titles || params.titles.length === 0) {
           let suggestions = [];
@@ -4720,14 +6227,24 @@ var enrichTitles = {
             };
           }
         }
+        ctx?.progress?.({
+          progress: 3,
+          total: 3,
+          message: `Launching enrichment for ${params.titles.length} title${params.titles.length === 1 ? "" : "s"}\u2026`
+        });
         try {
           await client.requestVoid("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
         } catch (err) {
+          const aborted = err?.name === "AbortError" || ctx?.signal?.aborted === true;
           if (bulkRecord && tracker) {
             try {
-              await tracker.markFailed(bulkRecord.bulk_id);
+              if (aborted) {
+                await tracker.markCancelled(bulkRecord.bulk_id);
+              } else {
+                await tracker.markFailed(bulkRecord.bulk_id);
+              }
             } catch (e) {
-              ctx?.logger?.warn?.(`enrich_titles: tracker.markFailed failed: ${e?.message ?? e}`);
+              ctx?.logger?.warn?.(`enrich_titles: tracker.${aborted ? "markCancelled" : "markFailed"} failed: ${e?.message ?? e}`);
             }
           }
           if (err?.code === "QUOTA_EXCEEDED") {
@@ -4804,6 +6321,13 @@ async function pMap(items, fn, concurrency) {
 }
 var bulkEnrichStatus = {
   name: "leadbay_bulk_enrich_status",
+  annotations: {
+    title: "Poll bulk-enrichment status",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Check status + per-lead contacts for a bulk enrichment you previously launched via leadbay_enrich_titles. Returns the bulk_id, progress per lead (done/total enrichable contacts), and overall progress. When include_contacts=true (opt-in), includes each contact's email/phone/job_title/enrichment.done. When to use: poll this after leadbay_enrich_titles returns a bulk_id. Default include_contacts=false for cheap status polls; set include_contacts=true once all_done flips for the final read. When NOT to use: as a substitute for leadbay_research_lead \u2014 that already includes enriched contacts for a single lead.",
   inputSchema: {
     type: "object",
@@ -4817,7 +6341,55 @@ var bulkEnrichStatus = {
         description: "If true, return the full contact list per lead (email, phone, enrichment.done). Default false \u2014 cheap status polls."
       }
     },
-    required: ["bulk_id"]
+    required: ["bulk_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      bulk_id: { type: "string", description: "Echoed UUIDv4 handle." },
+      launched_at: { type: "string", description: "ISO timestamp of /enrichment/launch ack." },
+      status: {
+        type: "string",
+        description: "'launched' on success. Errors return error envelopes (handled separately)."
+      },
+      durability: {
+        type: "string",
+        description: "'persistent' (file-backed bulks.json) or 'memory' (LEADBAY_BULK_STORE_ALLOW_MEMORY)."
+      },
+      titles: {
+        type: "array",
+        description: "Titles ordered at launch time (echoed from the original enrich_titles call).",
+        items: { type: "string" }
+      },
+      email: { type: "boolean", description: "True if email enrichment was requested." },
+      phone: { type: "boolean", description: "True if phone enrichment was requested." },
+      lens_id: { type: "number", description: "Lens id used to scope the enrichment." },
+      leads: {
+        type: "array",
+        description: "Per-lead rollup: {lead_id, enrichment_progress:{done,total}, contacts? (when include_contacts=true)}.",
+        items: { type: "object" }
+      },
+      overall_progress: {
+        type: "object",
+        description: "Aggregate progress across all leads.",
+        properties: {
+          done: { type: "number" },
+          total: { type: "number" },
+          done_ratio: { type: "number" }
+        }
+      },
+      all_done: {
+        type: "boolean",
+        description: "True when overall_progress.done === total AND no partial_failures."
+      },
+      partial_failures: {
+        type: "array",
+        description: "Per-lead errors observed during contacts fan-out (omitted when no failures).",
+        items: { type: "object" }
+      }
+    },
+    required: ["bulk_id", "status", "leads", "overall_progress", "all_done"]
   },
   execute: async (client, params, ctx) => {
     if (!isValidBulkId(params.bulk_id)) {
@@ -4886,6 +6458,18 @@ var bulkEnrichStatus = {
         launched_at: record.launched_at
       };
     }
+    if (record.status === "cancelled") {
+      return {
+        error: true,
+        code: "BULK_CANCELLED",
+        message: "The bulk was cancelled (ctx.signal aborted by the client mid-launch). No further work is in flight.",
+        hint: "Call leadbay_enrich_titles again with the same titles to relaunch \u2014 the cancelled record won't block a fresh launch.",
+        bulk_id: record.bulk_id,
+        launched_at: record.launched_at
+      };
+    }
+    let doneSoFar = 0;
+    const totalLeads = record.lead_ids.length;
     const results = await pMap(record.lead_ids, async (leadId) => {
       try {
         const out = await getContacts.execute(client, { leadId });
@@ -4893,6 +6477,12 @@ var bulkEnrichStatus = {
         const enrichable = contacts.filter((c) => c && c.enrichment);
         const done = enrichable.filter((c) => c.enrichment?.done === true).length;
         const total = enrichable.length;
+        doneSoFar += 1;
+        ctx?.progress?.({
+          progress: doneSoFar,
+          total: totalLeads,
+          message: `Fetched contacts for ${leadId} (${doneSoFar}/${totalLeads})`
+        });
         return {
           kind: "ok",
           lead_id: leadId,
@@ -4901,6 +6491,12 @@ var bulkEnrichStatus = {
           contacts: includeContacts ? contacts : void 0
         };
       } catch (err) {
+        doneSoFar += 1;
+        ctx?.progress?.({
+          progress: doneSoFar,
+          total: totalLeads,
+          message: `Fetch failed for ${leadId} (${doneSoFar}/${totalLeads}): ${err?.code ?? "UNKNOWN"}`
+        });
         return {
           kind: "fail",
           lead_id: leadId,
@@ -5041,6 +6637,17 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
 }
 var adjustAudience = {
   name: "leadbay_adjust_audience",
+  annotations: {
+    title: "Adjust lens audience filters",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Each call MERGES new criteria into the lens config; calling twice
+    // with the same args produces the same final state (last write wins on
+    // overlapping criteria, but the merge is deterministic). Per spec
+    // idempotentHint is about same observable outcome — re-call is safe.
+    idempotentHint: true,
+    openWorldHint: true
+  },
   description: "Restrict (or expand) the lens audience by sector / size. Free-text sectors are auto-resolved against the sector taxonomy; ambiguous matches are surfaced to the agent rather than guessed silently. Permission routing is hidden: the default lens auto-clones to a new user lens; an org-level lens defaults to a per-user draft (admins can override with save_for_org:true). Filter MERGES with existing criteria (unrelated criteria are not dropped). When to use: when the user wants to see different kinds of leads (sector / size / etc.). When NOT to use: to refine BEYOND firmographics \u2014 that's leadbay_refine_prompt.",
   inputSchema: {
     type: "object",
@@ -5077,7 +6684,34 @@ var adjustAudience = {
         type: "string",
         description: "Name to use when this composite has to clone the default lens (otherwise auto-named)"
       }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Two return shapes: 'ambiguous_sectors' when free-text sectors matched multiple candidates (agent re-calls with sector_ids), 'applied' on success.",
+    properties: {
+      status: {
+        type: "string",
+        description: "'ambiguous_sectors' or 'applied'."
+      },
+      sector_ambiguities: {
+        type: "array",
+        description: "Per ambiguous text: {sector_text, matches:[{id, name, score}]}. Agent picks an id and re-calls.",
+        items: { type: "object" }
+      },
+      message: { type: "string" },
+      lens_used: {
+        type: "object",
+        description: "Resolved lens metadata: {id, name, was_draft, was_new, save_for_org}."
+      },
+      filter_applied: {
+        type: "object",
+        description: "The merged FilterPayload that was POSTed to the lens."
+      },
+      _meta: { type: "object" }
+    },
+    required: ["status"]
   },
   execute: async (client, params, ctx) => {
     const me = await client.resolveMe();
@@ -5151,7 +6785,7 @@ var adjustAudience = {
               error: true,
               code: "ORPHAN_DRAFT",
               message: `Draft ${targetLensId} created but filter update failed; draft cleanup also failed`,
-              hint: `Manually delete draft lens ${targetLensId} via the Leadbay UI`,
+              hint: `Use leadbay_promote_lens or leadbay_update_lens to recover, or open https://leadbay.app/lenses to manually delete draft lens ${targetLensId}.`,
               orphan_draft_id: targetLensId
             };
           }
@@ -5189,6 +6823,16 @@ var DEFAULT_POLL_ATTEMPTS = 2;
 var DEFAULT_POLL_GAP_MS = 5e3;
 var refinePrompt = {
   name: "leadbay_refine_prompt",
+  annotations: {
+    title: "Refine the audience prompt",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Sets the org's user_prompt and may trigger a clarification flow. Each
+    // call replaces the prior prompt — a second call with a different
+    // instruction is NOT idempotent (the second prompt wins).
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Refine the kind of leads Leadbay surfaces, beyond firmographics. Free-text instruction (e.g. 'focus on hospitals running their own IT'). Sets the org's user_prompt; if the new prompt produces ambiguous criteria, Leadbay raises a clarification question, which this composite polls for and surfaces. Admin-only on the backend (will return 403 for non-admins). When to use: when audience filters (leadbay_adjust_audience) aren't enough. When NOT to use: to answer a pending clarification \u2014 that's leadbay_answer_clarification.",
   inputSchema: {
     type: "object",
@@ -5207,7 +6851,44 @@ var refinePrompt = {
         description: "If true, return the call shape WITHOUT setting the prompt"
       }
     },
-    required: ["prompt"]
+    required: ["prompt"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Multiple return shapes by status. dry_run, applied (with optional clarified_via_elicit), or clarification_pending.",
+    properties: {
+      dry_run: { type: "boolean", description: "True when dry_run:true was passed (no state change)." },
+      would_call: {
+        type: "object",
+        description: "Dry-run preview of the POST that would have been issued."
+      },
+      status: {
+        type: "string",
+        description: "'applied' (prompt set; intelligence regenerating) or 'clarification_pending' (telephone path)."
+      },
+      computing_intelligence: {
+        type: "boolean",
+        description: "True when intelligence is regenerating after the prompt set."
+      },
+      clarified_via_elicit: {
+        type: "boolean",
+        description: "True when the clarification was answered via the client's elicitation UI (not via telephone)."
+      },
+      message: {
+        type: "string",
+        description: "Operator-facing summary."
+      },
+      clarification: {
+        type: "object",
+        description: "ClarificationPayload returned by the backend (clarification_pending path)."
+      },
+      next_action: {
+        type: "string",
+        description: "Concrete next-step instruction for the agent."
+      },
+      _meta: { type: "object" }
+    }
   },
   execute: async (client, params, ctx) => {
     const me = await client.resolveMe();
@@ -5259,6 +6940,58 @@ var refinePrompt = {
       }
     }
     if (clarification) {
+      if (ctx?.elicit) {
+        const opts = clarification.options ?? [];
+        const requestedSchema = opts.length > 0 ? {
+          type: "object",
+          properties: {
+            option_id: {
+              type: "string",
+              title: "Pick one",
+              description: "Choose the option that best matches your intent.",
+              enum: opts.filter((o) => o.id).map((o) => o.id),
+              enumNames: opts.filter((o) => o.id).map((o) => o.label)
+            }
+          },
+          required: ["option_id"]
+        } : {
+          type: "object",
+          properties: {
+            text_answer: {
+              type: "string",
+              title: "Answer",
+              description: "Free-text answer to the clarification. Plain English."
+            }
+          },
+          required: ["text_answer"]
+        };
+        try {
+          const elicited = await ctx.elicit({
+            message: clarification.question,
+            requestedSchema
+          });
+          if (elicited.action === "accept" && elicited.content) {
+            const body = typeof elicited.content.option_id === "string" ? { option_id: elicited.content.option_id } : typeof elicited.content.text_answer === "string" ? { text_answer: elicited.content.text_answer } : null;
+            if (body) {
+              try {
+                await client.requestVoid("POST", `/organizations/${orgId}/pick_clarification`, body);
+                client.invalidateMe();
+                return {
+                  status: "applied",
+                  clarified_via_elicit: true,
+                  computing_intelligence: true,
+                  message: "Prompt set + clarification answered via the client's elicitation UI. Leadbay is regenerating intelligence.",
+                  _meta: { region: client.region }
+                };
+              } catch (err) {
+                ctx?.logger?.warn?.(`refine_prompt: pick_clarification POST failed after elicit: ${err?.message ?? err?.code ?? err}`);
+              }
+            }
+          }
+        } catch (err) {
+          ctx?.logger?.warn?.(`refine_prompt: elicit failed: ${err?.message ?? err?.code ?? err} \u2014 falling back to telephone path`);
+        }
+      }
       return {
         status: "clarification_pending",
         clarification,
@@ -5278,13 +7011,44 @@ var refinePrompt = {
 // ../core/dist/composite/answer-clarification.js
 var answerClarification = {
   name: "leadbay_answer_clarification",
+  annotations: {
+    title: "Answer pending clarification",
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Records a one-time answer that becomes the new user_prompt and
+    // triggers regeneration. Re-calling with a different answer wins;
+    // not idempotent.
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Answer the pending clarification question Leadbay raised after a refine_prompt. The answer is stored as the new user_prompt and triggers regeneration. Pass option_id (preferred \u2014 pick from the offered options) or text_answer (free-text). Admin-only. When to use: after leadbay_refine_prompt returns status='clarification_pending'. When NOT to use: to set a brand-new prompt \u2014 use leadbay_refine_prompt.",
   inputSchema: {
     type: "object",
     properties: {
       option_id: { type: "string", description: "Id of one of the clarification's options" },
       text_answer: { type: "string", description: "Free-text answer (overrides option_id)" }
-    }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        description: "'answered' (recorded; intelligence regenerating) or 'no_pending_clarification' (nothing to answer)."
+      },
+      recorded_as_user_prompt: {
+        type: "boolean",
+        description: "True when the answer was stored as the org's new user_prompt."
+      },
+      message: { type: "string" },
+      hint: {
+        type: "string",
+        description: "Operator-facing next-step (no_pending_clarification path)."
+      },
+      _meta: { type: "object" }
+    },
+    required: ["status"]
   },
   execute: async (client, params, ctx) => {
     if (!params.option_id && !params.text_answer) {
@@ -5341,6 +7105,13 @@ function formatNoteWithVerification(note, v) {
 }
 var reportOutreach = {
   name: "leadbay_report_outreach",
+  annotations: {
+    title: "Report outreach to Leadbay",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
   description: "Log an outreach action (email, call, message, meeting) on a lead so the human team using Leadbay sees the progress in their UI. Writes a NOTE on the lead and (optionally) sets an EPILOGUE status (still chasing, meeting booked, etc.). VERIFICATION REQUIRED: every call must include verification={source: 'gmail_message_id'|'calendar_event_id'|'user_confirmed', ref: '<id-or-confirmation>'} to prevent hallucinated outreach poisoning the pipeline. The verification is appended to the note body. Bulk variant: pass lead_ids=[uuid,...] instead of lead_id (epilogue is bulk-native; notes fan out per-lead). When to use: AFTER actually emailing/calling/meeting/messaging a contact, OR after a substantive decision the user wants logged (skip, save, hand off). When NOT to use: BEFORE doing the outreach (use dry_run:true to validate args first); without verification (call will be rejected); from a flow where the user did not consent to having actions logged automatically.",
   optional: true,
   write: true,
@@ -5368,14 +7139,78 @@ var reportOutreach = {
           source: { type: "string" },
           ref: { type: "string" }
         },
-        required: ["source", "ref"]
+        required: ["source", "ref"],
+        // Security-load-bearing: the verification field prevents the agent from
+        // poisoning the SDR pipeline with hallucinated outreach. Extra keys here
+        // would create an injection vector (e.g., agent passes
+        // verification.bypass="true"). Hard-rejected per second-opinion #3.
+        additionalProperties: false
       },
       dry_run: {
         type: "boolean",
         description: "If true, return what WOULD be called without writing anything"
       }
     },
-    required: ["note", "verification"]
+    required: ["note", "verification"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "Either the dry_run shape (dry_run:true with would_write_notes / would_set_epilogue) OR the live result (notes:{succeeded,failed} + epilogue:{status,applied,error?} + verification + _meta). Schema declares both shapes; the dry_run discriminator picks which sub-shape applies.",
+    properties: {
+      // dry_run discriminator + dry_run subshape (from before iter 13)
+      dry_run: { type: "boolean" },
+      would_write_notes: {
+        type: "array",
+        description: "On dry_run: the per-lead POST shapes that WOULD be issued.",
+        items: { type: "object" }
+      },
+      would_set_epilogue: {
+        type: ["object", "null"],
+        description: "On dry_run: the epilogue POST shape that WOULD be issued."
+      },
+      // Live subshape — what execute() actually returns when dry_run is false.
+      notes: {
+        type: "object",
+        description: "Per-lead note-write outcome (split into succeeded / failed sub-arrays).",
+        properties: {
+          succeeded: {
+            type: "array",
+            items: { type: "object" }
+          },
+          failed: {
+            type: "array",
+            items: { type: "object" }
+          }
+        }
+      },
+      epilogue: {
+        type: "object",
+        description: "Epilogue status outcome: status (the wire-format string written to /leads/epilogue, or null when not requested), applied (true/false), error (when applied=false).",
+        properties: {
+          status: { type: ["string", "null"] },
+          applied: { type: "boolean" },
+          error: { type: "string" }
+        }
+      },
+      verification: {
+        type: "object",
+        description: `Effective verification used (after elicit override). Useful for the client UI to render "logged with proof X". When source=user_confirmed AND ctx.elicit was available, ref is the user's literal text typed into the client; otherwise it's the agent-supplied ref.`,
+        properties: {
+          source: { type: "string" },
+          ref: { type: "string" }
+        }
+      },
+      confirmed_via: {
+        type: "string",
+        description: "Audit trail of how verification was obtained: 'elicit' (user typed into client UI \u2014 anti-poisoning), 'agent_supplied' (legacy path; user_confirmed source with no elicit), 'non_user_confirmed' (gmail_message_id or calendar_event_id \u2014 agent can't fabricate these)."
+      },
+      _meta: {
+        type: "object",
+        description: "Operator context: region.",
+        properties: { region: { type: "string" } }
+      }
+    }
   },
   execute: async (client, params, ctx) => {
     if (!params.verification || !params.verification.source || !params.verification.ref) {
@@ -5386,6 +7221,16 @@ var reportOutreach = {
         hint: "Provide verification.source as one of: gmail_message_id (the Gmail message id from sending), calendar_event_id (the event id from booking), or user_confirmed (set verification.ref to the user's literal confirmation in chat)."
       };
     }
+    const verificationKeys = Object.keys(params.verification);
+    const extraKeys = verificationKeys.filter((k) => k !== "source" && k !== "ref");
+    if (extraKeys.length > 0) {
+      return {
+        error: true,
+        code: "VERIFICATION_EXTRA_KEYS",
+        message: `verification accepts only {source, ref}; rejected extra key(s): ${extraKeys.join(", ")}`,
+        hint: "Drop the extra key(s). Verification is security-sensitive \u2014 extra fields are not silently accepted."
+      };
+    }
     if (!VALID_SOURCES.has(params.verification.source)) {
       return {
         error: true,
@@ -5399,10 +7244,59 @@ var reportOutreach = {
         error: true,
         code: "BAD_INPUT",
         message: "Provide lead_id (single) or lead_ids (bulk)",
-        hint: "lead_id for one lead; lead_ids: [uuid, ...] for many"
+        hint: "Set lead_id to one UUID for a single-lead call, or pass lead_ids: [uuid, ...] for a bulk call. Use leadbay_pull_leads to discover candidate IDs."
       };
     }
-    const noteBody = formatNoteWithVerification(params.note, params.verification);
+    let confirmedVia = params.verification.source === "user_confirmed" ? "agent_supplied" : "non_user_confirmed";
+    let effectiveVerification = params.verification;
+    if (!params.dry_run && params.verification.source === "user_confirmed" && typeof ctx?.elicit === "function") {
+      try {
+        const targetIds = params.lead_ids ?? [params.lead_id];
+        const leadCount = targetIds.length;
+        const elicitMsg = leadCount === 1 ? `An AI agent wants to log outreach on lead ${targetIds[0]}: "${params.note}". The agent claims you confirmed this. Type your literal confirmation to proceed; cancel to reject.` : `An AI agent wants to log outreach on ${leadCount} leads: "${params.note}". The agent claims you confirmed this. Type your literal confirmation to proceed; cancel to reject.`;
+        const result = await ctx.elicit({
+          message: elicitMsg,
+          requestedSchema: {
+            type: "object",
+            properties: {
+              confirmation: {
+                type: "string",
+                title: "Your confirmation",
+                description: "Type a few words confirming the outreach actually happened. This text becomes the audit-trail entry."
+              }
+            },
+            required: ["confirmation"]
+          }
+        });
+        if (result.action === "accept") {
+          const userText = String(result.content?.confirmation ?? "").trim();
+          if (userText.length > 0) {
+            effectiveVerification = {
+              source: "user_confirmed",
+              ref: userText
+            };
+            confirmedVia = "elicit";
+          } else {
+            return {
+              error: true,
+              code: "OUTREACH_USER_CANCELLED",
+              message: "User confirmation was empty; outreach not logged.",
+              hint: "Re-call leadbay_report_outreach after the user types a non-empty confirmation, or use a gmail_message_id / calendar_event_id source instead."
+            };
+          }
+        } else {
+          return {
+            error: true,
+            code: "OUTREACH_USER_CANCELLED",
+            message: `User ${result.action === "decline" ? "declined" : "cancelled"} the outreach confirmation; nothing was logged.`,
+            hint: "Re-call leadbay_report_outreach with verification.source set to gmail_message_id or calendar_event_id when the user is unwilling to type a confirmation."
+          };
+        }
+      } catch (err) {
+        ctx?.logger?.warn?.(`report_outreach: ctx.elicit failed (${err?.code ?? err?.message ?? err}) \u2014 falling back to agent-supplied verification`);
+      }
+    }
+    const noteBody = formatNoteWithVerification(params.note, effectiveVerification);
     let epilogueWire = null;
     if (params.epilogue_status) {
       const w = EPILOGUE_LABEL_MAP[params.epilogue_status];
@@ -5469,7 +7363,17 @@ var reportOutreach = {
         status: epilogueWire,
         ...epilogueResult
       },
-      verification: params.verification,
+      verification: effectiveVerification,
+      // iter-22: audit-trail field. Tells the SDR team which path was taken
+      // for this call:
+      //   "elicit" = the user typed the confirmation directly via the
+      //              client UI (anti-poisoning shape).
+      //   "agent_supplied" = source was user_confirmed but ctx.elicit was
+      //              unavailable / failed; agent's ref was accepted.
+      //   "non_user_confirmed" = source was gmail_message_id or
+      //              calendar_event_id (agent doesn't get to fabricate
+      //              these — they're external ids).
+      confirmed_via: confirmedVia,
       _meta: { region: client.region }
     };
   }