@leadbay/mcp 0.7.1 → 0.9.0

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

@@ -571,6 +571,8 @@ WHEN NOT TO USE: as a substitute for leadbay_research_lead \u2014 that already i
 `;
 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.
 
+**Default to \`wait_for_completion:false\`** for any \`count > 5\` or when chained inside a multi-phase workflow \u2014 the blocking default can hit the MCP per-call timeout and surface as \`"Request timed out"\` even when the server is still working fine. The async pattern (capture \`qualify_id\`, poll \`leadbay_qualify_status\` every ~10s) is timeout-proof. Reserve the blocking form for tiny single-digit counts in interactive use.
+
 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\`.
@@ -578,6 +580,43 @@ WHEN TO USE: when the user wants more qualified leads than what's currently show
 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\`.
+
+
+---
+
+## Status / scalar \u2014 single-sentence shape
+
+The response is a status confirmation or scalar \u2014 render exactly one sentence inline. Do NOT emit a card or a table. Do NOT enumerate the affected records (that's the next tool's job).
+
+Template patterns to follow:
+
+- Job kicked off \u2192 \`"\u2713 <Verb> N <noun(s)> \u2014 typically ~M minutes. I'll refresh when it's done."\`
+- No work needed \u2192 \`"All N <noun(s)> already <state> \u2014 no work to do."\`
+- Long-running \u2192 \`"\u23F3 <Verb> still running \u2014 N% complete; check back in ~M minutes."\`
+- Failure \u2192 \`"\u26A0 <Verb> failed: <error>. <recovery hint>"\`
+
+After the status line, propose the obvious refresh / progress-check / recovery action in the NEXT STEPS block. Never expand the status into a card.
+
+
+Specifically for bulk qualify:
+
+- Kicked off async \u2192 \`"\u2713 Qualifying N lead(s) (qualify_id <id>) \u2014 typically ~M minutes. I'll refresh your leads view when it's done."\`
+- Blocking call returned with answers \u2192 \`"\u2713 Qualified N lead(s). Refresh your leads to see the new \u2756 caps."\`
+- Already-qualified short-circuit \u2192 \`"All N leads are already qualified \u2014 no work to do."\`
+- 429 mid-fanout \u2192 \`"\u26A0 Rate-limited after launching M of N \u2014 already-launched leads will complete; re-call later for the rest."\`
+
+Do not enumerate the affected leads \u2014 that's the job of \`leadbay_pull_leads\`.
+
+---
+
+## NEXT STEPS \u2014 after kicking off bulk qualification
+
+Exactly two offers \u2014 keep it terse, this is a status tool:
+
+| Observation                          | Suggest                                       | Calls                          |
+|--------------------------------------|-----------------------------------------------|--------------------------------|
+| Qualification kicked off (async)     | "Check progress in ~30s"                      | leadbay_qualify_status         |
+| Job is done / blocking call returned | "Refresh leads view \u2014 the new qualifications should be on the top"  | leadbay_pull_leads(lensId = pinned) |
 `;
 var leadbay_clear_selection = `Clear the user's transient selection.
 
@@ -759,6 +798,38 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 
 
 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.
+
+---
+
+## RENDERING \u2014 import result summary (single-record, terse)
+
+The response carries either a completed result or an async handle. Render a brief summary; do NOT enumerate every imported lead.
+
+**Header \u2014 single line, choose by status:**
+
+- Completed: \`"\u2713 Import complete \u2014 N leads imported \xB7 M failed \xB7 P resolved-with-ambiguity"\`
+- Running: \`"\u23F3 Import running \u2014 handle_id <id>; poll leadbay_import_status"\`
+- Pending qualification (\`leadbay_import_and_qualify\`): \`"\u2713 Imported N leads \xB7 qualifying M of them \u2014 qualify_id <id>"\`
+
+**When failures or ambiguous rows are non-empty**, follow the header with a small bulleted list (\u2264 5 items): \`<row identifier or domain> \xB7 <reason>\`. Then \`"*+N more \u2014 leadbay_import_status for full detail*"\`.
+
+**When the user's request implied a downstream use** ("import then prep outreach for them"), emit \`Imported leadIds: <up to 5 ids, then '+N more'>\` \u2014 just the ids. Let the next composite render the leads.
+
+Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead\` in NEXT STEPS.
+
+
+---
+
+## NEXT STEPS \u2014 after an import
+
+| Observation                                    | Suggest                                                       | Calls                                                  |
+|------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|
+| Status: running                                | "Check progress"                                              | leadbay_import_status(handle_id)                       |
+| Status: complete, imports succeeded            | "Run AI qualification on the imported leads"                  | leadbay_bulk_qualify_leads([leadIds]) \u2014 or use leadbay_import_and_qualify next time |
+| Ambiguous / unresolved rows present            | "Resolve the ambiguous rows"                                  | leadbay_resolve_import_rows(records, identity_mappings)|
+| Failed rows from bad mappings                  | "Check the org's mappable fields and remap"                   | leadbay_list_mappable_fields                           |
+| User wants to see the imported leads           | "See the imported leads in your view"                         | leadbay_pull_leads                                     |
+| User had follow-up intent for the imports      | "Prep outreach for [a specific imported lead]"                | leadbay_prepare_outreach(leadId)                       |
 `;
 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.
 
@@ -774,12 +845,76 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role on the Leadbay account; active billing.
+
+---
+
+## RENDERING \u2014 import result summary (single-record, terse)
+
+The response carries either a completed result or an async handle. Render a brief summary; do NOT enumerate every imported lead.
+
+**Header \u2014 single line, choose by status:**
+
+- Completed: \`"\u2713 Import complete \u2014 N leads imported \xB7 M failed \xB7 P resolved-with-ambiguity"\`
+- Running: \`"\u23F3 Import running \u2014 handle_id <id>; poll leadbay_import_status"\`
+- Pending qualification (\`leadbay_import_and_qualify\`): \`"\u2713 Imported N leads \xB7 qualifying M of them \u2014 qualify_id <id>"\`
+
+**When failures or ambiguous rows are non-empty**, follow the header with a small bulleted list (\u2264 5 items): \`<row identifier or domain> \xB7 <reason>\`. Then \`"*+N more \u2014 leadbay_import_status for full detail*"\`.
+
+**When the user's request implied a downstream use** ("import then prep outreach for them"), emit \`Imported leadIds: <up to 5 ids, then '+N more'>\` \u2014 just the ids. Let the next composite render the leads.
+
+Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead\` in NEXT STEPS.
+
+
+---
+
+## NEXT STEPS \u2014 after an import
+
+| Observation                                    | Suggest                                                       | Calls                                                  |
+|------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|
+| Status: running                                | "Check progress"                                              | leadbay_import_status(handle_id)                       |
+| Status: complete, imports succeeded            | "Run AI qualification on the imported leads"                  | leadbay_bulk_qualify_leads([leadIds]) \u2014 or use leadbay_import_and_qualify next time |
+| Ambiguous / unresolved rows present            | "Resolve the ambiguous rows"                                  | leadbay_resolve_import_rows(records, identity_mappings)|
+| Failed rows from bad mappings                  | "Check the org's mappable fields and remap"                   | leadbay_list_mappable_fields                           |
+| User wants to see the imported leads           | "See the imported leads in your view"                         | leadbay_pull_leads                                     |
+| User had follow-up intent for the imports      | "Prep outreach for [a specific imported lead]"                | leadbay_prepare_outreach(leadId)                       |
 `;
 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\`.
+
+---
+
+## Status / scalar \u2014 single-sentence shape
+
+The response is a status confirmation or scalar \u2014 render exactly one sentence inline. Do NOT emit a card or a table. Do NOT enumerate the affected records (that's the next tool's job).
+
+Template patterns to follow:
+
+- Job kicked off \u2192 \`"\u2713 <Verb> N <noun(s)> \u2014 typically ~M minutes. I'll refresh when it's done."\`
+- No work needed \u2192 \`"All N <noun(s)> already <state> \u2014 no work to do."\`
+- Long-running \u2192 \`"\u23F3 <Verb> still running \u2014 N% complete; check back in ~M minutes."\`
+- Failure \u2192 \`"\u26A0 <Verb> failed: <error>. <recovery hint>"\`
+
+After the status line, propose the obvious refresh / progress-check / recovery action in the NEXT STEPS block. Never expand the status into a card.
+
+
+Specifically for import status:
+
+- Running \u2192 \`"\u23F3 Import still running \u2014 N% complete; check back in ~M minutes."\`
+- Complete \u2192 \`"\u2713 Import complete \u2014 N leads imported, M failed."\`
+- Error / failed \u2192 \`"\u26A0 Import failed: <error>. See leadbay_resolve_import_rows for diagnosis."\`
+
+---
+
+## NEXT STEPS
+
+| Observation             | Suggest                                | Calls                          |
+|-------------------------|----------------------------------------|--------------------------------|
+| Status: complete        | "See the imported leads"               | leadbay_pull_leads             |
+| Status: running         | "Check again in N minutes"             | leadbay_import_status \u2014 re-call|
+| Status: error / failed  | "Diagnose the failure"                 | leadbay_resolve_import_rows    |
 `;
 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.
 
@@ -803,7 +938,35 @@ Optional \`for_records\` param: pass a sample of CSV-shaped rows and the tool al
 
 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.
+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. Cache the result per session; re-fetch only after a \`leadbay_create_custom_field\` call (which can change the catalog).
+
+---
+
+## RENDERING
+
+When called mid-import (internal use), do NOT render \u2014 return the data only.
+
+When the user asks to inspect the org's fields directly, render two sectioned bulleted lists:
+
+##### Standard fields
+
+Bullet each, grouped by domain (lead identity \u2192 location \u2192 sector \u2192 contact \u2192 status). Keep field names verbatim.
+
+##### Custom fields (N defined)
+
+Bullet each as \`<name> \xB7 <type> \xB7 \` \`\` \`<mapping_value>\` \`\` (mapping_value in backticks \u2014 agents need it verbatim for import calls).
+
+When called with \`for_records\`, append a final section **"Mapping hints for your file"** with the per-column suggestions; flag low-confidence mappings explicitly.
+
+---
+
+## NEXT STEPS
+
+| Observation                                | Suggest                                                     | Calls                                                  |
+|--------------------------------------------|-------------------------------------------------------------|--------------------------------------------------------|
+| User is preparing an import                | "Map a file"                                                | leadbay_resolve_import_rows / leadbay_import_leads     |
+| User needs a custom field that doesn't exist | "Create a new custom field"                               | leadbay_create_custom_field                            |
+| for_records was passed; hints look good    | "Run the import with these mappings"                        | leadbay_import_leads(records, mappings)                |
 `;
 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.
 
@@ -827,11 +990,110 @@ 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.
+var leadbay_prepare_outreach = `Prepare a single-lead outreach brief: the full \`lead\` block (score, \`split_ai_summary\`, \`location\`, \`size\`, \`phone_numbers\`, \`website\`, \`description\`, \`social_urls\`, \`social_presence\`), the \`recommended_contact\` (always in the post-enrichment shape \u2014 \`contact_id\`, \`first_name\`, \`last_name\`, \`job_title\`, \`email\`, \`phone_number\`, \`linkedin_page\`, \`is_org_contact\` \u2014 with nulls where data isn't yet enriched), \`additional_contacts_count\` (other contacts at this company), and an \`enrichment\` block describing async state.
+
+Optionally trigger contact enrichment in-flight with \`enrich:true\`. Enrichment is async (~60s). **Self-polling pattern (no separate tool needed):** re-call \`leadbay_prepare_outreach(leadId)\` without \`enrich\`; check \`enrichment.complete\`. When \`complete: true\`, the recommended contact now carries \`email\` and/or \`phone_number\`.
 
-WHEN TO USE: when the agent is about to draft outreach for ONE specific lead and needs the contact's email/phone.
+The first call to this tool on a lead records a \`LEAD_VIEWED\`-style prospecting action server-side (one per lead per session \u2014 deduped) so the lead ages out of the Discover "new" view.
+
+IRON LAW \u2014 OUTCOME AFTER OUTREACH. The moment the user reports outreach happened ("I sent it", "she didn't pick up", "left a voicemail", "they replied", a forwarded email thread, a calendar invite), you MUST (1) call leadbay_report_outreach with verification (gmail_message_id, calendar_event_id, or the user's literal one-sentence confirmation as user_confirmed.ref) AND (2) ask the user about the outcome and set epilogue_status to one of the 4 canonical values: EPILOGUE_INTEREST_VALIDATED_OR_MEETING_PLANED ("Meeting booked"), EPILOGUE_COULD_NOT_REACH_STILL_TRYING ("Trying to reach"), EPILOGUE_NOT_INTERESTED_LOST ("Not interested"), EPILOGUE_STILL_CHASING ("In progress"). Use the user-facing labels in dialogue ("What's the outcome \u2014 meeting booked, trying to reach, not interested, or in progress?"); never say "epilogue" out loud. Skipping this step silently de-ranks every future follow-up suggestion because pull_followups depends on honest, current outcomes.
+
+
+WHEN TO USE: when the agent is about to draft outreach for ONE specific lead and needs everything to compose \u2014 channels + angles + history context.
 
 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).
+
+---
+
+## RENDERING \u2014 outreach brief (single-record card)
+
+Present as the richest single-record card the MCP emits. The user is seconds-to-minutes away from contacting someone \u2014 every section earns its place by either (a) telling them HOW to outreach, (b) showing what they've done before, or (c) surfacing what's missing and how to get it.
+
+**Async enrichment.** When \`enrichment.triggered && !enrichment.complete\`, do NOT block the user. Render the brief with \`\u23F3\` on un-enriched channels and IMMEDIATELY draft a first version of the outreach using whatever data IS available (\`split_ai_summary.approach_angle\`, company-line phone, LinkedIn-search fallback). Tell the user: *"I'll refresh once enriched data lands."* On their next message (or after a clear pause), re-call \`leadbay_prepare_outreach(leadId)\` without \`enrich\`; if \`enrichment.complete: true\`, surface the now-resolved channels and offer to revise the draft.
+
+### Structure
+
+**Header** (H5): \`\u{1F4DE} Outreach prep \u2014 [Contact name](LinkedIn) \xB7 [Company](website)\`
+
+- Sub-line: job title \xB7 \`+N more contacts\` when \`additional_contacts_count > 0\`.
+- Prefix \`https://\` to \`website\` if it's a bare hostname.
+
+**Score line** (when \`lead.score\` is present): the 10-segment bar inline, no \`<br>\`. Same algorithm as \`pull_leads\`.
+
+**Channel readiness** \u2014 a single line of pill chips, \` \xB7 \`-separated:
+
+- \`\u{1F517} LinkedIn\` \u2014 \`profile\` (linked to real URL) if \`linkedin_page\` present; \`search\` (linked to people-search fallback) otherwise. \`\u23F3\` during enrichment.
+- \`\u{1F4E7} Email\` \u2014 show address if present; \`\u23F3 enriching\` when \`enrichment.triggered && !complete\`; \`\u26AA not enriched\` otherwise.
+- \`\u{1F4DE} Phone\` \u2014 contact-specific number if present; fall back to \`lead.phone_numbers[0]\` with \`(company line)\` annotation; \`\u23F3\` / \`\u26AA\` otherwise.
+
+**H5: \u{1F3AF} Angles & approach**
+
+- Render \`lead.split_ai_summary.approach_angle\` as the lead-in.
+- 3\u20134 bullets distilling \`split_ai_summary.next_step\` and any signals from a prior \`research_company\` call into salesperson-voice talking points. Cite \`[source](url)\` inline when known.
+- Final line: \`Recommended channel: <X> \u2014 <rationale>\`. Compute the recommendation from what data is available (email present \u2192 email; phone present \u2192 call; LinkedIn only \u2192 DM).
+
+**H5: \u{1F4DC} History with [Contact name]**
+
+When prior contact-level actions / notes are surfaced (or when \`prospecting_actions_count > 0\`), render a reverse-chronological timeline: \`<date> \xB7 <action_type> \xB7 <one-line summary>\`. Quote-block recent notes below. If empty: \`*No prior touchpoints with this contact.*\`
+
+**H5: \u{1F3E2} History with [Company name]**
+
+Same shape as the contact history, but only include items NOT duplicated from the contact section. If both empty: \`*No company-level history recorded.*\`
+
+**H5: \u{1F465} Other contacts** (only if \`additional_contacts_count > 0\`)
+
+One line: \`+N more contacts at this company \u2014 [see them all](leadbay_research_company)\`.
+
+**Closing line** (when enrichment is in progress): \`*Enrichment running \u2014 I'll refresh once email/phone lands.*\`
+
+**Hide:** \`id\`, \`lead.id\`, raw \`enrichment.hint\` when redundant with channel pills, history items without descriptions, any field whose value is the string \`"null"\`, deprecated \`other_contacts_count\` (use \`additional_contacts_count\`).
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+---
+
+## NEXT STEPS \u2014 after the outreach brief
+
+Offer 2\u20133 follow-ups. Choose based on enrichment state + available channels + history. Always offer the "log outreach" option once the user has clearly contacted someone.
+
+| Observation                                     | Suggest                                                       | Calls                                                  |
+|-------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|
+| \`enrichment.triggered && !enrichment.complete\`  | "Refresh now to check enrichment progress"                    | leadbay_prepare_outreach(leadId) \u2014 re-call             |
+| Email available                                 | "Draft the outreach email"                                    | (agent self-drafts inline, using split_ai_summary)     |
+| Direct phone available                          | "Draft the 60-second call opener"                             | (agent self-drafts inline)                             |
+| LinkedIn URL available                          | "Draft the LinkedIn DM"                                       | (agent self-drafts inline)                             |
+| Only company line, no direct phone              | "Draft a switchboard script targeting [Contact]"              | (agent self-drafts; flag uncertainty)                  |
+| \`additional_contacts_count > 0\`                 | "Show me the other N contacts at this company"                | leadbay_get_contacts(leadId)                           |
+| History is empty                                | "Pull the strategic overview before drafting"                 | leadbay_research_company(leadId)                       |
+| User reports they reached out                   | "Log this outreach \u2014 creates prospecting action + outcome"    | leadbay_report_outreach(leadId, contact_id, ...)       |
+| User adds context for next time                 | "Save a note on the contact or company"                       | leadbay_add_note                                       |
+| After a successful exchange                     | "Update qualification answers based on what you learned"      | leadbay_answer_clarification                           |
+
+The "log outreach" step is the most-important follow-up \u2014 it closes the loop and populates history for the next \`leadbay_prepare_outreach\` call. Detect intent from natural language: "I sent the email", "she didn't pick up", "left a voicemail", "they responded yes/no", etc.
 `;
 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.
 
@@ -847,13 +1109,252 @@ WHEN NOT TO USE: as a non-admin (will fail with 403); for personal lens changes
 
 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.
+var leadbay_pull_followups = `Pull KNOWN leads from the user's Monitor view \u2014 the re-engagement entry point of the two-entry-point workflow. Use when the user asks "what should I follow up on", "leads I haven't contacted", "leads in [city]", "before my trip", "this month", "what's overdue", or any phrasing that implies pre-existing pipeline context. For NEW leads from the Discover wishlist, use \`leadbay_pull_leads\` instead.
+
+Backend: wraps \`GET /1.5/monitor?personal=&liked=&filtered=&count=&page=\` plus, when \`set_filter\` is supplied, a preceding \`POST /1.5/monitor/filter\` to persist the filter server-side. The Monitor filter is a single \`FilterItem\` per user \u2014 refreshing the page restores it.
+
+**Filter mechanism \u2014 store-then-apply.** Pass \`set_filter: { criteria: FilterCriterion[] }\` to overwrite the server-stored filter, then the composite re-fetches with \`filtered:true\`. \`FilterCriterion\` is the backend's \`anyOf\` over 10 typed criteria: \`size\`, \`keywords\`, \`sector_ids\`, \`location_ids\`, \`custom_field\`, \`custom_field_comparison\`, \`yc\`, \`liked\`, \`last_action\` (filters by MonitorActionType enum), \`last_action_date\` (with \`last_days\` for "last N days").
+
+Practical mapping from user phrasing to criterion:
+
+| User phrase                          | Criterion                                                                 |
+|--------------------------------------|---------------------------------------------------------------------------|
+| "leads in Lyon"                      | \`{type: "location_ids", locations: [<admin_area_id>]}\`                    |
+| "healthcare staffing"                | \`{type: "keywords", keywords: ["healthcare", "staffing"]}\`                |
+| "leads I haven't touched in 30 days" | \`{type: "last_action_date", last_days: 30}\`                               |
+| "leads I liked"                      | \`{type: "liked"}\`                                                         |
+| "leads where I purchased contacts"   | \`{type: "last_action", types: ["PURCHASE_LEAD_CONTACT"]}\`                 |
+| "leads 50\u2013200 employees"             | \`{type: "size", sizes: [{min: 50, max: 200}]}\`                            |
+| "Y Combinator companies"             | \`{type: "yc"}\`                                                            |
+
+Geo filtering requires \`admin_area_id\` resolution (the backend doesn't accept free-text city names in \`location_ids\`). The MCP doesn't expose an admin-area lookup yet \u2014 for now, ask the user to pick the geo from the Leadbay app's filter UI, or skip the geo filter and rely on agent post-filtering of the response.
+
+**Pushback exclusion.** Leads with active pushback (\`pushback_status\` set and \`pushback_until > today\`) are excluded from the response. The composite enforces this client-side; \`total_excluded_by_pushback\` in the output reports how many rows were dropped.
+
+WHEN TO USE: when the user is re-engaging pipeline ("what should I follow up on", "leads in [city]", "stale leads"), or wants to filter their monitored leads by city / sector / recency / action type / liked.
+
+WHEN NOT TO USE: for NEW leads from the wishlist \u2014 that's \`leadbay_pull_leads\` (discovery). The two surfaces overlap but rank differently; pulling the wrong one wastes the user's time.
+
+---
+
+## RENDERING \u2014 follow-ups table, status-badge driven
+
+Markdown table with FOUR columns, sorted by \`last_monitor_action_at\` desc. **NO score bar in this view** \u2014 discovery owns the \`\u25B0\u2756\u25B1\` visual identity; follow-up uses status badges. Active-pushback leads are already excluded server-side.
+
+**Active-filters line** ABOVE the table, \` \xB7 \`-separated chips from \`active_filters.criteria\`:
+
+| Criterion type        | Chip                       |
+|-----------------------|----------------------------|
+| \`location_ids\`        | \u{1F4CD} \\<resolved name\\>       |
+| \`sector_ids\`          | \u{1F3F7} \\<sector name\\>         |
+| \`keywords\`            | \u{1F50D} \\<keyword\\>             |
+| \`size\`                | \u{1F465} \\<min\\>\u2013\\<max\\>         |
+| \`last_action_date\`    | \u{1F4C5} \\<window\\>              |
+| \`last_action\`         | \u{1F3AF} \\<action types\\>        |
+| \`liked\` / \`yc\`        | \u2B50 liked / \u{1F3C5} YC           |
+| \`custom_field*\`       | \u2699 \\<field name\\>          |
+
+Render \`*No filters applied.*\` when empty.
+
+**Column 1 \u2014 Status** (DERIVED from existing fields, priority order):
 
-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.
+1. \`epilogue_status == "EPILOGUE_INTEREST_VALIDATED_OR_MEETING_PLANED"\` \u2192 \u{1F3AF} Meeting booked
+2. \`epilogue_status == "EPILOGUE_COULD_NOT_REACH_STILL_TRYING"\` \u2192 \u26A1 Trying to reach
+3. \`epilogue_status == "EPILOGUE_STILL_CHASING"\` + last_prospecting_action_at within 14d \u2192 \u{1F7E2} In progress
+4. \`epilogue_status == "EPILOGUE_NOT_INTERESTED_LOST"\` \u2192 \u2744 Not interested (usually filtered out)
+5. \`epilogue_status == null\` + \`last_prospecting_action_at == null\` \u2192 \u2728 New
+6. \`epilogue_status == null\` + \`last_prospecting_action_at > 60d\` \u2192 \u{1F4A4} Dormant
+7. Otherwise \u2192 \u{1F525} Hot
+
+Append \`<relative time>\` of \`last_monitor_action_at\` (\`today\`/\`Nd\`/\`Nw\`/\`Nmo\`). For \u2728, show \`new\`. Line 2: **[Company](website)** bold. Line 3: short location \xB7 compact size.
+
+**Column 2 \u2014 AI take** (3 lines from \`split_ai_summary\` verbatim, \`<br>\`-separated):
+
+- Line 1: emoji + **bold split_ai_summary.worth_pursuing**. Emoji from leading word: \`Yes\u2026\`\u2192\u2705, \`No\u2026\`\u2192\u274C, \`Maybe\u2026\`\u2192\u{1F914}, else\u2192\u{1F4A1}.
+- Line 2: *italic split_ai_summary.approach_angle* (\u2264 18 words).
+- Line 3: **Next:** split_ai_summary.next_step.
+- Fallback when null: render \`ai_summary\` italic, no emoji.
+
+**Column 3 \u2014 History & notes**
+
+- Line 1: \`<relative time> ago \xB7 <last_prospecting_action>\` (humanize: snake_case \u2192 Title Case; drop \`LEAD_\` prefix). When null: \`*Never touched.*\`
+- Line 2 (when \`epilogue_status\` set): \`\u{1F4CC} Outcome: <user-facing label> \xB7 <relative time>\` \u2014 NEVER show the wire-format \`EPILOGUE_*\` value.
+- Line 3 (when a recent note surfaces): \`\u{1F4DD} *<note clipped \u2264 14 words>* (<rel time>)\`.
+- If neither: \`*0 prior touches \xB7 0 notes*\`.
+
+**Column 4 \u2014 Contacts** (max 3 lines, recommended_contact first):
+
+\`\`\`
+\u2605 [Name](linkedin_page or people-search) \xB7 \u260E phone \xB7 \u{1F4E7} email
+\`\`\`
+
+Markers: \`\u2605\` recommended, \`\u{1F48E}\` hot in web_insights key_people. Channel pills: \`\u260E phone\` (rec.phone_number \u2192 lead.phone_numbers[0] \`(co)\` \u2192 \`\u26AA phone\`); \`\u{1F4E7} email\` (rec.email \u2192 \`\u26AA email\`). When no visible contact has email/direct phone: append \`*enrich first*\` in italic.
+
+**Hide:** \`id\`, \`location.pos\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`stale_at\`, \`sector_id\`, zero counters, \`social_presence\` booleans (except \xB0-flag), \`score\`, string \`"null"\`.
+
+**Legend** (user-facing \u2014 NEVER say "epilogue"):
+
+\u{1F3AF} Meeting booked \xB7 \u26A1 Trying to reach \xB7 \u{1F7E2} In progress \xB7 \u{1F4A4} Dormant \xB7 \u2728 New \xB7 \u{1F525} Hot \xB7 \u2744 Not interested \xB7 \u2605 recommended \xB7 \u{1F48E} hot in web_insights \xB7 \u260E (co) = company line \xB7 \u26AA not enriched
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+---
+
+## NEXT STEPS \u2014 after the follow-ups table
+
+Always include at least one filter-modification offer (users think in filters: by city, by recency, by action type). Filter modification goes through \`set_filter: FilterItem\` which the composite POSTs to \`/monitor/filter\` server-side.
+
+| Observation                                   | Suggest                                                  | Calls                                                                                              |
+|-----------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------|
+| Always (top of menu)                          | "Prep outreach for [top row's contact]"                  | leadbay_prepare_outreach(leadId)                                                                   |
+| User named a city / sector / timeframe        | "Refilter by [their phrase]"                             | leadbay_pull_followups(set_filter: { criteria: [...] })                                            |
+| \`pagination.has_more == true\`                 | "Pull the next page"                                     | leadbay_pull_followups(page = current + 1)                                                         |
+| \u22653 rows \u2728 (never-touched)                    | "Surface only never-touched leads"                       | set_filter with \`last_action_date.last_days = 0\`                                                   |
+| \u22653 rows \u26A1 (Trying to reach)                  | "Focus on overdue commitments"                           | set_filter with \`last_action.types = ["EPILOGUE_COULD_NOT_REACH_STILL_TRYING"]\`                    |
+| User planning a trip / in a city              | "Group by city for trip planning"                        | set_filter with \`location_ids\` (requires admin_area_id)                                            |
+| All rows last action > 60d                    | "Re-qualify \u2014 context may have changed"                  | leadbay_bulk_qualify_leads([leadId, ...])                                                          |
+| One obvious priority row                      | "Take me to that lead's full brief"                      | leadbay_prepare_outreach(leadId) / leadbay_research_lead(leadId)                                   |
+| User wants to defer a lead                    | "Snooze [Company] for 3 / 6 / 12 months"                 | leadbay_set_pushback({ lead_ids:[leadId], status:"3" })                                            |
+| User completed outreach mid-flow              | "Log the outreach + record the outcome"                  | leadbay_report_outreach                                                                            |
+| Discovery mode might fit better               | "Looking for NEW leads instead? Switch to discovery."    | leadbay_pull_leads                                                                                 |
+
+Always offer at least one of: prep outreach, refilter, pushback. Pushback is the canonical way to honor "not now" / "next quarter" \u2014 leads with active pushback are excluded from this view until expiry.
+`;
+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 / 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 \u2014 a healthy daily rhythm is to bulk-qualify the rows without \u2756 caps so tomorrow's top-10 list is richer.
+
+Every lead carries \`recommended_contact\` (with \`linkedin_page\` when the backend has it), \`phone_numbers\` (when available), \`split_ai_summary.{worth_pursuing, approach_angle, next_step}\` (when AI-qualified), and \`social_urls\` per-platform (linkedin, instagram, tiktok, facebook, twitter, crunchbase). Use them \u2014 they're already in the response, you don't need a second call.
 
 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).
+
+The active lens can change between calls (5-min cache + backend \`last_requested_lens\`). If a multi-step workflow depends on staying on one lens, **capture \`response.lens.id\` from the first response and pass it as the \`lensId\` argument on every subsequent Leadbay call** \u2014 including re-pulls, bulk qualifies, and research. (Field-name caveat: response nests it as \`lens.id\`; the parameter is \`lensId\`.) Re-pulling without \`lensId\` after a long-running tool may silently switch to a different lens and discard prior work.
+
+---
+
+## RENDERING \u2014 markdown table, three columns, score-bar driven
+
+Present the response as a markdown table sorted by \`score\` descending, with exactly three columns. Do not summarize in prose. Do not show the numeric score anywhere.
+
+## Score-bar (10-segment, inline-code wrapped)
+
+Wrap a 10-glyph bar in a SINGLE inline-code span (backticks). The inline-code styling is what gives the bar contrast in most chat renderers \u2014 HTML \`<span>\` is stripped inside table cells.
+
+Glyphs (use these exact characters; do not substitute):
+
+- \`\u25B0\` \u2014 firmographic-only fill
+- \`\u2756\` \u2014 AI-booster cap (placed at the RIGHT END of the filled run, never the front)
+- \`\u25B1\` \u2014 empty
+
+Computation:
+
+\`\`\`
+total_filled  = round(score / 10), clamped to 0..10
+ai_segments   = round(qualification_summary.avg_qualification_boost / 3.3),
+                clamped to [0, total_filled]
+normal_filled = total_filled \u2212 ai_segments
+bar = "\u25B0" \xD7 normal_filled
+    + "\u2756" \xD7 ai_segments
+    + "\u25B1" \xD7 (10 \u2212 total_filled)
+\`\`\`
+
+If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is null, set \`ai_segments = 0\` (no \u2756). Always wrap the bar in backticks. Print the legend \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster cap \xB7 \`\u25B1\` unfilled \`\` once below the table.
+
+
+**Column 1 \u2014 Company**
+
+- Line 1: the 10-segment score bar in inline-code backticks (see the score-bar snippet above for the algorithm).
+- Insert \`<br>\` between lines.
+- Line 2: linked company name + \` \xB7 \` + short location + \` \xB7 \` + compact size.
+  - Link target: \`website\` (prefix \`https://\` if it's a bare hostname). Don't synthesize an app deep-link.
+  - Location: shorten "City of New York" \u2192 "NYC"; otherwise "City ST"; state alone only when city missing.
+  - Size: \`"Xk+"\` when \`size.min >= 1000\`, \`"min\u2013max"\` otherwise.
+
+**Column 2 \u2014 Why it fits**
+
+- One sentence, \u2264 20 words.
+- Synthesize from (in priority order, whichever is present) the lead's \`short_description\`, top 2 \`tags[].display_name\`, and the gist of \`qualification_summary.best_response_excerpt\`. The trim payload does NOT carry the longer \`description\` field \u2014 for that, agent must call \`leadbay_research_lead\` or \`leadbay_research_company\`.
+- Do NOT append \`(boost N)\` \u2014 the \u2756 cap in column 1 already carries that signal.
+- No bullet lists, no line breaks inside the cell.
+
+**Column 3 \u2014 Contact**
+
+\`[Contact name](LINK) \xB7 short job title\`. See linking/contact-linkedin for LINK priority and the \xB0-flag fallback.
+
+**Hide from the user (never include in any cell):** \`id\`, \`location.pos\`, \`location.country\` (unless city/state both missing), \`sector_id\`, \`is_hq\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`highlighted_fields\`, \`custom_fields\`, \`contacts_count\` when 0, \`notes_count\` / \`epilogue_actions_count\` / \`prospecting_actions_count\` when 0, \`stale_at\`, \`deal_insights\`, \`social_presence\` booleans (except as the \xB0-flag signal), \`need_attention\` flags, any field whose value is the string \`"null"\`.
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+---
+
+## NEXT STEPS \u2014 after rendering the pull_leads table
+
+Pick 2\u20133 items below based on what was actually observed in the response. Surface them as a short bulleted list \u2014 do NOT recite the whole table.
+
+| Observation                                                | Suggest                                                      | Calls                                                  |
+|------------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------|
+| \`has_more == true\`                                         | "Pull the next page (page N+1 of M)"                         | leadbay_pull_leads(page = current + 1, lensId = pinned)|
+| \u2265 3 rows have \`qualification_summary.answered == 0\`        | "Deepen AI qualification on the rows without \u2756 caps"         | leadbay_bulk_qualify_leads(leadIds=[\u2026])                |
+| User points at a single row                                | "Research [Company] in depth"                                | leadbay_research_lead(leadId)                          |
+| User wants the company-level web view                      | "Pull the company-level research for [Company]"              | leadbay_research_company({leadId} or {companyName})    |
+| Top row has phone AND email                                | "Prepare an outreach for [Contact] \u2014 call + email"           | leadbay_prepare_outreach(leadId)                       |
+| Top row has email but no phone                             | "Draft an outreach email for [Contact]"                      | leadbay_prepare_outreach(leadId)                       |
+| Top row has phone but no email                             | "Show [Contact]'s call details + a 60-second opener"         | leadbay_prepare_outreach(leadId)                       |
+| Top row has contacts but no phone/email                    | "Order contact enrichment to surface email/phone first"      | leadbay_enrich_titles(...) or leadbay_prepare_outreach(leadId, enrich:true) |
+| \`computing_scores == true\` or \`computing_wishlist == true\` | "Scores are still being computed \u2014 re-pull in ~30s"          | leadbay_pull_leads (retry with same lensId)            |
+| User wants a narrower / wider audience                     | "Adjust the lens filters (sector / size)"                    | leadbay_adjust_audience(...)                           |
+
+If nothing in the menu applies cleanly, suggest only "pull next page" and "research a specific lead in depth" \u2014 never invent a tool that doesn't exist.
 `;
 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.
 
@@ -889,6 +1390,16 @@ 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_remove_pushback = `Clear an active pushback on one or more leads. They re-enter \`leadbay_pull_followups\` immediately. Use when the user changes their mind ("actually let's reach out now"), or when external context shifts (the company announces hiring / funding / a new product that makes them ripe sooner than the deferral window expected).
+
+Bulk-native: pass up to 1000 lead UUIDs per call. No status enum \u2014 pushback is binary (either an active window exists, or it doesn't).
+
+WHEN TO USE: the user wants to revive a snoozed lead now, ahead of the pushback window expiry.
+
+WHEN NOT TO USE: the pushback expired naturally (no API call needed; the lead reappears in \`pull_followups\` 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_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).
@@ -903,9 +1414,120 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 `;
 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\`.
+The response carries the rich-lead block (firmographics, \`phone_numbers\`, \`split_ai_summary\`, \`social_urls\`), \`qualification[]\` (Q&A pairs from the AI agent \u2014 empty until the lead is qualified), \`contacts[]\` (paid + org, each with a normalized \`linkedin_page\`), \`web_insights\` (keyed by emoji-prefixed section labels \u2014 see RENDERING for handling), \`web_insights_fetched_at\` (staleness), and \`recent_activities\` (engagement history).
+
+WHEN TO USE: when the user references a company by name and you don't yet have its \`lead_id\`, OR when you want a single-record card with web-research signals (business signals, prospecting clues, strategic positioning) rather than a raw lead profile.
+
+WHEN NOT TO USE: when you already have the lead_id and need the bundled deeper lens-scoped data \u2014 use leadbay_research_lead.
+
+---
+
+## RENDERING \u2014 single-record research card, mode-adaptive
+
+Present as a single-record card, not a table. This tool gets invoked in two distinct user contexts \u2014 detect which and adapt the body density accordingly.
+
+**MODE A \u2014 Discovery.** The user is evaluating whether to pursue this company as a target. Signals: "tell me about", "what do they do", "is this a fit", "research [company]", arrival via a click-through from \`leadbay_pull_leads\`, no prior outreach context in the conversation. Next step is usually qualify, deep-dive via \`leadbay_research_lead\`, or decide whether to start outreach.
+
+**MODE B \u2014 Contact preparation.** The user is about to call or email someone at this company and needs the talking points. Signals: "I'm calling them", "draft an email", "before my call", "outreach prep", "what should I say", or the conversation has already touched on a specific contact. Next step is usually \`leadbay_prepare_outreach\`.
+
+Default to MODE A when uncertain. Always offer the cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### Common structure (both modes)
+
+- **Header** (H4 or H5): \`<10-segment score bar>\` \`[Company name](website)\`. Use the score-bar algorithm; the bar lives in a single inline-code span. Prefix \`https://\` to website if it's a bare hostname.
+- **Pill row** (immediately below the header): short location \xB7 compact size \xB7 social pill chips iterated over \`social_urls\` (each non-null platform becomes \`[<platform-label>](<url>)\`) \xB7 \`[website-domain](website)\` \xB7 \`\u260E phone\` when \`phone_numbers[]\` is non-empty (use the first number). All \` \xB7 \`-separated.
+- **Blurb**: render \`description\` (preferred) or \`short_description\` as a single blockquoted paragraph.
+- **Staleness line**: italic, \`"Researched <relative time>"\` from \`web_insights_fetched_at\`. Use \`"today"\` / \`"yesterday"\` / \`"N days ago"\` up to 30 days, then absolute date. Prefix with \`\u26A0\` if older than 30 days.
+- **Contacts table** (always at the bottom):
+  \`\`\`
+  |   | Name | Title | LinkedIn |
+  \`\`\`
+  Markers in column 1:
+  - \`\u2605\` \u2014 \`recommended_contact\` match.
+  - \`\u{1F48E}\` \u2014 name fuzzy-matches a \`hot: true\` entry in \`web_insights\` key_people. (Use \`\u{1F48E}\`, not \`\u{1F525}\`, to avoid glyph collision with the follow-up status badge.)
+  Sort \`\u2605\` first, then \`\u{1F48E}\`-only rows, then API order. Link the name via \`linkedin_page\` first; fall back to LinkedIn people-search with \`<First>+<Last>+<Company>\`. Append \`\xB0\` only when the fallback is in use AND \`social_presence.linkedin == false\`. Cap to 6 rows; if \`contacts_count > shown\`, end with \`"+N more \u2014 ask to see the full list"\`.
+
+### MODE A body (Discovery, fuller, scannable)
+
+Render each non-empty \`web_insights\` section as H5 with the emoji + label intact. Section order: \`\u{1F3E2} company profile\` \u2192 \`\u{1F4C8} business signals\` \u2192 \`\u{1F4A1} prospecting clues\` \u2192 \`\u{1F9E9} strategic positioning\` \u2192 \`\u{1F50E} technologies & innovation\`. Inside each, bullet 3\u20135 items. Sort \`hot: true\` items first. **Bold** the description text of hot items; leave cold items plain. Render \`source\` as \`[source](url)\` at the end; include \`date\` when present. Omit empty sections. Skip \`\u{1F517} social links\` (already in the pill row) and \`\u{1F464} key people\` (already in the contacts table).
+
+### MODE B body (Contact preparation, tighter)
+
+Render exactly two H5 sections:
+
+##### \u{1F3AF} Conversation hooks
 
-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).
+Distill the 3 most recent / most hot signals from \`\u{1F4C8} business signals\` and \`\u{1F4A1} prospecting clues\` into one-sentence talking points in salesperson voice. Strip the academic framing. Cite the source inline.
+
+##### \u{1F464} About the person *(only when recommended_contact is non-empty)*
+
+2-line summary: their title + any context from \`web_insights\` key_people. If they appear in a hot signal ("X appointed CEO"), surface that prominently.
+
+Skip \u{1F3E2} profile, \u{1F9E9} strategic positioning, \u{1F50E} technologies in MODE B \u2014 context the user doesn't need for the next 30 seconds.
+
+If \`qualification[]\` is non-empty, append one collapsed line: \`"Qualification: N questions answered, avg boost X"\` and offer to expand in NEXT STEPS.
+
+**Hide:** \`id\`, \`lead.id\`, \`contact.id\`, \`lead.location.pos\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`recommended_contact_title\` (duplicates \`recommended_contact.job_title\`), empty arrays, fields whose value is the string \`"null"\`, \`contact.source\` (internal), insights whose \`source\` is empty.
+
+**Legend (print once below the card):** \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster \xB7 \`\u25B1\` unfilled \xB7 \u2605 recommended \xB7 \u{1F48E} hot in web_insights \xB7 \xB0 = no company LinkedIn (fallback link only) \`\`
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+---
+
+## NEXT STEPS \u2014 after the research card
+
+Offer 2\u20133 follow-ups that match the detected mode. Always offer a cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### MODE A (Discovery)
+
+| Observation                                            | Suggest                                            | Calls                                              |
+|--------------------------------------------------------|----------------------------------------------------|----------------------------------------------------|
+| \`qualification[]\` is empty                             | "Run AI qualification on this lead"                | leadbay_bulk_qualify_leads([leadId])               |
+| \u22651 hot recent item in \u{1F4C8} business signals              | "Prepare outreach referencing [signal headline]"   | leadbay_prepare_outreach(leadId)                   |
+| \`contacts_count > len(contacts)\` shown                 | "Pull the full contact list (N more)"              | leadbay_get_contacts(leadId)                       |
+| \`web_insights_fetched_at\` > 30 days                    | "Re-run the web research \u2014 this is stale"          | leadbay_research_company(leadId) \u2014 refresh         |
+| User wants the deeper lens-scoped bundle               | "Pull the full lead profile (research_lead)"       | leadbay_research_lead(leadId)                      |
+| User is exploring multiple companies                   | "Back to the lead list"                            | leadbay_pull_leads                                 |
+| \`qualification[]\` non-empty                            | "Expand the AI qualification answers"              | (render qualification[] as a sub-card)             |
+
+End MODE A with the pivot offer: \`"Want the contact-prep view for [recommended contact name]?"\`
+
+### MODE B (Contact preparation)
+
+| Observation                                            | Suggest                                            | Calls                                              |
+|--------------------------------------------------------|----------------------------------------------------|----------------------------------------------------|
+| \`phone_numbers[]\` non-empty                            | "Show full call notes + a 60-second opener"        | leadbay_prepare_outreach(leadId)                   |
+| Recommended contact has an email                       | "Draft the outreach email"                         | leadbay_prepare_outreach(leadId)                   |
+| Neither phone nor email for recommended contact        | "Order contact enrichment first"                   | leadbay_prepare_outreach(leadId, enrich:true) or leadbay_enrich_titles |
+| After the user reports a touchpoint                    | "Log the call/email outcome"                       | leadbay_report_outreach                            |
+| Adding pre-call context                                | "Add a note to this lead"                          | leadbay_add_note                                   |
+
+End MODE B with the pivot offer: \`"Want the full strategic overview instead?"\`
 `;
 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.
 
@@ -914,12 +1536,46 @@ Scoring has two layers: the basic \`score\` (firmographic, always present, alrea
 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.)
+
+**Concurrency note**: this is a composite that reads many sub-resources per call. Call it **sequentially** or in small batches (\u22643 parallel) when researching multiple leads. Firing 10+ in parallel can saturate the transport and produce misleading \`"Tool permission stream closed"\` errors that look like permission failures but are really backpressure. On a transient stream/timeout failure, retry the same lead once before moving on.
 `;
 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.
+
+---
+
+## RENDERING
+
+Present as a markdown table of resolution outcomes per row.
+
+\`\`\`
+| Source row | Match status | Resolved leadId / candidates |
+\`\`\`
+
+Status emoji map:
+
+- \`\u2713\` unambiguous match \u2014 one Leadbay lead, high confidence
+- \`\u26A0\` ambiguous \u2014 multiple candidates returned
+- \`\u2717\` no match \u2014 backend has no candidates; can still import if \`website\` is present
+- \`\u23F3\` resolving \u2014 async resolve still running
+
+For ambiguous rows, list up to 3 candidate names + leadIds inline. Truncate the source row to a short identifier (first non-empty column or domain).
+
+Below the table, a one-liner: \`"Ready: K rows \xB7 Ambiguous: A rows \xB7 Unmatched: U rows"\`
+
+---
+
+## NEXT STEPS
+
+| Observation                            | Suggest                                                     | Calls                                                  |
+|----------------------------------------|-------------------------------------------------------------|--------------------------------------------------------|
+| All rows resolved cleanly              | "Import these rows now"                                     | leadbay_import_leads(records_for_import, mappings_for_import) |
+| Ambiguous rows present                 | "Inspect candidates for each ambiguous row"                 | (re-call with include_candidate_profiles=true)         |
+| Unmatched rows but websites present    | "Import anyway \u2014 Leadbay will crawl and match later"        | leadbay_import_leads (status check after)              |
+| User wants to skip rows they can't ID  | "Drop unmatched rows and import the rest"                   | leadbay_import_leads (with filtered records)           |
 `;
 var leadbay_select_leads = `Add leads to the user's transient selection (used by selection-scoped bulk operations). Accepts 1-1000 \`leadIds\` per call.
 
@@ -943,6 +1599,18 @@ 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_pushback = `Snooze (pushback) one or more leads for 3, 6, or 12 months. The leads remain in the user's pipeline but are excluded from \`leadbay_pull_followups\` until the pushback window expires. Use this when the user says "not now", "next quarter", "follow up in 3 months", "6 months out", "next year", or any equivalent deferral.
+
+Accepts short labels (\`3\`, \`6\`, \`12\` \u2014 months) or the wire-format enum (\`PUSHBACK_3\`, \`PUSHBACK_6\`, \`PUSHBACK_12\`). Bulk-native: pass up to 1000 lead UUIDs per call.
+
+User-facing language: "snooze for 3/6/12 months" (or "pushback" if the user uses the term themselves). Never say "pushback status" in dialogue \u2014 say "snooze" or "follow up in N months".
+
+WHEN TO USE: the user explicitly says they want to defer a lead (or a small set of leads) for a known window. Pair with \`leadbay_add_note\` if the user's reason for deferring is worth preserving.
+
+WHEN NOT TO USE: the user is just skipping ONE outreach attempt \u2014 that's a normal \`EPILOGUE_COULD_NOT_REACH_STILL_TRYING\` outcome via \`leadbay_report_outreach\`, not a snooze.
+
 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.
@@ -1134,6 +1802,16 @@ var discoverLeads = {
 };
 
 // ../core/dist/tools/get-lead-profile.js
+function normalizeLinkedinPage(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
 var getLeadProfile = {
   name: "leadbay_get_lead_profile",
   annotations: {
@@ -1210,7 +1888,7 @@ var getLeadProfile = {
         last_name: c.last_name,
         email: c.email,
         phone_number: c.phone_number,
-        linkedin_page: c.linkedin_page,
+        linkedin_page: normalizeLinkedinPage(c.linkedin_page),
         job_title: c.job_title,
         recommended: c.recommended,
         enrichment: c.enrichment,
@@ -1222,7 +1900,7 @@ var getLeadProfile = {
         last_name: c.last_name,
         email: c.email,
         phone_number: c.phone_number,
-        linkedin_page: c.linkedin_page,
+        linkedin_page: normalizeLinkedinPage(c.linkedin_page),
         job_title: c.job_title,
         recommended: c.recommended,
         enrichment: c.enrichment,
@@ -1247,8 +1925,14 @@ var getLeadProfile = {
         phone_numbers: lead.phone_numbers,
         keywords: lead.keywords,
         contacts_count: lead.contacts_count,
-        recommended_contact_title: lead.recommended_contact_title ?? null,
-        recommended_contact: lead.recommended_contact ?? null,
+        // B8: recommended_contact_title dropped — duplicates
+        // recommended_contact.job_title. B1+B7: propagate linkedin_page.
+        recommended_contact: lead.recommended_contact ? {
+          ...lead.recommended_contact,
+          linkedin_page: normalizeLinkedinPage(lead.recommended_contact.linkedin_page ?? null)
+        } : null,
+        social_presence: lead.social_presence ?? null,
+        social_urls: lead.social_urls ?? null,
         web_fetch_in_progress: lead.web_fetch_in_progress ?? false
       },
       qualification: qualification?.map((q) => ({
@@ -4030,6 +4714,100 @@ var removeEpilogue = {
   }
 };
 
+// ../core/dist/tools/set-pushback.js
+var PUSHBACK_LABEL_MAP = {
+  "3": "PUSHBACK_3",
+  "6": "PUSHBACK_6",
+  "12": "PUSHBACK_12",
+  "3m": "PUSHBACK_3",
+  "6m": "PUSHBACK_6",
+  "12m": "PUSHBACK_12",
+  "3_months": "PUSHBACK_3",
+  "6_months": "PUSHBACK_6",
+  "12_months": "PUSHBACK_12",
+  PUSHBACK_3: "PUSHBACK_3",
+  PUSHBACK_6: "PUSHBACK_6",
+  PUSHBACK_12: "PUSHBACK_12"
+};
+var setPushback = {
+  name: "leadbay_set_pushback",
+  annotations: {
+    title: "Pushback (snooze) leads for 3 / 6 / 12 months",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_set_pushback,
+  optional: true,
+  write: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lead_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Lead UUIDs (1-1000)"
+      },
+      status: {
+        type: "string",
+        description: "One of: 3, 6, 12 (months) \u2014 or the long form PUSHBACK_3 / PUSHBACK_6 / PUSHBACK_12."
+      }
+    },
+    required: ["lead_ids", "status"],
+    additionalProperties: false
+  },
+  execute: async (client, params) => {
+    const wire = PUSHBACK_LABEL_MAP[String(params.status)];
+    if (!wire) {
+      return {
+        error: true,
+        code: "BAD_INPUT",
+        message: `Unknown pushback status: ${params.status}`,
+        hint: "Use one of: 3, 6, 12 (months) \u2014 or PUSHBACK_3 / PUSHBACK_6 / PUSHBACK_12."
+      };
+    }
+    await client.requestVoid("POST", "/leads/pushback", {
+      lead_ids: params.lead_ids,
+      status: wire
+    });
+    return { applied: true, count: params.lead_ids.length, status: wire };
+  }
+};
+
+// ../core/dist/tools/remove-pushback.js
+var removePushback = {
+  name: "leadbay_remove_pushback",
+  annotations: {
+    title: "Remove pushback (un-snooze) leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_remove_pushback,
+  optional: true,
+  write: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lead_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Lead UUIDs"
+      }
+    },
+    required: ["lead_ids"],
+    additionalProperties: false
+  },
+  execute: async (client, params) => {
+    await client.requestVoid("POST", "/leads/remove_pushback", {
+      lead_ids: params.lead_ids
+    });
+    return { cleared: true, count: params.lead_ids.length };
+  }
+};
+
 // ../core/dist/tools/preview-bulk-enrichment.js
 var previewBulkEnrichment = {
   name: "leadbay_preview_bulk_enrichment",
@@ -4300,6 +5078,16 @@ var researchCompany = {
 };
 
 // ../core/dist/composite/prepare-outreach.js
+function normalizeLinkedinPage2(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
 var prepareOutreach = {
   name: "leadbay_prepare_outreach",
   annotations: {
@@ -4320,7 +5108,7 @@ var prepareOutreach = {
       },
       enrich: {
         type: "boolean",
-        description: "If true and credits available, trigger enrichment on the recommended contact (default: false). Enrichment is async \u2014 poll leadbay_get_contacts after ~60s."
+        description: "If true and credits available, trigger enrichment on the recommended contact (default: false). Enrichment is async; re-call this tool (no enrich) after ~60s and check enrichment.complete to see if email/phone landed (B13: self-polling)."
       }
     },
     required: ["leadId"],
@@ -4331,32 +5119,67 @@ var prepareOutreach = {
     properties: {
       lead: {
         type: ["object", "null"],
-        description: "Short lead summary for outreach context: {name, ai_summary, website}. Null if /lead profile fetch failed.",
+        description: "Lead context for the brief. Expanded per B15: score, ai_summary, split_ai_summary, location, size, phone_numbers, website, description.",
         properties: {
+          id: { type: "string" },
           name: { type: "string" },
+          score: { type: ["number", "null"] },
+          ai_agent_lead_score: { type: ["number", "null"] },
           ai_summary: { type: ["string", "null"] },
-          website: { type: ["string", "null"] }
+          split_ai_summary: { type: ["object", "null"] },
+          location: { type: ["object", "null"] },
+          size: { type: ["object", "null"] },
+          phone_numbers: { type: ["array", "null"], items: { type: "string" } },
+          website: { type: ["string", "null"] },
+          description: { type: ["string", "null"] },
+          short_description: { type: ["string", "null"] },
+          social_presence: { type: ["object", "null"] },
+          social_urls: { type: ["object", "null"] }
         }
       },
       recommended_contact: {
         type: ["object", "null"],
-        description: "Best contact to outreach to ({id, name, job_title, email, phone_number, linkedin_page}). Null when no contacts known."
+        description: "Best contact to outreach to. Always returned in the post-enrichment shape (B21) \u2014 first_name/last_name/contact_id/email/phone_number/linkedin_page/job_title \u2014 with nulls in fields that aren't yet enriched.",
+        properties: {
+          contact_id: { type: ["string", "null"] },
+          first_name: { type: ["string", "null"] },
+          last_name: { type: ["string", "null"] },
+          job_title: { type: ["string", "null"] },
+          email: { type: ["string", "null"] },
+          phone_number: { type: ["string", "null"] },
+          linkedin_page: { type: ["string", "null"] },
+          is_org_contact: { type: ["boolean", "null"] }
+        }
+      },
+      additional_contacts_count: {
+        type: "number",
+        description: "How many other contacts exist beyond the recommended one (renamed from other_contacts_count per B16; both shipped for one release)."
+      },
+      total_contacts_count: {
+        type: "number",
+        description: "Total contacts on this lead (recommended + others)."
       },
       other_contacts_count: {
         type: "number",
-        description: "How many other contacts exist beyond the recommended one (so the agent knows there's more to discover via leadbay_get_contacts)."
+        description: "DEPRECATED: alias for additional_contacts_count. Will be removed in 0.10.0."
       },
       enrichment: {
         type: "object",
-        description: "Status of opt-in enrichment (only set when enrich:true was passed): {triggered, error, hint}.",
+        description: "Self-polling status (B13): triggered = whether this call kicked off enrichment; complete = whether the recommended contact now has email OR phone.",
         properties: {
           triggered: { type: "boolean" },
+          complete: { type: "boolean" },
           error: { type: ["string", "null"] },
           hint: { type: ["string", "null"] }
         }
       }
     },
-    required: ["recommended_contact", "other_contacts_count", "enrichment"]
+    required: [
+      "recommended_contact",
+      "additional_contacts_count",
+      "total_contacts_count",
+      "enrichment"
+    ]
   },
   execute: async (client, params, ctx) => {
     const contactsResult = await getContacts.execute(client, { leadId: params.leadId }, ctx);
@@ -4372,37 +5195,83 @@ var prepareOutreach = {
         enrichmentError = e?.message ?? String(e);
       }
     }
-    let leadSummary = null;
+    let refreshed = contacts;
+    if (enrichmentTriggered) {
+      try {
+        const again = await getContacts.execute(client, { leadId: params.leadId }, ctx);
+        refreshed = again.contacts ?? contacts;
+      } catch {
+      }
+    }
+    const recommendedFresh = refreshed.find((c) => c.recommended) ?? recommended;
+    let leadBlock = null;
     try {
       const profile = await getLeadProfile.execute(client, { leadId: params.leadId }, ctx);
-      leadSummary = {
-        name: profile.lead.name,
-        ai_summary: profile.lead.ai_summary,
-        website: profile.lead.website
+      const p = profile.lead;
+      leadBlock = {
+        id: p.id ?? params.leadId,
+        name: p.name ?? null,
+        score: p.score ?? null,
+        ai_agent_lead_score: p.ai_agent_lead_score ?? null,
+        ai_summary: p.ai_summary ?? null,
+        split_ai_summary: p.split_ai_summary ?? null,
+        location: p.location ?? null,
+        size: p.size ?? null,
+        phone_numbers: p.phone_numbers ?? null,
+        website: p.website ?? null,
+        description: p.description ?? null,
+        short_description: p.short_description ?? null,
+        social_presence: p.social_presence ?? null,
+        social_urls: p.social_urls ?? null
       };
     } catch {
+      leadBlock = {
+        id: params.leadId,
+        name: null,
+        ai_summary: null
+      };
     }
+    const recommendedContact = recommendedFresh ? {
+      contact_id: recommendedFresh.id ?? null,
+      first_name: recommendedFresh.first_name,
+      last_name: recommendedFresh.last_name,
+      job_title: recommendedFresh.job_title,
+      email: recommendedFresh.email,
+      phone_number: recommendedFresh.phone_number,
+      linkedin_page: normalizeLinkedinPage2(recommendedFresh.linkedin_page),
+      is_org_contact: recommendedFresh.source === "org"
+    } : null;
+    const total = refreshed.length;
+    const additional = recommendedFresh ? Math.max(0, total - 1) : total;
+    const enrichmentComplete = Boolean(recommendedContact && (recommendedContact.email || recommendedContact.phone_number));
     return {
-      lead: leadSummary,
-      recommended_contact: recommended ? {
-        id: recommended.id,
-        name: [recommended.first_name, recommended.last_name].filter(Boolean).join(" "),
-        job_title: recommended.job_title,
-        email: recommended.email,
-        phone_number: recommended.phone_number,
-        linkedin_page: recommended.linkedin_page
-      } : null,
-      other_contacts_count: Math.max(0, contacts.length - 1),
+      lead: leadBlock,
+      recommended_contact: recommendedContact,
+      additional_contacts_count: additional,
+      total_contacts_count: total,
+      // Deprecated alias kept for one release.
+      other_contacts_count: additional,
       enrichment: {
         triggered: enrichmentTriggered,
+        complete: enrichmentComplete,
         error: enrichmentError,
-        hint: enrichmentTriggered ? "Enrichment started. Poll leadbay_get_contacts with the same leadId in ~60 seconds." : null
+        hint: enrichmentTriggered && !enrichmentComplete ? "Enrichment running (~60s). Re-call leadbay_prepare_outreach with the same leadId (no enrich) and check enrichment.complete." : null
       }
     };
   }
 };
 
 // ../core/dist/composite/pull-leads.js
+function normalizeLinkedinPage3(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
 function summarise(responses) {
   const answered = responses.filter((r) => r.score != null).length;
   const total = responses.length;
@@ -4514,18 +5383,29 @@ var pullLeads = {
       }
     }));
     const summaryMap = new Map(summaries.map((s) => [s.leadId, s.summary]));
-    const trimmed = (lead) => verbose ? lead : {
+    const augmentContact2 = (c) => c ? {
+      ...c,
+      linkedin_page: normalizeLinkedinPage3(c.linkedin_page ?? null)
+    } : null;
+    const trimmed = (lead) => verbose ? {
+      ...lead,
+      recommended_contact: augmentContact2(lead.recommended_contact)
+    } : {
       id: lead.id,
       name: lead.name,
       score: lead.score,
       ai_agent_lead_score: lead.ai_agent_lead_score,
+      ai_summary: lead.ai_summary ?? null,
+      split_ai_summary: lead.split_ai_summary ?? null,
       location: lead.location,
       short_description: lead.short_description ?? lead.description,
       size: lead.size,
       website: lead.website,
+      phone_numbers: lead.phone_numbers ?? null,
       tags: lead.tags,
-      recommended_contact_title: lead.recommended_contact_title ?? null,
-      recommended_contact: lead.recommended_contact ?? null,
+      social_presence: lead.social_presence ?? null,
+      social_urls: lead.social_urls ?? null,
+      recommended_contact: augmentContact2(lead.recommended_contact),
       web_fetch_in_progress: lead.web_fetch_in_progress ?? false,
       enrichment_in_progress: lead.enrichment_in_progress ?? false,
       liked: lead.liked,
@@ -4560,7 +5440,182 @@ var pullLeads = {
   }
 };
 
+// ../core/dist/composite/pull-followups.js
+function normalizeLinkedinPage4(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
+function augmentContact(c) {
+  if (!c)
+    return null;
+  return {
+    ...c,
+    linkedin_page: normalizeLinkedinPage4(c.linkedin_page ?? null)
+  };
+}
+var pullFollowups = {
+  name: "leadbay_pull_followups",
+  annotations: {
+    title: "Pull known leads to follow up on (Monitor view)",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_pull_followups,
+  inputSchema: {
+    type: "object",
+    properties: {
+      filtered: {
+        type: "boolean",
+        description: "Apply the user's stored Monitor filter (server-persisted via POST /monitor/filter). Default true."
+      },
+      personal: {
+        type: "boolean",
+        description: "When true, restrict to leads this user has personally monitored (not org-wide). Default false."
+      },
+      liked: {
+        type: "boolean",
+        description: "When true, restrict to leads the user has explicitly liked. Default false."
+      },
+      count: {
+        type: "number",
+        description: "Leads per page, max 200 (default 20)."
+      },
+      page: {
+        type: "number",
+        description: "Page number, 0-indexed (default 0)."
+      },
+      set_filter: {
+        type: "object",
+        description: "Optional FilterItem ({criteria: FilterCriterion[]}). When provided, the composite POSTs it to /monitor/filter (server-persists across sessions) BEFORE fetching the filtered Monitor view. Use to refine 'leads to follow up' by city, sector, recency, action type, etc.",
+        properties: {
+          criteria: {
+            type: "array",
+            description: "Array of FilterCriterion objects per the backend FilterCriterion anyOf schema (location_ids, sector_ids, size, keywords, last_action, last_action_date, liked, yc, custom_field, custom_field_comparison).",
+            items: { type: "object" }
+          }
+        }
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      active_filters: {
+        type: ["object", "null"],
+        description: "The FilterItem currently stored server-side for this user (via GET /monitor/filter). null when no filter is set or when filtered:false was passed."
+      },
+      leads: {
+        type: "array",
+        description: "The page of monitored leads. Each lead carries the FullLead shape augmented with normalized linkedin_page on contacts and `recommended_contact`.",
+        items: { type: "object" }
+      },
+      pagination: {
+        type: ["object", "null"],
+        description: "page / pages / total \u2014 the backend's pagination envelope when present."
+      },
+      total_excluded_by_pushback: {
+        type: "number",
+        description: "Composite-derived count of leads in the page that were excluded because their `pushback_status` is active. The backend may or may not pre-filter; this exposes the count when the composite has to drop them itself."
+      },
+      _meta: {
+        type: "object",
+        description: "Operator context: region + last-call latency.",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["leads"]
+  },
+  execute: async (client, params, ctx) => {
+    const filtered = params.filtered ?? true;
+    const personal = params.personal ?? false;
+    const liked = params.liked ?? false;
+    const page = params.page ?? 0;
+    const count = Math.min(params.count ?? 20, 200);
+    if (params.set_filter) {
+      try {
+        await client.requestVoid("POST", "/monitor/filter", params.set_filter);
+      } catch (err) {
+        ctx?.logger?.warn?.(`pull_followups: POST /monitor/filter failed: ${err?.message ?? err?.code ?? err}`);
+      }
+    }
+    const qs = new URLSearchParams({
+      personal: String(personal),
+      liked: String(liked),
+      filtered: String(filtered),
+      count: String(count),
+      page: String(page)
+    }).toString();
+    const [filterR, monitorR] = await Promise.allSettled([
+      filtered ? client.request("GET", "/monitor/filter") : Promise.resolve(null),
+      client.request("GET", `/monitor?${qs}`)
+    ]);
+    const activeFilter = filterR.status === "fulfilled" ? filterR.value ?? null : null;
+    if (monitorR.status === "rejected") {
+      throw monitorR.reason;
+    }
+    const monitor = monitorR.value ?? {};
+    const rawLeads = Array.isArray(monitor.items) ? monitor.items : Array.isArray(monitor.leads) ? monitor.leads : Array.isArray(monitor) ? monitor : [];
+    const now = Date.now();
+    const isActivePushback = (lead) => {
+      const status = lead?.pushback_status;
+      if (!status)
+        return false;
+      const until = lead?.pushback_until ?? lead?.pushback_status_set_at;
+      if (!until)
+        return true;
+      const ts = Date.parse(until);
+      if (Number.isNaN(ts))
+        return true;
+      return ts > now;
+    };
+    let excluded = 0;
+    const leads = rawLeads.filter((lead) => {
+      if (isActivePushback(lead)) {
+        excluded += 1;
+        return false;
+      }
+      return true;
+    }).map((lead) => ({
+      ...lead,
+      recommended_contact: augmentContact(lead.recommended_contact),
+      org_contacts: Array.isArray(lead.org_contacts) ? lead.org_contacts.map(augmentContact) : lead.org_contacts ?? null
+    }));
+    return {
+      active_filters: activeFilter,
+      leads,
+      pagination: monitor.pagination ?? null,
+      total_excluded_by_pushback: excluded,
+      _meta: {
+        region: client.region,
+        latency_ms: client.lastMeta?.latency_ms ?? null
+      }
+    };
+  }
+};
+
 // ../core/dist/composite/research-lead.js
+function normalizeLinkedinPage5(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
 function renderResearchLeadMarkdown(shape) {
   const out = [];
   const firm = shape.firmographics ?? {};
@@ -4737,22 +5792,96 @@ var researchLead = {
       },
       firmographics: {
         type: "object",
-        description: "Lead profile basics. iter-30: nested additionalProperties:false closes the output-side strictness frontier \u2014 runtime returns must match exactly these keys.",
+        description: "Lead profile basics. The shapes here match the backend `LeadSimplified` schema verbatim \u2014 `size` is `{min,max,...}`, `location` is `{city,state,country,full,pos}`, `tags` are typed objects.",
         properties: {
           id: { type: "string" },
           name: { type: "string" },
           sector_id: { type: ["number", "string", "null"] },
-          size: { type: ["string", "null"] },
-          location: { type: ["string", "null"] },
+          size: {
+            type: ["object", "null"],
+            description: "LeadSimplified.size \u2014 employee-count band.",
+            properties: {
+              low: { type: ["number", "null"] },
+              high: { type: ["number", "null"] },
+              min: { type: ["number", "null"] },
+              max: { type: ["number", "null"] },
+              label: { type: ["string", "null"] }
+            }
+          },
+          location: {
+            type: ["object", "null"],
+            description: "LeadFullLocation \u2014 city/state/country/full/pos.",
+            properties: {
+              city: { type: ["string", "null"] },
+              state: { type: ["string", "null"] },
+              country: { type: ["string", "null"] },
+              full: { type: ["string", "null"] },
+              pos: {
+                type: ["array", "null"],
+                items: { type: "number" }
+              }
+            }
+          },
           website: { type: ["string", "null"] },
           description: { type: ["string", "null"] },
           short_description: { type: ["string", "null"] },
-          keywords: { type: "array", items: { type: "string" } },
-          tags: { type: "array", items: { type: "string" } },
+          keywords: {
+            type: "array",
+            description: "Either bare strings (legacy) or {keyword,score} objects depending on the backend payload version.",
+            items: {}
+          },
+          tags: {
+            type: "array",
+            description: "LeadTag[] \u2014 {id, display_name, tag, score}.",
+            items: {
+              type: "object",
+              properties: {
+                id: { type: ["number", "string", "null"] },
+                display_name: { type: ["string", "null"] },
+                tag: { type: "string" },
+                score: { type: ["number", "null"] }
+              }
+            }
+          },
           score: { type: ["number", "null"] },
           ai_agent_lead_score: { type: ["number", "null"] },
-          social_presence: { type: ["object", "string", "null"] },
-          social_urls: { type: ["object", "array", "null"] },
+          ai_summary: { type: ["string", "null"] },
+          split_ai_summary: {
+            type: ["object", "null"],
+            properties: {
+              worth_pursuing: { type: ["string", "null"] },
+              approach_angle: { type: ["string", "null"] },
+              next_step: { type: ["string", "null"] }
+            }
+          },
+          phone_numbers: {
+            type: ["array", "null"],
+            items: { type: "string" }
+          },
+          social_presence: {
+            type: ["object", "null"],
+            description: "LeadSocialPresence \u2014 6 booleans per platform. Use `social_urls` for URLs.",
+            properties: {
+              crunchbase: { type: "boolean" },
+              facebook: { type: "boolean" },
+              instagram: { type: "boolean" },
+              linkedin: { type: "boolean" },
+              tiktok: { type: "boolean" },
+              twitter: { type: "boolean" }
+            }
+          },
+          social_urls: {
+            type: ["object", "null"],
+            description: "LeadSocialUrls \u2014 URL strings per platform; null when the company has no profile.",
+            properties: {
+              crunchbase: { type: ["string", "null"] },
+              facebook: { type: ["string", "null"] },
+              instagram: { type: ["string", "null"] },
+              linkedin: { type: ["string", "null"] },
+              tiktok: { type: ["string", "null"] },
+              twitter: { type: ["string", "null"] }
+            }
+          },
           registry_ids: { type: ["object", "array", "null"] }
         },
         additionalProperties: false
@@ -4773,7 +5902,6 @@ var researchLead = {
           liked: { type: "boolean" },
           disliked: { type: "boolean" },
           new: { type: "boolean" },
-          recommended_contact_title: { type: ["string", "null"] },
           recommended_contact: { type: ["object", "null"] },
           notes_count: { type: "number" },
           epilogue_actions_count: { type: "number" },
@@ -4894,11 +6022,16 @@ var researchLead = {
         tags: lead.tags,
         score: lead.score,
         ai_agent_lead_score: lead.ai_agent_lead_score,
+        ai_summary: lead.ai_summary ?? null,
+        split_ai_summary: lead.split_ai_summary ?? null,
+        phone_numbers: lead.phone_numbers ?? null,
         social_presence: lead.social_presence ?? null,
         social_urls: lead.social_urls ?? null,
         registry_ids: lead.registry_ids ?? null
       },
       // 4) contacts (paid/enriched, plus org contacts if present)
+      // B6: defensively coerce the literal string "null" to a real null —
+      // some backend serializers emit it for un-enriched contacts.
       contacts: {
         enriched: paidContacts.map((c) => ({
           id: c.id,
@@ -4907,7 +6040,7 @@ var researchLead = {
           job_title: c.job_title,
           email: c.email,
           phone_number: c.phone_number,
-          linkedin_page: c.linkedin_page,
+          linkedin_page: normalizeLinkedinPage5(c.linkedin_page),
           recommended: c.recommended,
           enrichment_done: c.enrichment?.done ?? false
         })),
@@ -4916,16 +6049,22 @@ var researchLead = {
           first_name: c.first_name,
           last_name: c.last_name,
           job_title: c.job_title,
-          email: c.email
+          email: c.email,
+          linkedin_page: normalizeLinkedinPage5(c.linkedin_page ?? null)
         }))
       },
-      // 5) engagement — what humans/prior agent runs already did
+      // 5) engagement — what humans/prior agent runs already did.
+      // B8: `recommended_contact_title` dropped — it duplicates
+      // `recommended_contact.job_title` and just confused agents.
       engagement: {
         liked: lead.liked,
         disliked: lead.disliked,
         new: lead.new ?? false,
-        recommended_contact_title: lead.recommended_contact_title ?? null,
-        recommended_contact: lead.recommended_contact ?? null,
+        recommended_contact: lead.recommended_contact ? {
+          ...lead.recommended_contact,
+          // B1+B7: propagate linkedin_page when the backend includes it.
+          linkedin_page: normalizeLinkedinPage5(lead.recommended_contact.linkedin_page ?? null)
+        } : null,
         notes_count: lead.notes_count ?? 0,
         epilogue_actions_count: lead.epilogue_actions_count ?? 0,
         prospecting_actions_count: lead.prospecting_actions_count ?? 0,
@@ -8921,6 +10060,8 @@ var granularWriteTools = [
   dismissClarification,
   setEpilogueStatus,
   removeEpilogue,
+  setPushback,
+  removePushback,
   previewBulkEnrichment,
   launchBulkEnrichment,
   createCustomField
@@ -8935,6 +10076,7 @@ granularTools.forEach((t) => {
 });
 var compositeReadTools = [
   pullLeads,
+  pullFollowups,
   researchLead,
   recallOrderedTitles,
   accountStatus,
@@ -9019,12 +10161,15 @@ export {
   dismissClarification,
   setEpilogueStatus,
   removeEpilogue,
+  setPushback,
+  removePushback,
   previewBulkEnrichment,
   launchBulkEnrichment,
   createCustomField,
   researchCompany,
   prepareOutreach,
   pullLeads,
+  pullFollowups,
   researchLead,
   recallOrderedTitles,
   accountStatus,