@leadbay/mcp 0.6.3 → 0.7.1

package/dist/{chunk-QAOJARMK.js → chunk-3WNCQ7MP.js}

@@ -532,6 +532,444 @@ function parseRetryAfter(value) {
   return null;
 }
 
+// ../core/dist/tool-descriptions.generated.js
+var leadbay_account_status = `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.
+`;
+var leadbay_add_note = `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, including meaningful per-lead notes/context preserved from an imported file after the import returns lead IDs.
+
+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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_adjust_audience = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_answer_clarification = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_bulk_enrich_status = `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.
+`;
+var leadbay_bulk_qualify_leads = `Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch). Pass \`wait_for_completion:false\` to return quickly with \`{status:'running', qualify_id}\`; poll leadbay_qualify_status with that id. With \`wait_for_completion\` omitted/true, the legacy behavior polls 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).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_clear_selection = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_clear_user_prompt = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_create_custom_field = `Create an org-level CRM custom field for imports, then use the returned \`mapping_value\` in leadbay_import_leads / leadbay_import_and_qualify mappings. Use when the user's file contains valuable columns that do not fit Leadbay's standard fields, such as source-system deep links, source record IDs, campaign provenance, or user-requested enrichment attributes.
+
+For HubSpot record links, prefer \`type:'EXTERNAL_ID'\` with \`config.url_template\` and import only the stable HubSpot id as the CSV value. Example: create field name 'HubSpot Contact', type 'EXTERNAL_ID', config \`{url_template:'https://app.hubspot.com/contacts/<portal-id>/record/0-1/{value}'}\`; then map \`hubspot_id\` to the returned \`mapping_value\`. If only a full URL column exists and the id cannot be safely extracted, use a TEXT field instead.
+
+WHEN TO USE: after leadbay_list_mappable_fields shows no suitable existing custom field and preserving the column matters to the user's goal.
+
+WHEN NOT TO USE: for standard company/contact data that maps to LEAD_WEBSITE, LEAD_NAME, CONTACT_EMAIL, etc.; do not create custom fields for noisy scraper notes unless the user explicitly asks to preserve them.
+`;
+var leadbay_create_lens = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_create_lens_draft = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_deselect_leads = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_discover_leads = `Get AI-recommended leads from Leadbay. Returns paginated lead summaries with scores, AI summaries, tags, and recommended contacts. Auto-resolves to the active lens if \`lensId\` is omitted; \`count\` is capped at 50 per page.
+
+WHEN TO USE: low-level \u2014 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.
+`;
+var leadbay_dismiss_clarification = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_enrich_contacts = `Order email and/or phone enrichment for a specific contact. Performs an advisory credit check, then tries the paid-contact path and falls back to the org-contact path on NOT_FOUND. Consumes enrichment credits.
+
+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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_enrich_titles = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_get_clarification = `Check whether Leadbay has a pending clarification question \u2014 a question raised when refining the intelligence prompt produced contradictory or ambiguous criteria. Returns \`{pending: false, clarification: 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.
+`;
+var leadbay_get_contacts = `Get contacts for a lead, including enriched email and phone data. Returns both organization contacts and enrichable contacts with IDs, tagged with \`source:'org'|'paid'\`.
+
+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.
+`;
+var leadbay_get_enrichment_job_titles = `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.
+`;
+var leadbay_get_epilogue_responses = `Read the lead's epilogue history \u2014 what status (still chasing, meeting booked, etc.) was set when, and by whom. Paginated (\`count\` 1-200 default 20, \`page\` 0-indexed).
+
+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.
+`;
+var leadbay_get_lead_activities = `Get prospecting activity history for a lead (emails sent, calls made, status changes, notes). Each entry is \`{type, date}\`; older activities are trimmed by \`count\` (max 100, default 50).
+
+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.
+`;
+var leadbay_get_lead_notes = `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.
+`;
+var leadbay_get_lead_profile = `Get a full lead profile including company details, AI qualification scores, web insights, and contacts. Also marks the lead as SEEN+CLICKED in the user's lens so it ages out of the "new" Discover view (fire-and-forget; profile fetch never blocks on it).
+
+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.
+`;
+var leadbay_get_lens_filter = `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.
+`;
+var leadbay_get_lens_scoring = `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.
+`;
+var leadbay_get_prospecting_actions = `Read the CRM-style activity log for a lead (calls, emails, meetings \u2014 actions performed by humans or prior agent runs). Paginated (\`count\` 1-200 default 20, \`page\` 0-indexed).
+
+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.
+`;
+var leadbay_get_quota = `Read remaining quota / spend across daily, weekly, and 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.
+`;
+var leadbay_get_selection_ids = `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).
+`;
+var leadbay_get_taste_profile = `Get the user's Ideal Buyer Profile, purchase-intent tags, and qualification questions. The result is cached on the client. Returns an operator \`hint\` when no profile is configured yet.
+
+WHEN TO USE: at the very start of a session to understand what kind of leads the user is looking for.
+
+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).
+`;
+var leadbay_get_user_prompt = `Read the org's intelligence-refinement prompt (free-text instruction that steers lead recommendations beyond firmographics). Returns \`{prompt: null, set: false}\` when none is configured (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.
+`;
+var leadbay_get_web_fetch = `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.
+`;
+var leadbay_import_and_qualify = `Import + qualify leads in one call. Pass either \`domains: [{domain, name?}]\` (Mode A) OR \`records[]\` with \`mappings\` (Mode B). At least one mapped field must be LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE. Discover the org's mappable surface via \`leadbay_list_mappable_fields\`. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan \u2192 resolve \u2192 preserve \u2192 commit phases.
+
+WHEN TO USE: agent has a list of companies (domains, or CSV-shaped rows from the user's CRM) and wants the full AI qualification \u2014 qualification answers, web-research signals \u2014 without orchestrating import + bulk_qualify_leads + lead_profile chains by hand.
+
+WHEN NOT TO USE: discovery (use leadbay_pull_leads); single-lead deep dive (use leadbay_research_lead); high-cadence or untrusted automation \u2014 this mutates user state and consumes ai_rescore + web_fetch quota.
+
+Budgets: \`total_budget_ms\` caps wall-clock; \`per_lead_budget_ms\` caps each lead's poll. For short transport timeouts, pass \`wait_for_completion:false\` and poll \`leadbay_import_status\`. Outputs \`qualified[]\`, \`still_running[]\`, \`not_imported[]\`, \`qualify_id\` (resumable handle). Idempotent within a 5-min window. \`dry_run:'preview'\` returns mapping hints + custom-field candidates without importing.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+
+
+Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role; active billing. Imported leads are NOT auto-promoted to the Monitor view; lens-scoring threshold decides.
+`;
+var leadbay_import_leads = `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. For MCP clients with short transport timeouts, pass \`wait_for_completion:false\` to return quickly with \`{status:'running', handle_id}\`; poll leadbay_import_status with that handle. For end-to-end import+qualify in one call, prefer leadbay_import_and_qualify. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan \u2192 resolve \u2192 preserve \u2192 commit phases.
+
+TWO MODES: (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. (B) Custom records + mapping \u2014 pass \`records: [{Col1, Col2, ...}]\` plus \`mappings.fields: {Col1: 'LEAD_NAME', ...}\`. \`mappings.fields\` must include LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE (resolver needs at least one identity key). Pass exactly one of \`domains\` / \`records\`. Reserved column \`MCP_ROW_ID\` cannot appear in records/mappings \u2014 the tool injects it for stable reconciliation.
+
+MUTATES USER STATE: each call creates a row in the user's CRM-imports list (visible in the web UI) and touches onboarding state. Suitable for occasional automation, NOT for high-cadence (>5 calls/day). Imported leads are NOT auto-promoted to the user's Monitor view; lens-scoring threshold decides. For messy files call leadbay_resolve_import_rows first, then pass \`records_for_import\`/\`mappings_for_import\` here. Agents should inspect every column, build a preservation plan, and pass an explicit final mapping. For each meaningful column decide standard field, CONTACT_* field, Leadbay note, custom field, derived helper, or skip with a reason. For contact-only exports, derive a company-domain column from CONTACT_EMAIL only when it's a real business domain. Multiple rows can share the same LEADBAY_ID and import as separate contacts on that lead. Custom fields use \`CUSTOM.<id>\` in \`mappings.fields\` or the \`mappings.custom_fields\` shorthand. For source-system deep links create a custom field via leadbay_create_custom_field first (prefer EXTERNAL_ID + url_template). Preserve meaningful per-lead notes by calling leadbay_add_note after import returns lead IDs.
+
+WHEN TO USE: you have a list of company domains from another system (CRM, analytics, email correspondents) and need stable Leadbay leadIds; or CRM-shaped rows with custom columns and want to drive the wizard with explicit field mappings.
+
+WHEN 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; when you also want qualification in the same call (use leadbay_import_and_qualify).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+
+
+Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role on the Leadbay account; active billing.
+`;
+var leadbay_import_status = `Retrieve the current state of an async lead import. Pass \`handle_id\` returned by \`leadbay_import_leads({wait_for_completion:false})\`, or pass legacy \`importIds[]\` to inspect backend wizard rows. This status call performs a single refresh pass and never polls in a loop.
+
+WHEN TO USE: after leadbay_import_leads or leadbay_import_and_qualify returns \`{status:'running', handle_id}\` for the import phase, call this tool later to retrieve progress or the final import result without re-running the import.
+
+WHEN NOT TO USE: for qualification handles returned as \`qualify_id\` \u2014 use leadbay_qualify_status for those; or when you still want the legacy blocking behavior from leadbay_import_leads with \`wait_for_completion=true\`.
+`;
+var leadbay_launch_bulk_enrichment = `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. \`dry_run:true\` returns the call shape without contacting the backend.
+
+WHEN TO USE: low-level.
+
+WHEN NOT TO USE: from agent flow \u2014 leadbay_enrich_titles handles selection lifecycle, preview, launch, and cleanup.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_list_lenses = `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\`.
+`;
+var leadbay_list_mappable_fields = `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.
+
+For contact exports, map person data to CONTACT_* fields and still provide parent-company identity via LEADBAY_ID/LEAD_WEBSITE/LEAD_NAME/CRM_ID/SIREN. When contact emails contain business domains, agents may derive a clean company-domain column for LEAD_WEBSITE only when the domain agrees with the row's company/deal/brand context, while preserving the original email as CONTACT_EMAIL. For import files, audit every meaningful source column. If no standard/contact field fits, preserve the data by creating or reusing a custom field unless the column is blank, duplicate plumbing, raw unparsed noise after useful extraction, or harmful to data quality. For HubSpot or other source-system deep links, create or reuse an EXTERNAL_ID/TEXT custom field with leadbay_create_custom_field, then map the source id/link to the returned \`mapping_value\`. Backend mapping_hints are advisory only; for contact files, do not accept hints such as first_name -> LEAD_NAME when the column is clearly a person field.
+
+Optional \`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). Saves a separate preview round-trip.
+
+WHEN 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 without for_records, ~5\u201310s with) but unnecessary if the agent has already cached the catalog within the same conversation.
+`;
+var leadbay_list_sectors = `List the sector taxonomy (id + display name in the requested language). Default: \`lang\` follows the caller's language; \`includeInvisible=false\` returns ~1,091 visible sectors.
+
+WHEN TO USE: to resolve a free-text sector name (e.g. "Healthcare") into the sector ids that leadbay_adjust_audience needs.
+
+WHEN NOT TO USE: when you already have sector ids \u2014 pass them directly.
+`;
+var leadbay_login = `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. On success, sets the client's bearer token and switches the active region if needed.
+
+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 \u2014 you'll just overwrite it. The user needs a Leadbay account first; they can register at https://wow.leadbay.ai/?register=true.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_pick_clarification = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_prepare_outreach = `Prepare an outreach package for a single lead: recommended contact + enriched contact details + AI summary. Optionally trigger contact enrichment in-flight (\`enrich:true\`); enrichment is async, so poll leadbay_get_contacts after ~60s if you need the result inline.
+
+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).
+`;
+var leadbay_preview_bulk_enrichment = `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.
+`;
+var leadbay_promote_lens = `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).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_pull_leads = `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 (removed in v0.2.0).
+`;
+var leadbay_qualify_lead = `Trigger AI qualification for a single lead (web fetch + AI rescore). The operation is asynchronous \u2014 results take ~60s. \`forceFetch:true\` re-runs even if recent data exists.
+
+WHEN TO USE: low-level \u2014 when you need to kick qualification on exactly one lead without composite orchestration.
+
+WHEN NOT TO USE: as the agent's bulk-qualify path \u2014 use leadbay_bulk_qualify_leads, which paginates past already-qualified leads, fans out, polls, and bails out cleanly on 429.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_qualify_status = `Retrieve the current state of an import_and_qualify (or bulk_qualify_leads) 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.
+
+WHEN TO USE: after leadbay_import_and_qualify or leadbay_bulk_qualify_leads 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.
+
+WHEN 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.
+`;
+var leadbay_recall_ordered_titles = `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 \u2014 a selection-scoped preview call that reads \`previously_enriched_titles\` from the backend (newer prod field). (2) FALLBACK \u2014 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.
+`;
+var leadbay_refine_prompt = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_remove_epilogue = `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).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_report_outreach = `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.). Bulk variant: pass \`lead_ids=[uuid,...]\` instead of \`lead_id\` (epilogue is bulk-native; notes fan out per-lead).
+
+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. Skipping or fabricating verification poisons the human team's pipeline.
+
+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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_research_company = `Deep-dive research on a specific company by NAME (fuzzy match against the active lens's wishlist). Pass \`companyName\` (matches the top-scoring lead with that name) or \`leadId\` (takes precedence when both supplied).
+
+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).
+`;
+var leadbay_research_lead = `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.)
+`;
+var leadbay_resolve_import_rows = `Resolve messy CSV-shaped lead rows against Leadbay before file import. The tool sends each row's available identity signals to \`POST /leads/resolve\`, returns matched lead IDs or ambiguous candidate IDs, and produces \`records_for_import\` plus a SAFE identity-only \`mappings_for_import\` starting point for leadbay_import_leads / leadbay_import_and_qualify. This tool deliberately does not try to understand every CSV dialect; the agent should inspect the file, derive clean helper columns when useful, pass explicit \`identity_mappings\`, and build the final CRM mapping from \`mapping_guidance\`.
+
+WHEN TO USE: before importing user-supplied files when domains, names, CRM IDs, registry numbers, or Leadbay IDs may be inconsistently formatted; when the agent needs to pre-resolve messy rows, inspect ambiguous candidates, or prepare LEADBAY_ID values for the import composites. For contact-only files, first derive company website/domain from business contact emails where possible, while ignoring consumer mailbox domains. Deterministic matches get a LEADBAY_ID column inserted so the standard import commits immediately. Ambiguous rows are deliberately left without LEADBAY_ID; inspect candidates and choose one only when the evidence is good. Rows with websites but no match can still be imported; Leadbay may crawl and match them later, and leadbay_import_status can surface late matches.
+
+WHEN NOT TO USE: for prospect discovery from scratch (use leadbay_pull_leads); for one known company profile (use leadbay_research_company / leadbay_research_lead); or when the file already has clean, final LEADBAY_ID/CRM_ID/SIREN mappings and no row-level identity disambiguation is needed.
+`;
+var leadbay_select_leads = `Add leads to the user's transient selection (used by selection-scoped bulk operations). Accepts 1-1000 \`leadIds\` per call.
+
+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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_set_active_lens = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_set_epilogue_status = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_set_user_prompt = `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). \`dry_run:true\` returns the call shape without contacting the backend.
+
+WHEN TO USE: low-level.
+
+WHEN NOT TO USE: from agent flow \u2014 use leadbay_refine_prompt, which polls for follow-up clarifications.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_update_lens = `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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_update_lens_filter = `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). \`dry_run:true\` returns the call shape without contacting the backend.
+
+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.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+
 // ../core/dist/tools/login.js
 var login = {
   name: "leadbay_login",
@@ -542,7 +980,7 @@ var login = {
     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",
+  description: leadbay_login,
   inputSchema: {
     type: "object",
     properties: {
@@ -593,7 +1031,7 @@ var listLenses = {
     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.",
+  description: leadbay_list_lenses,
   inputSchema: {
     type: "object",
     properties: {},
@@ -641,7 +1079,7 @@ var discoverLeads = {
     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.",
+  description: leadbay_discover_leads,
   inputSchema: {
     type: "object",
     properties: {
@@ -705,7 +1143,7 @@ var getLeadProfile = {
     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.",
+  description: leadbay_get_lead_profile,
   inputSchema: {
     type: "object",
     properties: {
@@ -837,7 +1275,7 @@ var getContacts = {
     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.",
+  description: leadbay_get_contacts,
   inputSchema: {
     type: "object",
     properties: {
@@ -897,7 +1335,7 @@ var getQuota = {
     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.",
+  description: leadbay_get_quota,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   outputSchema: {
     type: "object",
@@ -926,7 +1364,7 @@ var getTasteProfile = {
     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).",
+  description: leadbay_get_taste_profile,
   inputSchema: {
     type: "object",
     properties: {},
@@ -990,7 +1428,7 @@ var qualifyLead = {
     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.",
+  description: leadbay_qualify_lead,
   optional: true,
   inputSchema: {
     type: "object",
@@ -1027,7 +1465,7 @@ var enrichContacts = {
     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.",
+  description: leadbay_enrich_contacts,
   optional: true,
   inputSchema: {
     type: "object",
@@ -1101,7 +1539,7 @@ var addNote = {
     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.",
+  description: leadbay_add_note,
   optional: true,
   inputSchema: {
     type: "object",
@@ -1151,7 +1589,7 @@ var getLeadActivities = {
     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.",
+  description: leadbay_get_lead_activities,
   inputSchema: {
     type: "object",
     properties: {
@@ -1211,7 +1649,7 @@ var getLensFilter = {
     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.",
+  description: leadbay_get_lens_filter,
   inputSchema: {
     type: "object",
     properties: {
@@ -1235,7 +1673,7 @@ var getLensScoring = {
     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.",
+  description: leadbay_get_lens_scoring,
   inputSchema: {
     type: "object",
     properties: { lensId: { type: "number", description: "Lens id (required)" } },
@@ -1257,7 +1695,7 @@ var listSectors = {
     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.",
+  description: leadbay_list_sectors,
   inputSchema: {
     type: "object",
     properties: {
@@ -1295,7 +1733,7 @@ var getUserPrompt = {
     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.",
+  description: leadbay_get_user_prompt,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   outputSchema: {
     type: "object",
@@ -1335,7 +1773,7 @@ var getClarification = {
     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.",
+  description: leadbay_get_clarification,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   outputSchema: {
     type: "object",
@@ -1377,7 +1815,7 @@ var getLeadNotes = {
     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.",
+  description: leadbay_get_lead_notes,
   inputSchema: {
     type: "object",
     properties: { leadId: { type: "string", description: "Lead UUID (required)" } },
@@ -1399,7 +1837,7 @@ var getEpilogueResponses = {
     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.",
+  description: leadbay_get_epilogue_responses,
   inputSchema: {
     type: "object",
     properties: {
@@ -1427,7 +1865,7 @@ var getProspectingActions = {
     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.",
+  description: leadbay_get_prospecting_actions,
   inputSchema: {
     type: "object",
     properties: {
@@ -1455,7 +1893,7 @@ var getWebFetch = {
     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.",
+  description: leadbay_get_web_fetch,
   inputSchema: {
     type: "object",
     properties: { leadId: { type: "string", description: "Lead UUID (required)" } },
@@ -1498,7 +1936,7 @@ var getSelectionIds = {
     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).",
+  description: leadbay_get_selection_ids,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     return await client.request("GET", "/leads/selection/ids");
@@ -1515,7 +1953,7 @@ var getEnrichmentJobTitles = {
     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.",
+  description: leadbay_get_enrichment_job_titles,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   execute: async (client) => {
     return await client.request("GET", "/leads/selection/enrichment/job_titles");
@@ -1883,6 +2321,13 @@ var STABILIZATION_POLLS = 2;
 var MAX_COLUMN_NAME_LEN = 128;
 var RESERVED_COLUMN_RE = /^mcp_row_id$/i;
 var CUSTOM_FIELD_RE = /^CUSTOM\.(\d+)$/;
+var IMPORT_RESOLVER_FIELDS = /* @__PURE__ */ new Set([
+  "LEADBAY_ID",
+  "CRM_ID",
+  "LEAD_NAME",
+  "LEAD_WEBSITE",
+  "SIREN"
+]);
 function isCustomFieldMappingValue(v) {
   return CUSTOM_FIELD_RE.test(v);
 }
@@ -2125,8 +2570,8 @@ function prepareRecordsMode(client, records, mappings, customFieldCatalog) {
     throw client.makeError("IMPORT_MAPPING_REQUIRED", "mappings.fields must contain at least one column \u2192 CRM field entry", "Map at least one CSV column to LEAD_NAME or LEAD_WEBSITE.", "POST /imports");
   }
   const targets = new Set(fieldEntries.map(([, v]) => v));
-  if (!targets.has("LEAD_NAME") && !targets.has("LEAD_WEBSITE")) {
-    throw client.makeError("IMPORT_MAPPING_NO_RESOLVER", "mappings.fields must include LEAD_NAME or LEAD_WEBSITE", "The wizard needs at least one of those fields to match a lead. Map a CSV column to one of them.", "POST /imports");
+  if (![...targets].some((t) => IMPORT_RESOLVER_FIELDS.has(t))) {
+    throw client.makeError("IMPORT_MAPPING_NO_RESOLVER", "mappings.fields must include LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE", "The wizard needs at least one identity field to match a lead. Use leadbay_resolve_import_rows to prepare LEADBAY_ID values when the input file is messy.", "POST /imports");
   }
   const targetCounts = /* @__PURE__ */ new Map();
   for (const [col, target] of fieldEntries) {
@@ -2538,7 +2983,7 @@ var importLeads = {
     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. For MCP clients with short transport timeouts, pass `wait_for_completion:false` to return quickly with `{status:'running', handle_id}`; poll `leadbay_import_status` with that handle for progress and the final `{leads, not_imported, importIds}` result.\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.",
+  description: leadbay_import_leads,
   write: true,
   version: "0.3.0",
   inputSchema: {
@@ -2576,7 +3021,7 @@ var importLeads = {
         properties: {
           fields: {
             type: "object",
-            description: "Object whose keys are CSV column names (matching keys in `records`) and whose values are either Leadbay's StandardCrmFieldType (LEAD_NAME, LEAD_WEBSITE, LEAD_STATUS, LEAD_LOCATION, LEAD_LOCATION_*, LEAD_SECTOR, LEAD_SIZE, CRM_ID, LEADBAY_ID, EMAIL, DEAL_CRM_ID, CONTACT_FIRST_NAME, CONTACT_LAST_NAME, CONTACT_EMAIL, CONTACT_PHONE_NUMBER, CONTACT_TITLE, CONTACT_LINKEDIN, LEAD_STATUS_DATE, OWNER, SCORE, SIREN) or the wire-format string 'CUSTOM.<id>' for org-defined custom fields. At least one entry must target LEAD_NAME or LEAD_WEBSITE \u2014 the wizard needs that to find leads. Use leadbay_list_mappable_fields to discover the org's custom fields."
+            description: "Object whose keys are CSV column names (matching keys in `records`) and whose values are either Leadbay's StandardCrmFieldType (LEAD_NAME, LEAD_WEBSITE, LEAD_STATUS, LEAD_LOCATION, LEAD_LOCATION_*, LEAD_SECTOR, LEAD_SIZE, CRM_ID, LEADBAY_ID, EMAIL, DEAL_CRM_ID, CONTACT_FIRST_NAME, CONTACT_LAST_NAME, CONTACT_EMAIL, CONTACT_PHONE_NUMBER, CONTACT_TITLE, CONTACT_LINKEDIN, LEAD_STATUS_DATE, OWNER, SCORE, SIREN) or the wire-format string 'CUSTOM.<id>' for org-defined custom fields. At least one entry must target LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE \u2014 the wizard needs an identity field to find leads. Use leadbay_resolve_import_rows to prepare LEADBAY_ID values, and leadbay_list_mappable_fields to discover the org's custom fields. Contact rows should include both parent lead identity fields and CONTACT_* fields; repeated LEADBAY_ID/company values create multiple contacts on the same lead. Preserve HubSpot/source links by mapping them to a CUSTOM.<id> field returned by leadbay_create_custom_field when no suitable custom field already exists."
           },
           custom_fields: {
             type: "object",
@@ -2851,7 +3296,7 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
 var STANDARD_FIELDS = [
   { name: "LEAD_NAME", description: "Company name. Required for fuzzy match." },
   { name: "LEAD_WEBSITE", description: "Company domain (preferred matcher; protocol/path auto-stripped)." },
-  { name: "EMAIL", description: "Email \u2014 domain part used as a website-fallback matcher." },
+  { name: "EMAIL", description: "Lead/company email \u2014 domain part may be used as a website-fallback matcher. For a person's email, use CONTACT_EMAIL and optionally derive a separate business-domain column for LEAD_WEBSITE." },
   { name: "CRM_ID", description: "Your CRM's stable lead identifier (round-trips back as crm_id on the lead)." },
   { name: "LEADBAY_ID", description: "Leadbay UUID, if you already have one (matches by id, no fuzzy needed)." },
   { name: "DEAL_CRM_ID", description: "Your CRM's deal id (one deal per row; combined with LEAD_STATUS forms a sales record)." },
@@ -2869,7 +3314,7 @@ var STANDARD_FIELDS = [
   { name: "SIREN", description: "French SIREN registry number (9 digits) \u2014 auto-matches against the FR registry." },
   { name: "CONTACT_FIRST_NAME", description: "Contact first name (creates an org contact)." },
   { name: "CONTACT_LAST_NAME", description: "Contact last name." },
-  { name: "CONTACT_EMAIL", description: "Contact email." },
+  { name: "CONTACT_EMAIL", description: "Contact email. Does not replace the parent company's LEAD_WEBSITE; derive a company domain from this only when it is a business domain, not a personal mailbox provider." },
   { name: "CONTACT_PHONE_NUMBER", description: "Contact phone (free-form)." },
   { name: "CONTACT_TITLE", description: "Contact job title." },
   { name: "CONTACT_LINKEDIN", description: "Contact LinkedIn URL." }
@@ -2887,7 +3332,7 @@ function describeCustomField(f) {
     case "DATETIME":
       return `Custom DATETIME field${f.config?.format ? ` (format: ${f.config.format})` : " (ISO datetime)"}.`;
     case "EXTERNAL_ID":
-      return `Custom EXTERNAL_ID field \u2014 opaque id${f.config?.urlTemplate ? ` (deep-link template configured)` : ""}.`;
+      return `Custom EXTERNAL_ID field \u2014 opaque id${f.config?.url_template || f.config?.urlTemplate ? ` (deep-link template configured)` : ""}.`;
     default:
       return `Custom field of unrecognized type "${f.type}" \u2014 pass values as strings.`;
   }
@@ -2903,7 +3348,7 @@ var listMappableFields = {
     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.",
+  description: leadbay_list_mappable_fields,
   inputSchema: {
     type: "object",
     properties: {
@@ -2981,7 +3426,10 @@ var listMappableFields = {
       }
     };
     if (Array.isArray(params.for_records) && params.for_records.length > 0) {
-      const notes = [];
+      const notes = [
+        "mapping_hints are backend suggestions, not final truth. Inspect values semantically before importing; person columns like first_name/last_name should map to CONTACT_* fields, not LEAD_NAME.",
+        "If mapping_hints disagree with the user's file semantics, ignore the hint. Use leadbay_resolve_import_rows with explicit identity_mappings for identity matching, then author final mappings yourself."
+      ];
       try {
         const sample = params.for_records.slice(0, PREVIEW_SAMPLE_CAP);
         const headerSet = /* @__PURE__ */ new Set();
@@ -3065,7 +3513,7 @@ var selectLeads = {
     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.",
+  description: leadbay_select_leads,
   optional: true,
   write: true,
   inputSchema: {
@@ -3109,7 +3557,7 @@ var deselectLeads = {
     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.",
+  description: leadbay_deselect_leads,
   optional: true,
   write: true,
   inputSchema: {
@@ -3142,7 +3590,7 @@ var clearSelection = {
     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.",
+  description: leadbay_clear_selection,
   optional: true,
   write: true,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
@@ -3162,7 +3610,7 @@ var setActiveLens = {
     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.",
+  description: leadbay_set_active_lens,
   optional: true,
   write: true,
   inputSchema: {
@@ -3189,7 +3637,7 @@ var createLens = {
     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.",
+  description: leadbay_create_lens,
   optional: true,
   write: true,
   inputSchema: {
@@ -3236,7 +3684,7 @@ var updateLens = {
     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.",
+  description: leadbay_update_lens,
   optional: true,
   write: true,
   inputSchema: {
@@ -3269,7 +3717,7 @@ var updateLensFilter = {
     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.",
+  description: leadbay_update_lens_filter,
   optional: true,
   write: true,
   inputSchema: {
@@ -3315,7 +3763,7 @@ var createLensDraft = {
     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.",
+  description: leadbay_create_lens_draft,
   optional: true,
   write: true,
   inputSchema: {
@@ -3339,7 +3787,7 @@ var promoteLens = {
     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).",
+  description: leadbay_promote_lens,
   optional: true,
   write: true,
   inputSchema: {
@@ -3365,7 +3813,7 @@ var setUserPrompt = {
     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.",
+  description: leadbay_set_user_prompt,
   optional: true,
   write: true,
   inputSchema: {
@@ -3410,7 +3858,7 @@ var clearUserPrompt = {
     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.",
+  description: leadbay_clear_user_prompt,
   optional: true,
   write: true,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
@@ -3432,7 +3880,7 @@ var pickClarification = {
     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.",
+  description: leadbay_pick_clarification,
   optional: true,
   write: true,
   inputSchema: {
@@ -3479,7 +3927,7 @@ var dismissClarification = {
     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.",
+  description: leadbay_dismiss_clarification,
   optional: true,
   write: true,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
@@ -3512,7 +3960,7 @@ var setEpilogueStatus = {
     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.",
+  description: leadbay_set_epilogue_status,
   optional: true,
   write: true,
   inputSchema: {
@@ -3559,7 +4007,7 @@ var removeEpilogue = {
     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).",
+  description: leadbay_remove_epilogue,
   optional: true,
   write: true,
   inputSchema: {
@@ -3592,7 +4040,7 @@ var previewBulkEnrichment = {
     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.",
+  description: leadbay_preview_bulk_enrichment,
   optional: true,
   write: true,
   inputSchema: {
@@ -3622,7 +4070,7 @@ var launchBulkEnrichment = {
     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.",
+  description: leadbay_launch_bulk_enrichment,
   optional: true,
   write: true,
   inputSchema: {
@@ -3675,6 +4123,98 @@ var launchBulkEnrichment = {
   }
 };
 
+// ../core/dist/tools/create-custom-field.js
+var createCustomField = {
+  name: "leadbay_create_custom_field",
+  annotations: {
+    title: "Create CRM custom field",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_create_custom_field,
+  write: true,
+  version: "0.6.4",
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "User-visible custom field name, e.g. 'HubSpot Contact'."
+      },
+      type: {
+        type: "string",
+        description: "Custom field type: TEXT, NUMBER, PRICE, DATE, DATETIME, or EXTERNAL_ID. Defaults to TEXT."
+      },
+      config: {
+        type: ["object", "null"],
+        description: "Type-specific config. EXTERNAL_ID requires {url_template:'https://.../{value}'}; PRICE requires {currency:'USD'}; DATE/DATETIME may set {format}."
+      },
+      if_not_exists: {
+        type: "boolean",
+        description: "Default true. If a custom field with the same name already exists, return it instead of creating a duplicate."
+      }
+    },
+    required: ["name"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      name: { type: "string" },
+      type: { type: "string" },
+      config: { type: ["object", "null"] },
+      mapping_value: {
+        type: "string",
+        description: "Wire mapping value to use in import mappings, e.g. CUSTOM.123."
+      },
+      existed: {
+        type: "boolean",
+        description: "True when if_not_exists reused an existing custom field."
+      }
+    },
+    required: ["id", "name", "type", "mapping_value", "existed"]
+  },
+  execute: async (client, params) => {
+    const name = params.name?.trim();
+    if (!name) {
+      throw client.makeError("CUSTOM_FIELD_NAME_REQUIRED", "name must be a non-empty string", "Pass a user-visible custom field name, e.g. 'HubSpot Contact'.", "POST /crm/custom_fields");
+    }
+    const type = params.type ?? "TEXT";
+    const config = params.config ?? null;
+    if (type === "EXTERNAL_ID") {
+      const urlTemplate = config?.url_template ?? config?.urlTemplate;
+      if (!urlTemplate || !urlTemplate.includes("{value}")) {
+        throw client.makeError("CUSTOM_FIELD_EXTERNAL_ID_TEMPLATE_REQUIRED", "EXTERNAL_ID custom fields require config.url_template containing {value}", "Use a URL template like https://app.hubspot.com/contacts/<portal-id>/record/0-1/{value}.", "POST /crm/custom_fields");
+      }
+    }
+    if (params.if_not_exists ?? true) {
+      const existing = await client.request("GET", "/crm/custom_fields");
+      const found = (existing ?? []).find((f) => f.name.toLowerCase() === name.toLowerCase());
+      if (found) {
+        return {
+          ...found,
+          mapping_value: `CUSTOM.${found.id}`,
+          existed: true
+        };
+      }
+    }
+    const body = {
+      name,
+      type,
+      ...config ? { config } : {}
+    };
+    const created = await client.request("POST", "/crm/custom_fields", body);
+    return {
+      ...created,
+      mapping_value: `CUSTOM.${created.id}`,
+      existed: false
+    };
+  }
+};
+
 // ../core/dist/composite/research-company.js
 var researchCompany = {
   name: "leadbay_research_company",
@@ -3685,7 +4225,7 @@ var researchCompany = {
     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).",
+  description: leadbay_research_company,
   inputSchema: {
     type: "object",
     properties: {
@@ -3769,7 +4309,7 @@ var prepareOutreach = {
     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).",
+  description: leadbay_prepare_outreach,
   optional: true,
   inputSchema: {
     type: "object",
@@ -3884,7 +4424,7 @@ var pullLeads = {
     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).",
+  description: leadbay_pull_leads,
   inputSchema: {
     type: "object",
     properties: {
@@ -4142,7 +4682,7 @@ var researchLead = {
     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.)",
+  description: leadbay_research_lead,
   inputSchema: {
     type: "object",
     properties: {
@@ -4427,7 +4967,7 @@ var recallOrderedTitles = {
     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.",
+  description: leadbay_recall_ordered_titles,
   inputSchema: {
     type: "object",
     properties: {
@@ -4548,7 +5088,7 @@ var accountStatus = {
     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.",
+  description: leadbay_account_status,
   inputSchema: { type: "object", properties: {}, additionalProperties: false },
   outputSchema: {
     type: "object",
@@ -4645,7 +5185,7 @@ var bulkQualifyLeads = {
     idempotentHint: true,
     openWorldHint: true
   },
-  description: "Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch). Pass `wait_for_completion:false` to return quickly with `{status:'running', qualify_id}`; poll leadbay_qualify_status with that id. With wait_for_completion omitted/true, the legacy behavior polls 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).",
+  description: leadbay_bulk_qualify_leads,
   inputSchema: {
     type: "object",
     properties: {
@@ -4946,6 +5486,324 @@ var bulkQualifyLeads = {
   }
 };
 
+// ../core/dist/composite/resolve-import-rows.js
+var SOCIAL_FIELDS = /* @__PURE__ */ new Set(["linkedin", "facebook", "instagram", "twitter", "tiktok"]);
+var RESOLVER_TARGETS = /* @__PURE__ */ new Set(["LEADBAY_ID", "CRM_ID", "LEAD_NAME", "LEAD_WEBSITE", "SIREN"]);
+var DEFAULT_CANDIDATE_PROFILE_LIMIT = 5;
+function coerceCell2(v) {
+  if (v == null)
+    return "";
+  if (typeof v === "string")
+    return v;
+  if (typeof v === "number" || typeof v === "boolean")
+    return String(v);
+  return JSON.stringify(v) ?? "";
+}
+function compactMappings(mappings) {
+  const out = {};
+  for (const [k, v] of Object.entries(mappings)) {
+    if (v)
+      out[k] = v;
+  }
+  return out;
+}
+function payloadForRecord(row, mappings) {
+  const payload = {};
+  const socials = {};
+  for (const [field, column] of Object.entries(mappings)) {
+    const value = (row[column] ?? "").trim();
+    if (!value)
+      continue;
+    if (SOCIAL_FIELDS.has(field)) {
+      socials[field] = value;
+    } else {
+      payload[field] = value;
+    }
+  }
+  if (Object.keys(socials).length > 0)
+    payload.socials = socials;
+  return payload;
+}
+function identityMappingsForImport(records, identityMappings) {
+  const fields = {};
+  if (records.some((r) => (r.LEADBAY_ID ?? "").trim() !== "")) {
+    fields.LEADBAY_ID = "LEADBAY_ID";
+  }
+  const add = (field, target) => {
+    const column = identityMappings[field];
+    if (!column || fields[column])
+      return;
+    if (!records.some((r) => (r[column] ?? "").trim() !== ""))
+      return;
+    fields[column] = target;
+  };
+  add("leadbay_id", "LEADBAY_ID");
+  add("crm_id", "CRM_ID");
+  add("registry_number", "SIREN");
+  add("name", "LEAD_NAME");
+  add("website", "LEAD_WEBSITE");
+  return { fields, statuses: {}, default_status: null };
+}
+function disambiguationPolicy() {
+  return [
+    "Use `matched` lead_id values directly; the tool already writes those into LEADBAY_ID.",
+    "For `ambiguous` rows, do not choose a candidate from score alone. Score is a tied evidence-band, not a confidence percentage.",
+    "For every ambiguous row you resolve, keep a short decision note: selected candidate id, evidence used, conflicting evidence checked, or why LEADBAY_ID stayed blank. Report counts and examples to the user.",
+    "Try to disambiguate relentlessly before giving up: rerun the row with include_candidate_profiles=true and a larger candidate_profile_limit if candidate facts are truncated, and include every trustworthy source signal available (website, full address, postcode, city, phone, registry/CRM id, source URL path, neighborhood/location words).",
+    "Compare addresses intelligently as a human would. Recognize ordinary formatting, abbreviation, spelling, punctuation, casing, accent, direction, ordinal, and suite/unit differences without treating address comparison as a rigid rule checklist. A clear same-place street address match is strong evidence.",
+    "Auto-select an ambiguous candidate when hydrated candidate facts uniquely agree with the source row on strong evidence: exact registry number, exact CRM ID, exact canonical website/domain with only one candidate, exact phone, or name plus clear same-place address match with postcode/city and no conflicting evidence.",
+    "If several candidates share the same website/domain, do not fail fast. Treat it as a chain/multi-location problem: use source street address, postcode, city/neighborhood, phone, source URL path/location slug, and location words in the source name to pick the specific location when exactly one candidate matches.",
+    "Postcode/city alone is not enough, and brand/root-domain alone is not enough for multi-location sources. If several candidates remain plausible after checking location/phone/path evidence, leave LEADBAY_ID blank.",
+    "A domain derived from a contact email is useful only when it is a business domain (not gmail/hotmail/outlook/yahoo/icloud/proton/aol/etc.) and the company/contact context agrees with the candidate. If the domain looks like a POS/vendor/agency/group domain or conflicts with row notes, do not use it for LEADBAY_ID selection.",
+    "If evidence is name-only, fuzzy-name-only, generic directory website, or multiple candidates remain plausible after exhausting location/phone/path evidence, leave LEADBAY_ID blank and import with website/name so Leadbay can crawl or late-match later.",
+    "When the user asked for qualification after import, qualify only the lead IDs that the import returns. Late website matches may appear later via leadbay_import_status."
+  ];
+}
+function mappingGuidance() {
+  return [
+    "Treat mappings_for_import as a safe identity starting point, not a complete CRM mapping.",
+    "Before importing, inspect every user column and sample values, then make a preservation plan: standard field, CONTACT_* field, Leadbay note, custom field, derived helper, or skip with a reason. The model, not this helper, should decide the complete mapping.",
+    "Default to preserving client-provided business data. For meaningful columns with no standard Leadbay field, call leadbay_list_mappable_fields and create/reuse custom fields instead of silently dropping them. Skip only blank placeholders, duplicate plumbing, raw unparsed blobs after useful values are extracted, or values that would actively harm data quality.",
+    "Always include LEADBAY_ID when records_for_import contains it; it makes deterministic matches import immediately.",
+    "Also map the best available source identity columns: website/domain/url -> LEAD_WEBSITE, company/account/restaurant name -> LEAD_NAME, CRM/system id -> CRM_ID, registry/SIREN/SIRET/company number -> SIREN.",
+    "For contact-only or HubSpot contact exports, derive a separate company_domain/company_website column from CONTACT_EMAIL only when the email domain is a real business domain and agrees with the company/deal/brand context. Do not use POS/vendor/group domains that conflict with the row, and do not derive company identity from private mailbox domains such as gmail.com, hotmail.com, outlook.com, yahoo.com, icloud.com, proton.me/protonmail.com, aol.com, or similar consumer email providers.",
+    "Map contact-person columns when the file contains people: first_name -> CONTACT_FIRST_NAME, last_name -> CONTACT_LAST_NAME, job_title/title -> CONTACT_TITLE, contact email -> CONTACT_EMAIL, contact phone -> CONTACT_PHONE_NUMBER, contact LinkedIn -> CONTACT_LINKEDIN. If a company/restaurant row contains structured owners, decision makers, or contact lists, expand those people into additional import rows that repeat the parent lead identity and contain one CONTACT_* person per row. Multiple rows may point to the same LEADBAY_ID/company; import them as separate contacts on that lead.",
+    "Preserve valuable source-system links. For HubSpot URLs, prefer extracting the stable object id into a clean column and mapping it to an existing or newly created EXTERNAL_ID custom field. Reuse an existing HubSpot linked-id field when present. Preserve raw source identifiers such as hubspot_id and associated_deal in custom fields when they are not already represented by a better standard/custom field. Use TEXT only when no stable id/template can be recovered.",
+    "Clean source-system deal names before using them as LEAD_NAME: strip import campaign suffixes such as BYOC, BYOC only, DD, Uber, trailing separators, and duplicate pipeline labels, while preserving the original associated deal/source value in a custom field when it is meaningful to the user's workflow.",
+    "Drop blank-header columns and placeholder values like `couldn't find`, `yes`, empty arrays, and raw JSON blobs unless you first extract meaningful scalar fields.",
+    "Leadbay has CONTACT_PHONE_NUMBER but no standard LEAD_PHONE field in this surface. Preserve establishment/company phone only via an intentional custom field, not by pretending it is a contact phone.",
+    "Preserve meaningful client notes, data-quality warnings that affect outreach, source record links, and owner/evidence URLs when they help the user's workflow. Do not map noisy scraper plumbing, duplicate blank columns, placeholder values, or long reasoning text.",
+    "If the file contains meaningful per-lead notes/context, keep that text aside during import and add it to the imported/resolved leads with leadbay_add_note after import when that tool is available. For dry runs, report which notes would be written. If notes cannot be written and the user asked to preserve the text, create/reuse an import-notes custom field.",
+    "For scraped owner/email JSON columns, extract the best scalar values into new clean columns before import; do not pass raw JSON blobs as core CRM fields.",
+    "If no confident standard/custom mapping exists for a meaningful user column, create or reuse a custom field unless the column is blank/noisy/duplicate and record why it was skipped."
+  ];
+}
+async function hydrateCandidateProfiles(client, candidates, lensId, limit) {
+  const selected = candidates.slice(0, Math.max(0, limit));
+  const settled = await Promise.allSettled(selected.map((c) => client.request("GET", `/lenses/${lensId}/leads/${c.lead_id}`)));
+  const out = [];
+  settled.forEach((r, i) => {
+    if (r.status !== "fulfilled")
+      return;
+    const lead = r.value;
+    out.push({
+      lead_id: selected[i].lead_id,
+      name: lead.name ?? null,
+      website: lead.website ?? null,
+      location: lead.location ? {
+        full: lead.location.full ?? null,
+        city: lead.location.city ?? null,
+        state: lead.location.state ?? null,
+        country: lead.location.country ?? null
+      } : null,
+      phone_numbers: Array.isArray(lead.phone_numbers) ? lead.phone_numbers : [],
+      description: typeof lead.description === "string" ? lead.description.slice(0, 400) : null
+    });
+  });
+  return out;
+}
+function hasResolverTarget(mappings) {
+  return Object.values(mappings.fields).some((v) => RESOLVER_TARGETS.has(v));
+}
+var resolveImportRows = {
+  name: "leadbay_resolve_import_rows",
+  annotations: {
+    title: "Resolve import row identities",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_resolve_import_rows,
+  write: false,
+  version: "0.6.4",
+  inputSchema: {
+    type: "object",
+    properties: {
+      records: {
+        type: "array",
+        description: "CSV-shaped rows from the user file. Values may be strings, numbers, booleans, null, arrays, or objects; non-scalars are JSON-stringified for resolver/import preparation.",
+        items: { type: "object" }
+      },
+      identity_mappings: {
+        type: "object",
+        description: "Resolver field -> source column map chosen by the agent after inspecting the file, e.g. {website:'company_domain', name:'Company', crm_id:'Salesforce ID', registry_number:'SIREN'}. May point to clean columns the agent derived before calling this tool. This tool does not infer mappings from header names.",
+        properties: {
+          leadbay_id: { type: "string" },
+          crm_id: { type: "string" },
+          name: { type: "string" },
+          website: { type: "string" },
+          phone: { type: "string" },
+          email: { type: "string" },
+          registry_number: { type: "string" },
+          registry_type: { type: "string" },
+          address: { type: "string" },
+          city: { type: "string" },
+          postcode: { type: "string" },
+          country: { type: "string" },
+          linkedin: { type: "string" },
+          facebook: { type: "string" },
+          instagram: { type: "string" },
+          twitter: { type: "string" },
+          tiktok: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      include_candidate_profiles: {
+        type: "boolean",
+        description: "When true, hydrate ambiguous candidate IDs with lightweight lead facts from the active lens. Use on small batches or rerun on only ambiguous rows; large ambiguous files can return many candidates."
+      },
+      candidate_profile_limit: {
+        type: "number",
+        description: `Maximum candidates to hydrate per ambiguous row when include_candidate_profiles=true (default ${DEFAULT_CANDIDATE_PROFILE_LIMIT}).`
+      },
+      lensId: {
+        type: "number",
+        description: "Lens ID used for candidate profile hydration. Defaults to the user's active lens."
+      }
+    },
+    required: ["records"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      rows: {
+        type: "array",
+        description: "Per-input resolution result. Matched rows include lead_id; ambiguous rows include candidates; none/unidentifiable rows explain what extra signal would help.",
+        items: { type: "object" }
+      },
+      records_for_import: {
+        type: "array",
+        description: "Import-ready records. Matched rows include LEADBAY_ID. Ambiguous/unresolved rows preserve user data and rely on website/name/CRM fields for normal or late matching.",
+        items: { type: "object" }
+      },
+      mappings_for_import: {
+        type: "object",
+        description: "Safe identity-only mapping starter. The agent should review/extend this using mapping_guidance and leadbay_list_mappable_fields before importing."
+      },
+      identity_mappings_used: { type: "object" },
+      mapping_guidance: {
+        type: "array",
+        description: "Instructions for building the final import mappings from the source columns.",
+        items: { type: "string" }
+      },
+      disambiguation_policy: {
+        type: "array",
+        description: "Rules the agent should follow before writing LEADBAY_ID onto ambiguous rows.",
+        items: { type: "string" }
+      },
+      summary: { type: "object" },
+      next_action: { type: "string" },
+      region: { type: "string" },
+      _meta: { type: "object" }
+    },
+    required: [
+      "rows",
+      "records_for_import",
+      "mappings_for_import",
+      "identity_mappings_used",
+      "mapping_guidance",
+      "disambiguation_policy",
+      "summary",
+      "next_action",
+      "region",
+      "_meta"
+    ]
+  },
+  execute: async (client, params) => {
+    if (!Array.isArray(params.records) || params.records.length === 0) {
+      throw client.makeError("RESOLVE_IMPORT_EMPTY_INPUT", "records[] must contain at least one row", "Pass the rows from the user file, then import records_for_import.", "POST /leads/resolve");
+    }
+    const rows = params.records.map((rec, i) => {
+      if (rec == null || typeof rec !== "object" || Array.isArray(rec)) {
+        throw client.makeError("RESOLVE_IMPORT_INVALID_ROW", `records[${i}] must be a plain object`, "Pass each input row as { ColumnName: value, ... }.", "POST /leads/resolve");
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(rec))
+        out[k] = coerceCell2(v);
+      return out;
+    });
+    const identityMappings = compactMappings(params.identity_mappings ?? {});
+    const allColumns = new Set(rows.flatMap((r) => Object.keys(r)));
+    for (const [field, column] of Object.entries(identityMappings)) {
+      if (!allColumns.has(column)) {
+        throw client.makeError("RESOLVE_IMPORT_MAPPING_KEY_UNKNOWN", `identity_mappings.${field} points to missing column ${JSON.stringify(column)}`, "Use a source column that exists in at least one input record.", "POST /leads/resolve");
+      }
+    }
+    const outputs = [];
+    const recordsForImport = [];
+    const results = await Promise.all(rows.map(async (row) => {
+      const payload = payloadForRecord(row, identityMappings);
+      const result = await client.request("POST", "/leads/resolve", payload);
+      return { payload, result };
+    }));
+    let matched = 0;
+    let ambiguous = 0;
+    let none = 0;
+    let unidentifiable = 0;
+    const hydrateProfiles = params.include_candidate_profiles === true;
+    const candidateProfileLimit = params.candidate_profile_limit ?? DEFAULT_CANDIDATE_PROFILE_LIMIT;
+    const hydrationLensId = hydrateProfiles ? params.lensId ?? await client.resolveDefaultLens() : null;
+    for (let index = 0; index < results.length; index++) {
+      const { payload, result } = results[index];
+      const importRecord = { ...rows[index] };
+      const rowOut = {
+        index,
+        type: result.type,
+        resolver_payload: payload,
+        import_record: importRecord
+      };
+      if (result.type === "matched") {
+        matched++;
+        importRecord.LEADBAY_ID = result.lead_id;
+        rowOut.lead_id = result.lead_id;
+        rowOut.matched_on = result.matched_on;
+      } else if (result.type === "ambiguous") {
+        ambiguous++;
+        rowOut.candidates = result.candidates;
+        if (hydrateProfiles && hydrationLensId !== null) {
+          rowOut.candidate_profiles = await hydrateCandidateProfiles(client, result.candidates, hydrationLensId, candidateProfileLimit);
+        }
+      } else if (result.type === "none") {
+        none++;
+        rowOut.would_help = result.would_help;
+      } else {
+        unidentifiable++;
+        rowOut.reason = result.reason;
+      }
+      recordsForImport.push(importRecord);
+      outputs.push(rowOut);
+    }
+    const mappingsForImport = identityMappingsForImport(recordsForImport, identityMappings);
+    const readyForImport = hasResolverTarget(mappingsForImport);
+    return {
+      rows: outputs,
+      records_for_import: recordsForImport,
+      mappings_for_import: mappingsForImport,
+      identity_mappings_used: identityMappings,
+      mapping_guidance: mappingGuidance(),
+      disambiguation_policy: disambiguationPolicy(),
+      summary: {
+        total: rows.length,
+        matched,
+        ambiguous,
+        none,
+        unidentifiable,
+        ready_for_import: readyForImport
+      },
+      next_action: readyForImport ? "Review ambiguous candidates using disambiguation_policy. Build the final mapping from mappings_for_import plus mapping_guidance, then call leadbay_import_leads or leadbay_import_and_qualify with records_for_import and the reviewed mapping." : "Add or map at least one import resolver column (LEADBAY_ID, CRM_ID, LEAD_NAME, LEAD_WEBSITE, or SIREN), then call leadbay_import_leads.",
+      region: client.region,
+      _meta: client.lastMeta ?? {
+        region: client.region,
+        endpoint: "POST /leads/resolve",
+        latency_ms: null,
+        retry_after: null
+      }
+    };
+  }
+};
+
 // ../core/dist/composite/import-and-qualify.js
 function escapeCsv(v) {
   return escapeCsvCell(v);
@@ -5035,28 +5893,7 @@ var importAndQualify = {
     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. For MCP clients with short transport timeouts, pass \`wait_for_completion:false\`; the tool returns quickly with an import \`handle_id\` that can be polled with leadbay_import_status before continuing qualification. 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:
-  - \`domains\`: list of \`{domain, name?}\` (Mode A) \u2014 mutually exclusive with \`records\`.
-  - \`records\`: list of CSV-shaped objects (Mode B), accompanied by \`mappings\`. Use \`mappings.fields\` with     StandardCrmFieldType names or 'CUSTOM.<id>' wire values; or \`mappings.custom_fields\` with field id     or name shorthand. Discover the org's mappable surface via leadbay_list_mappable_fields.
-  - Budgets: \`total_budget_ms\` (default ${DEFAULT_TOTAL_BUDGET_MS3 / 6e4} min) caps the entire wall-clock;     \`per_lead_budget_ms\` (default ${DEFAULT_PER_LEAD_BUDGET_MS2 / 1e3}s) caps each lead's individual qualification poll.
-
-Outputs include \`qualified[]\` (per-lead question answers), \`still_running[]\` (lead ids whose qualification exceeded the budget), \`not_imported[]\` (rows the wizard couldn't match), and \`qualify_id\` (the resumable handle when at least one lead is still running). Idempotent within a 5-min window: re-calling with the same records+mapping returns the same qualify_id (\`reused: true\`). The result has a \`kind\` discriminator (\`'result' | 'preview'\`); preview-mode (\`dry_run: 'preview'\`) returns mapping hints + custom-field candidates instead of importing. Pass \`dry_run: true\` for input-validation only (top-level \`dry_run: true\` appears in the result so the agent can distinguish from all-malformed input).
-
-When to use: the agent has a list of companies (domains, or CSV-shaped rows from the user's CRM) and wants Leadbay's full AI qualification \u2014 qualification answers, web-research signals \u2014 without orchestrating import + bulk_qualify_leads + lead_profile chains by hand.
-When NOT to use: discovery (use leadbay_pull_leads); single-lead deep dive (use leadbay_research_lead); high-cadence or untrusted automation \u2014 this mutates user state by creating CRM-import rows and consumes ai_rescore + web_fetch quota.
-
-\u26A0\uFE0F MUTATES USER STATE. Each call:
-  - creates a CRM-imports row (visible in the web UI)
-  - touches onboarding state
-  - launches up to N\xD7ai_rescore + N\xD7web_fetch quota where N = imported lead count (unless \`skip_already_qualified: true\` (default) excludes already-scored leads)
-
-\u2139\uFE0F Monitor-tab membership: imported leads are NOT auto-promoted to the user's Monitor view. The lens-scoring rule decides \u2014 only leads that score above the lens threshold get \`in_monitor: true\` server-side. Lower-scoring imports stay invisible to the Monitor tab. Tell the user this if they ask 'where did my import go?' \u2014 answer is the CRM-imports list, not Monitor.
-
-\u2139\uFE0F In-lens-but-unscored leads: a lead may be admitted to the active lens (lens GET returns 200) but the lens-scoring job may not materialize for it (qualification never starts). The composite today surfaces hard-rejected leads (404 from lens GET) in \`not_in_lens[]\`, but in-lens-unscored leads currently sit in \`still_running[]\` \u2014 there's no per-lead 'scoring queued vs won't_compute' signal from the backend yet (tracked: leadbay/product#3571). If still_running stays non-empty for a lead more than 5 minutes after a successful import, suggest the user verify the lens covers that lead's profile (e.g., sector match) \u2014 qualify_status's poll won't ever produce answers.
-
-Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role; active billing.`,
+  description: leadbay_import_and_qualify,
   write: true,
   version: "0.2.0",
   inputSchema: {
@@ -5097,7 +5934,7 @@ Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role;
         properties: {
           fields: {
             type: "object",
-            description: "Object whose keys are CSV column names and whose values are either StandardCrmFieldType (LEAD_NAME, LEAD_WEBSITE, ..., CONTACT_TITLE) or 'CUSTOM.<id>'. Discover via leadbay_list_mappable_fields. At least one entry must target LEAD_NAME or LEAD_WEBSITE."
+            description: "Object whose keys are CSV column names and whose values are either StandardCrmFieldType (LEAD_NAME, LEAD_WEBSITE, ..., CONTACT_TITLE) or 'CUSTOM.<id>'. Discover via leadbay_list_mappable_fields. At least one entry must target LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE. Use leadbay_resolve_import_rows to prepare LEADBAY_ID values from messy user files. Contact exports and embedded owner/contact lists should map CONTACT_EMAIL/PHONE/TITLE/name fields while preserving parent lead identity; expand structured people into repeated parent rows. HubSpot/source links should map to CUSTOM.<id> fields created or discovered before import."
           },
           custom_fields: {
             type: "object",
@@ -6285,7 +7122,7 @@ var importStatus = {
     idempotentHint: true,
     openWorldHint: true
   },
-  description: "Retrieve the current state of an async lead import. Pass `handle_id` returned by leadbay_import_leads({wait_for_completion:false}), or pass legacy `importIds[]` to inspect backend wizard rows. This status call performs a single refresh pass and never polls in a loop.\nWhen to use: after leadbay_import_leads or leadbay_import_and_qualify returns `{status:'running', handle_id}` for the import phase, call this tool later to retrieve progress or the final import result without re-running the import.\nWhen NOT to use: for qualification handles returned as `qualify_id` \u2014 use leadbay_qualify_status for those; or when you still want the legacy blocking behavior from leadbay_import_leads with wait_for_completion=true.",
+  description: leadbay_import_status,
   inputSchema: {
     type: "object",
     properties: {
@@ -6443,7 +7280,7 @@ var qualifyStatus = {
     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.",
+  description: leadbay_qualify_status,
   inputSchema: {
     type: "object",
     properties: {
@@ -6631,7 +7468,7 @@ var enrichTitles = {
     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.",
+  description: leadbay_enrich_titles,
   inputSchema: {
     type: "object",
     properties: {
@@ -6992,7 +7829,7 @@ var bulkEnrichStatus = {
     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.",
+  description: leadbay_bulk_enrich_status,
   inputSchema: {
     type: "object",
     properties: {
@@ -7312,7 +8149,7 @@ var adjustAudience = {
     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.",
+  description: leadbay_adjust_audience,
   inputSchema: {
     type: "object",
     properties: {
@@ -7497,7 +8334,7 @@ var refinePrompt = {
     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.",
+  description: leadbay_refine_prompt,
   inputSchema: {
     type: "object",
     properties: {
@@ -7685,7 +8522,7 @@ var answerClarification = {
     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.",
+  description: leadbay_answer_clarification,
   inputSchema: {
     type: "object",
     properties: {
@@ -7776,7 +8613,7 @@ var reportOutreach = {
     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.",
+  description: leadbay_report_outreach,
   optional: true,
   write: true,
   inputSchema: {
@@ -8085,7 +8922,8 @@ var granularWriteTools = [
   setEpilogueStatus,
   removeEpilogue,
   previewBulkEnrichment,
-  launchBulkEnrichment
+  launchBulkEnrichment,
+  createCustomField
 ];
 var granularTools = [
   login,
@@ -8103,6 +8941,7 @@ var compositeReadTools = [
   bulkEnrichStatus,
   qualifyStatus,
   importStatus,
+  resolveImportRows,
   // listMappableFields is granular-shaped but the import composites depend on
   // it for discoverability; expose it always-on so agents can find custom fields
   // without needing LEADBAY_MCP_ADVANCED=1.
@@ -8119,7 +8958,13 @@ var compositeWriteTools = [
   answerClarification,
   reportOutreach,
   importLeads,
-  importAndQualify
+  importAndQualify,
+  // createCustomField is granular-shaped but file-import prompts depend on it
+  // to preserve source-system links without requiring advanced-tool exposure.
+  createCustomField,
+  // addNote is granular-shaped but file-import prompts depend on it to preserve
+  // meaningful source-file notes after imports return lead ids.
+  addNote
 ];
 var compositeTools = [
   ...compositeReadTools,
@@ -8176,6 +9021,7 @@ export {
   removeEpilogue,
   previewBulkEnrichment,
   launchBulkEnrichment,
+  createCustomField,
   researchCompany,
   prepareOutreach,
   pullLeads,
@@ -8183,6 +9029,7 @@ export {
   recallOrderedTitles,
   accountStatus,
   bulkQualifyLeads,
+  resolveImportRows,
   importAndQualify,
   isValidBulkId,
   LocalBulkStore,