@leadbay/mcp 0.9.1 → 0.10.0

package/dist/{chunk-ZRTAIXEJ.js → chunk-F3EWCHME.js}

@@ -414,7 +414,21 @@ var LeadbayClient = class {
       return this.makeError("AUTH_EXPIRED", "Authentication token expired or invalid", "Your LEADBAY_TOKEN is no longer valid. Regenerate it: npx -y @leadbay/mcp login --email <you> --region <us|fr>, then restart your MCP client.", endpoint);
     }
     if (status === 429 || status === 402 || parsed?.error === "quota_exceeded" || parsed?.error?.code === "quota_exceeded") {
-      return this.makeError("QUOTA_EXCEEDED", retryAfter ? `Quota exceeded \u2014 retry in ${retryAfter}s` : "Quota exceeded", retryAfter ? `Wait ${retryAfter}s before retrying. Check leadbay_get_quota to see which resource window was hit.` : "Wait, then retry. Check leadbay_get_quota to see which resource window (daily/weekly/monthly) was hit.", endpoint, retryAfter);
+      const hintBase = retryAfter ? `Wait ${retryAfter}s before retrying` : "Wait, then retry";
+      return this.makeError(
+        "QUOTA_EXCEEDED",
+        retryAfter ? `Quota exceeded \u2014 retry in ${retryAfter}s` : "Quota exceeded",
+        // The Leadbay user can either wait for the window to reset OR top up
+        // AI credits (which clears the throttle immediately). Tell the agent
+        // both options exist so it offers the top-up path to the user instead
+        // of forcing them to wait. Surface leadbay_create_topup_link so the
+        // agent can generate the URL itself instead of asking the user to
+        // navigate to a website. Once the user has topped up, the previous
+        // 429 is stale — retry the failed call.
+        `${hintBase}, OR top up AI credits \u2014 top-ups clear the throttle immediately. Offer the user to generate a Stripe checkout URL via leadbay_create_topup_link, OR direct them to app.leadbay.ai \u2192 Billing. Check leadbay_account_status / leadbay_get_quota to see which resource window (daily/weekly/monthly) was hit. Once the user has topped up, the previous QUOTA_EXCEEDED is stale \u2014 re-call leadbay_account_status to refresh, then RETRY the original operation.`,
+        endpoint,
+        retryAfter
+      );
     }
     if (status === 403) {
       const msg = parsed?.message || parsed?.error || parsed?.error?.message || "";
@@ -533,11 +547,44 @@ function parseRetryAfter(value) {
 }
 
 // ../core/dist/tool-descriptions.generated.js
-var leadbay_account_status = `Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption.
+var leadbay_account_status = `## WHEN TO USE
 
-WHEN TO USE: at the start of a session to know what the agent can/can't do, or after a 429 to explain to the user which resource window was exhausted and when it resets.
+Trigger phrases: "what's my account status", "how much quota do I have", "what lens am I on", "am I an admin", "is intelligence still regenerating", "I topped up / I bought credits / I added credits".
 
-WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating.
+Do NOT use for: "show me leads / today's prospects" \u2192 \`leadbay_pull_leads\`.
+
+Prefer when: user opens with a meta question about themselves / their workspace \u2014 typically as a daily check-in opener
+
+Examples that SHOULD invoke this tool:
+- "What's my account status?"
+- "How much quota do I have left this week?"
+- "Is my intelligence still regenerating?"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me today's leads."
+- "What should I follow up on?"
+- "Run the daily check-in."
+
+## RENDER (quick)
+
+Compact markdown: org name + admin badge on line 1; active lens on
+line 2; per-window quota usage as \`(used / cap)\` chips for
+llm_completion \xB7 ai_rescore \xB7 web_fetch. Surface regeneration flag
+prominently if mid-regen.
+
+---
+
+Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption.
+
+**Top-ups always beat waiting.** When a quota window is hit, the user has two options: wait for the window reset (\`resets_at\` in each quota entry) OR top up AI credits. Top-ups clear the throttle IMMEDIATELY; they are not subject to the same window. When you tell the user about a 429 / quota exhaustion, ALWAYS surface both options \u2014 "wait until <reset>" or "top up now (I can generate the link)" \u2014 and let them pick. Never default-recommend "wait until tomorrow" when a 30-second top-up unblocks the same operation.
+
+**Offer the top-up link via \`leadbay_create_topup_link\`.** When the user accepts the top-up offer, call \`leadbay_create_topup_link\` and surface the returned Stripe checkout URL as a clickable link. The user completes payment in their browser; nothing is charged just by generating the URL. For ongoing subscription changes (plan upgrade / payment method), use \`leadbay_open_billing_portal\` instead.
+
+**After a user tops up, do NOT keep refusing \u2014 RETRY.** If the user signals they topped up / bought credits / added credits, the previous QUOTA_EXCEEDED is invalidated the moment the Stripe webhook lands. RE-CALL \`leadbay_account_status\` to pick up the new state AND retry the originally failed call. The retry itself does not require a successful account_status check first \u2014 a topped-up user has cleared the throttle whether or not your cached snapshot reflects it yet. If the retry hits the wall again, only then re-offer top-up / wait. **A stale quota snapshot is never a reason to gate-keep a topped-up user.**
+
+WHEN TO USE: at the start of a session to know what the agent can/can't do, after a 429 to explain to the user which resource window was exhausted and when it resets (and to offer the top-up alternative), and after the user signals a top-up so the agent can resume the interrupted workflow.
+
+WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating. And: a recent quota snapshot showing "exhausted" is NOT a reason to refuse a write call when the user has just topped up \u2014 re-call this tool first, then proceed.
 `;
 var leadbay_add_note = `Add a note to a lead. Notes are visible to the whole organization in Leadbay.
 
@@ -567,7 +614,7 @@ var leadbay_bulk_enrich_status = `Check status + per-lead contacts for a bulk en
 
 WHEN TO USE: poll this after leadbay_enrich_titles returns a \`bulk_id\`. Default \`include_contacts=false\` for cheap status polls; set \`include_contacts=true\` once \`all_done\` flips for the final read.
 
-WHEN NOT TO USE: as a substitute for leadbay_research_lead \u2014 that already includes enriched contacts for a single lead.
+WHEN NOT TO USE: as a substitute for leadbay_research_lead_by_id \u2014 that already includes enriched contacts for a single lead.
 `;
 var leadbay_bulk_qualify_leads = `Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch). Pass \`wait_for_completion:false\` to return quickly with \`{status:'running', qualify_id}\`; poll leadbay_qualify_status with that id. With \`wait_for_completion\` omitted/true, the legacy behavior polls until the answers are populated or a budget is exhausted. Already-qualified leads (those with a non-null \`ai_agent_lead_score\`) are silently no-ops on the backend, so this composite paginates past them to find fresh candidates. On 429 mid-fanout, stops launching but keeps polling already-launched leads.
 
@@ -611,6 +658,32 @@ Do not enumerate the affected leads \u2014 that's the job of \`leadbay_pull_lead
 
 ## NEXT STEPS \u2014 after kicking off bulk qualification
 
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
 Exactly two offers \u2014 keep it terse, this is a status tool:
 
 | Observation                          | Suggest                                       | Calls                          |
@@ -658,6 +731,23 @@ WHEN NOT TO USE: from agent flow \u2014 leadbay_adjust_audience handles the draf
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_create_topup_link = `Generate a one-shot Stripe checkout session for an AI-credits top-up. Wraps \`POST /1.5/stripe/topup_checkout\` \u2192 \`{url}\`. Returns a fresh Stripe-hosted URL (~1 hour TTL); creating one does NOT charge the user \u2014 payment happens only after the user opens the URL and completes checkout in their browser.
+
+**When a quota window is hit, offer top-up as the FIRST option.** A top-up clears the throttle immediately (no need to wait for the daily/weekly/monthly window reset). The flow:
+
+1. Operation returns QUOTA_EXCEEDED / 429.
+2. Tell the user which window was hit (from \`leadbay_account_status\` / \`leadbay_get_quota\`) and offer BOTH options: "wait until \`<resets_at>\`" OR "top up at app.leadbay.ai (I can generate the link)".
+3. If the user accepts top-up, call \`leadbay_create_topup_link\` and surface the returned \`url\` as a clickable link.
+4. Tell the user to complete checkout in their browser. After they return saying "I topped up" / "bought credits" / "added credits", call \`leadbay_account_status\` to confirm the refreshed state, then RETRY the originally failed call.
+
+Do NOT call this tool defensively before any quota error \u2014 only after a real 429 or in response to the user's explicit "I want to top up" / "I'll buy credits". The URL is single-use and rotating it without the user asking just clutters the conversation.
+
+\`leadbay_open_billing_portal\` is the companion tool for ongoing subscription management (upgrade / downgrade / payment methods) via the Stripe customer portal.
+
+WHEN TO USE: when a quota error has blocked the user's intent and they want to keep working today rather than wait for the window reset; OR when the user explicitly asks for a top-up link.
+
+WHEN NOT TO USE: pre-flight (the agent is not paying \u2014 the user is); for subscription / plan changes use \`leadbay_open_billing_portal\` instead; for read-only quota diagnostics use \`leadbay_account_status\` / \`leadbay_get_quota\`.
+`;
 var leadbay_deselect_leads = `Remove leads from the user's transient selection.
 
 WHEN TO USE: when narrowing a previously-built selection without clearing it entirely.
@@ -672,6 +762,44 @@ WHEN TO USE: low-level \u2014 when you need raw paginated wishlist access withou
 
 WHEN NOT TO USE: as the agent's default lead-discovery entry point \u2014 use leadbay_pull_leads, which adds a one-line qualification summary per lead.
 `;
+var leadbay_dislike_lead = `## WHEN TO USE
+
+Trigger phrases: "I don't like this lead", "thumbs down", "not relevant", "wrong industry", "too small", "skip this one permanently", "not a fit", "no to this one".
+
+Do NOT use for: "remind me about this lead later / snooze it / not now" \u2192 \`leadbay_set_pushback\`; "thumbs up / save this one / this is a good fit" \u2192 \`leadbay_like_lead\`.
+
+Prefer when: user expresses durable rejection of a specific lead; pass the lead's UUID as \`lead_id\`. If the user just wants to defer for now, route to \`leadbay_set_pushback\` instead.
+
+Examples that SHOULD invoke this tool:
+- "Thumbs down \u2014 wrong industry."
+- "Dislike this one, never show me leads like this again."
+- "Not a fit at all, remove it."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Skip this for now, ask me again next month."
+- "I'll look at this one later."
+- "I like this lead \u2014 save it."
+
+## RENDER (quick)
+
+One short confirmation line after the call returns ("\u{1F44E} Disliked **{company_name}** \u2014
+negative signal sent."), then continue the current flow (don't dump the full
+lead card again).
+
+---
+
+Mark a lead as disliked. This is the same action as clicking the thumbs-down on the Leadbay website. The signal is fed back into the scoring engine: disliked leads teach Leadbay what to filter out, improving the relevance of future batches.
+
+Pass the lead's UUID as \`lead_id\`.
+
+Dislike is a **permanent** negative signal \u2014 it influences scoring durably. If the user only wants to defer a lead ("not now", "remind me next month", "I'll look at this one later"), call \`leadbay_set_pushback\` instead; that's reversible and time-bounded.
+
+WHEN TO USE: the user explicitly rejects a lead ("not relevant", "wrong industry", "too small", "thumbs down", "skip this", "not a fit"). Use proactively after \`leadbay_research_lead\` reveals disqualifying signals.
+
+WHEN NOT TO USE: the user simply wants to defer a lead \u2014 use \`leadbay_set_pushback\` to snooze instead. Dislike is a permanent negative signal; pushback is a temporary deferral.
+
+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_dismiss_clarification = `Dismiss the pending clarification without answering. Leadbay proceeds with its best guess. Admin-only.
 
 WHEN TO USE: when the user explicitly doesn't want to answer the disambiguation.
@@ -696,6 +824,172 @@ WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contact
 
 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_followups_map = `## WHEN TO USE
+
+Trigger phrases: "I'm going to <city>", "this week's trip", "leads I should visit in person", "visit in person", "show me followups in <city / state / country>", "leads in Texas / California / France / Bavaria etc.", "leads near <city>", "map of leads", "show me on a map", "itinerary", "plan my itinerary", "trip itinerary", "where are my leads".
+
+Do NOT use for: "default follow-up table / status view" \u2192 \`leadbay_pull_followups\`; "new leads / today's prospects" \u2192 \`leadbay_pull_leads\`.
+
+Prefer when: user signals geographic / map-style intent \u2014 even a passive 'before my trip' mention counts
+
+Examples that SHOULD invoke this tool:
+- "I'm flying to New York Thursday \u2014 who should I meet in person?"
+- "Show my leads on a map for the SF trip."
+- "Who can I visit while I'm in Chicago next week?"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "What should I follow up on this week?"
+- "Show me today's new prospects."
+- "Tell me about Acme Corp."
+
+## RENDER (quick)
+
+Two render surfaces \u2014 host picks. Primary: route to Claude's
+\`places_map_display_v0\` widget with \`{name, address (lead.location.full),
+latitude+longitude (lead.location.pos[0/1]), notes (short prose with
+bare phone+email)}\` per lead. Fallback: per-lead markdown blocks
+\`### **Company** \xB7 City, ST\` + one-sentence note + bare phone/email
+\u2014 chat hosts auto-detect into place-card carousel. Detail below.
+
+---
+
+Plot the user's follow-up leads on an interactive map \u2014 the canonical surface for travel / in-person / "I'm going to <city>" intent. Wraps \`leadbay_pull_followups\` (same params, response, store-then-apply geo filter); named separately so the agent has an explicit entry-point for travel intent and can route to \`places_map_display_v0\` (when the host exposes it) or emit place-card prose blocks (which most chat hosts auto-detect into Google Place cards).
+
+**Common city aliases resolve automatically** \u2014 \`NYC\` / \`New York\` \u2192 City of New York, \`SF\` / \`S.F.\` \u2192 San Francisco, \`LA\` / \`L.A.\` \u2192 Los Angeles, \`DC\` / \`Washington D.C.\` \u2192 Washington, \`Philly\` \u2192 Philadelphia, \`Vegas\` \u2192 Las Vegas, \`NOLA\` \u2192 New Orleans. Pass either an abbreviation, a city name, or a pre-resolved \`city_id\`. Ambiguous matches surface as \`status: "ambiguous_locations"\` + \`location_ambiguities[]\` \u2014 pick an id and re-call with \`city_id\`.
+
+**\`city\` is the universal geo arg \u2014 it resolves any admin level.** Despite the name, pass any place name there: states (\`"Texas"\`, \`"California"\`, \`"Bavaria"\`), countries (\`"France"\`, \`"United States"\`), regions (\`"New England"\`, \`"Bay Area"\`), neighborhoods (\`"Brooklyn"\`, \`"SoHo"\`), or cities. The \`/geo/search\` resolver indexes all levels \u2014 level 4 (state), level 2 (country), level 5 (city) \u2014 and the composite picks the best match. **Never** put a place name into \`keywords\` instead \u2014 that's a text-match against company descriptions, not a real geo filter (e.g. \`keywords: ["Texas"]\` returns \u22480 hits even when the user has dozens of Texas leads). If \`keywords: ["<PlaceName>"]\` returned empty, the correct next call is \`city: "<PlaceName>"\`, NOT the unfiltered Monitor view.
+
+---
+
+## RENDER \u2014 host-native map widget (REQUIRED, preferred)
+
+When the host exposes Claude's \`places_map_display_v0\`, route the leads there. It owns the visual surface (markers, place-card carousel, "Notes from Claude") and beats inline prose by miles.
+
+**Call shape \u2014 pass the most precise data you have. The richer the address + coordinates, the more likely Google resolves a real business listing and shows structured property pills (phone, website, Directions button, rating) on each card. Cheap city-level data => basic pin + your notes string only.**
+
+\`\`\`
+places_map_display_v0({
+  locations: leads.map(l => ({
+    name: l.company_name ?? l.name,
+    // \u2605 REQUIRED \u2014 pos is [lat, lng] in our payload. Pass them split.
+    latitude:  l.location.pos[0],
+    longitude: l.location.pos[1],
+    // \u2605 Pass the FULL detailed address from l.location.full
+    //   ("1140, 6th Avenue, 10036, City of New York, New York, United States"),
+    //   NOT a city-level fallback. Google's place lookup needs the street
+    //   + ZIP to resolve a business listing \u2192 that's what unlocks the
+    //   structured phone/website/rating pills on the card.
+    address: l.location.full ?? [l.location.city, l.location.state, l.location.country].filter(Boolean).join(", "),
+    notes: <one-sentence pitch \u2014 see notes recipe below>,
+    // place_id omitted \u2014 Leadbay's backend doesn't store Google Place
+    // IDs. Google resolves implicitly from name + lat/lng + address.
+    // If it doesn't find a listing (small B2B, no Google business page),
+    // the card falls back to your notes string only \u2014 that's why the
+    // notes string MUST be self-sufficient (phone + email inline).
+  })),
+  // travel_mode: "driving" if the user mentioned driving / trip, etc.
+})
+\`\`\`
+
+Skip any lead whose \`location.pos\` is null \u2014 without lat/lng the widget can't pin it. (Surface them as a "+ N leads without coordinates" footer below the widget instead.)
+
+**Notes recipe for each lead** \u2014 "Notes from Claude" on the place card.
+
+CRITICAL REALITY OF THE CAROUSEL: it renders the notes string as **a single wrapped paragraph of plain text**. The carousel renderer:
+- STRIPS markdown \u2014 \`[Name](url)\` shows as literal "Name (url)" with the URL visible mid-text;
+- COLLAPSES newlines \u2014 vertical stacking does NOT work;
+- TRUNCATES long URLs mid-string visibly;
+- DOES auto-linkify bare phone numbers (\`+1 212-555-0100\` \u2192 tappable \`tel:\`) and bare email addresses (\`name@company.com\` \u2192 tappable \`mailto:\`) \u2014 those become the only "properties" the user can act on inside the card.
+
+So the notes string MUST be short prose with bare-text channels only. Use exactly this shape (one sentence, \u2264 ~30 words):
+
+\`\`\`
+\u2605 <One-sentence sector/fit + why-now>. Reach <Contact First Last>, <role>: <bare phone>, <bare email>.
+\`\`\`
+
+Examples:
+- \`\u2605 Strongest fit \u2014 active thread, 'trying to reach' from last Friday. Reach Troy Schirk, Principal & CIO: +1 312-550-2382, tschirk@atlasholdingsllc.com.\`
+- \`\u2605 Mid-size HR/staffing match, multi-branch pattern. Reach Irving Enciso, Regional Ops Manager: 952-835-1288, info@employersolutionsgroup.com.\`
+
+Rules:
+- ONE sentence. No newlines. No emoji prefixes (\`\u{1F464}\u{1F4DE}\u2709\uFE0F\u{1F310}\` add clutter but do NOT create sections \u2014 the carousel ignores layout).
+- NO markdown links anywhere in \`notes\`. Especially no LinkedIn URLs \u2014 they're long, they mid-truncate visibly, and the carousel renders them as raw text. Save LinkedIn for the chat prose below the widget.
+- Phone + email inline as bare text. They auto-linkify; that's the user's tap target inside the card.
+- Score callout (\`\u2605 Strongest fit\`, \`Score 83\`, etc.) uses \`ai_agent_lead_score\` when present, else \`score\`.
+- Omit channels that aren't enriched yet \u2014 don't write "<no phone>".
+
+## Chat prose AFTER the widget (where markdown DOES render)
+
+The carousel is the spatial visual. The user still wants the rich contact detail somewhere \u2014 but the right surface for that is the **chat message after invoking the widget**, not the notes inside it. Chat renders markdown links, lists, emoji properly.
+
+Below the widget invocation, emit a short structured summary like:
+
+\`\`\`
+**Atlas Holdings \u2014 Far Rockaway.** \u2605 Strongest fit. Active thread, "trying to reach" status from last Friday; AI angle is fresh (recent strategic investment signal).
+Contact: **[Troy Schirk](<linkedin_page or constructed search URL>)**, Principal & CIO \xB7 \u260E +1 312-550-2382 \xB7 \u2709 tschirk@atlasholdingsllc.com
+
+**Employer Solutions Services \u2014 Midtown.** \u2605 Mid-size HR/staffing match. Same address as the staffing-group sibling \u2014 single visit covers both.
+Contact: **[Irving Enciso](<linkedin URL>)**, Regional Operations Manager \xB7 \u260E 952-835-1288 \xB7 \u2709 info@employersolutionsgroup.com
+\`\`\`
+
+Keep it short \u2014 1 lead per ~3 lines, top 3\u20135 most relevant. The LinkedIn-linked contact name lives here (chat markdown works), the channels are listed as \` \xB7 \`-separated pills. **Do NOT enumerate the same leads as a markdown table** \u2014 this list-form summary is the chat-side detail surface.
+
+**LinkedIn URL priority** (used in the chat prose, not in carousel notes):
+1. \`recommended_contact.linkedin_page\` when set, not the literal \`"null"\`, starts with \`https://\`;
+2. Constructed search: \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\` with the company name stripped of \`Inc / LLC / Corp / GmbH / Ltd / Co / S.A. / S.L. / PLC / AG / SAS / SARL\` suffixes, URL-encoded. Append a trailing \` \xB0\` to the contact name to mark the fallback path.
+
+Open with **one short intro sentence** in chat ("Five lead visits across NYC for your trip next week \u2014 three in Midtown, plus Long Island and one in NJ.") and then invoke the widget, then the chat-side list above. **No markdown table.**
+
+**After the widget renders, end the turn with the NEXT STEPS surface** \u2014 not with a prose question. See "GATE \u2014 PREFER BUILT-IN HOST WIDGETS" below: surface 2\u20134 mutually-exclusive moves via \`ask_user_input_v0\` if the host exposes it, else as a short bulleted list. "Want me to plot these on a map or jump to outreach for Atlas?" is exactly the prose pattern to AVOID \u2014 it's a \`single_select\` with two options.
+
+## RENDER \u2014 fallback for hosts without \`places_map_display_v0\`
+
+If the host doesn't expose the native map, emit per-lead markdown blocks in this **exact** format \u2014 modern chat hosts (Claude.ai web, cowork) auto-detect addresses + company names and render them as a Google-Place-card carousel anyway:
+
+\`\`\`
+### **<Company Name>** \xB7 <City>, <State or Country>
+
+\u2605 <Score callout>. <One-sentence sector fit + why-now>.
+
+\u{1F464} [<Contact First Last>](<LinkedIn URL>) \u2014 <role>
+\u{1F4DE} <bare phone>
+\u2709\uFE0F <bare email>
+\u{1F310} <company website>
+\`\`\`
+
+Same one-channel-per-line discipline \u2014 newlines between channels so the carousel renders them as scannable properties (vs a wall of prose). Same auto-linkify rules: bare phone, bare email, markdown-wrapped contact name.
+
+The response payload carries everything you need: \`lead.company_name\` (or \`name\`), \`lead.location.city / country / full / pos\`, \`lead.score\`, \`lead.ai_agent_lead_score\`, \`lead.recommended_contact.{first_name, last_name, job_title, linkedin_page, email, phone_number}\`, \`lead.phone_numbers[]\`, \`lead.website\`, \`lead.short_description\`, \`lead.last_monitor_action\` + \`last_monitor_action_at\`. Score callout uses \`ai_agent_lead_score\` when present, else \`score\`.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
+---
+
+WHEN TO USE: the user mentions travel, in-person follow-up, "this week's trip", "visiting", "I'm going to", or any phrasing that benefits from a geographic view of pipeline. Also when the user explicitly asks for a map.
+
+WHEN NOT TO USE: for the default follow-up table (status badges, AI take, history) \u2014 that's \`leadbay_pull_followups\`. For NEW leads from the Discover wishlist \u2014 that's \`leadbay_pull_leads\`.
+
+The response shape is identical to \`leadbay_pull_followups\`: \`{leads, active_filters, pagination, total_excluded_by_pushback, _meta}\` on success; \`{status: "ambiguous_locations", location_ambiguities}\` when a passed \`city\` was ambiguous.
+`;
 var leadbay_get_clarification = `Check whether Leadbay has a pending clarification question \u2014 a question raised when refining the intelligence prompt produced contradictory or ambiguous criteria. Returns \`{pending: false, clarification: null}\` when nothing is pending (the backend returns 204).
 
 WHEN TO USE: after leadbay_refine_prompt, to see if Leadbay needs the user to disambiguate.
@@ -706,7 +1000,7 @@ var leadbay_get_contacts = `Get contacts for a lead, including enriched email an
 
 WHEN TO USE: to check enrichment status (\`contact.enrichment.done\`) on individual leads after a bulk enrichment was launched, or to find the \`contact_id\` needed by leadbay_enrich_contacts.
 
-WHEN NOT TO USE: as a substitute for leadbay_research_lead, which already includes enriched contacts in its return.
+WHEN NOT TO USE: as a substitute for leadbay_research_lead_by_id, which already includes enriched contacts in its return.
 `;
 var leadbay_get_enrichment_job_titles = `List the actual job titles present across the leads currently in the user's selection \u2014 the candidate set the user can ask to enrich.
 
@@ -724,7 +1018,7 @@ var leadbay_get_lead_activities = `Get prospecting activity history for a lead (
 
 WHEN TO USE: to avoid redundant outreach and understand where this lead is in the sales process.
 
-WHEN NOT TO USE: when leadbay_research_lead has already been called \u2014 it includes recent prospecting actions in its engagement block.
+WHEN NOT TO USE: when leadbay_research_lead_by_id has already been called \u2014 it includes recent prospecting actions in its engagement block.
 `;
 var leadbay_get_lead_notes = `Read existing notes on a lead \u2014 context the human team or prior agent runs have already captured.
 
@@ -736,7 +1030,7 @@ var leadbay_get_lead_profile = `Get a full lead profile including company detail
 
 WHEN TO USE: low-level \u2014 for fine-grained access to the raw shape of the lead profile.
 
-WHEN NOT TO USE: as the agent's default lead-detail tool \u2014 use leadbay_research_lead, which structures the data top-down (qualification first, then signals, then firmographics, then contacts, then engagement) and reshapes web_fetch.content into a stable array form.
+WHEN NOT TO USE: as the agent's default lead-detail tool \u2014 use leadbay_research_lead_by_id, which structures the data top-down (qualification first, then signals, then firmographics, then contacts, then engagement) and reshapes web_fetch.content into a stable array form.
 `;
 var leadbay_get_lens_filter = `Read the firmographic filter (sectors, sizes, locations) currently applied to a lens.
 
@@ -772,7 +1066,7 @@ var leadbay_get_taste_profile = `Get the user's Ideal Buyer Profile, purchase-in
 
 WHEN TO USE: at the very start of a session to understand what kind of leads the user is looking for.
 
-WHEN NOT TO USE: per-lead \u2014 leadbay_research_lead already includes the per-lead qualification answers (which are scored against these org-level questions).
+WHEN NOT TO USE: per-lead \u2014 leadbay_research_lead_by_id already includes the per-lead qualification answers (which are scored against these org-level questions).
 `;
 var leadbay_get_user_prompt = `Read the org's intelligence-refinement prompt (free-text instruction that steers lead recommendations beyond firmographics). Returns \`{prompt: null, set: false}\` when none is configured (the backend returns 204 in that case).
 
@@ -784,13 +1078,13 @@ var leadbay_get_web_fetch = `Read the AI-generated web-research summary for a le
 
 WHEN TO USE: when the agent already qualified this lead and wants the underlying research to reason from.
 
-WHEN NOT TO USE: as the first read on a lead \u2014 the leadbay_research_lead composite bundles this with qualification answers and reshapes the dict into a stable array form.
+WHEN NOT TO USE: as the first read on a lead \u2014 the leadbay_research_lead_by_id composite bundles this with qualification answers and reshapes the dict into a stable array form.
 `;
 var leadbay_import_and_qualify = `Import + qualify leads in one call. Pass either \`domains: [{domain, name?}]\` (Mode A) OR \`records[]\` with \`mappings\` (Mode B). At least one mapped field must be LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE. Discover the org's mappable surface via \`leadbay_list_mappable_fields\`. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan \u2192 resolve \u2192 preserve \u2192 commit phases.
 
 WHEN TO USE: agent has a list of companies (domains, or CSV-shaped rows from the user's CRM) and wants the full AI qualification \u2014 qualification answers, web-research signals \u2014 without orchestrating import + bulk_qualify_leads + lead_profile chains by hand.
 
-WHEN NOT TO USE: discovery (use leadbay_pull_leads); single-lead deep dive (use leadbay_research_lead); high-cadence or untrusted automation \u2014 this mutates user state and consumes ai_rescore + web_fetch quota.
+WHEN NOT TO USE: discovery (use leadbay_pull_leads); single-lead deep dive (use leadbay_research_lead_by_id); high-cadence or untrusted automation \u2014 this mutates user state and consumes ai_rescore + web_fetch quota.
 
 Budgets: \`total_budget_ms\` caps wall-clock; \`per_lead_budget_ms\` caps each lead's poll. For short transport timeouts, pass \`wait_for_completion:false\` and poll \`leadbay_import_status\`. Outputs \`qualified[]\`, \`still_running[]\`, \`not_imported[]\`, \`qualify_id\` (resumable handle). Idempotent within a 5-min window. \`dry_run:'preview'\` returns mapping hints + custom-field candidates without importing.
 
@@ -815,13 +1109,39 @@ The response carries either a completed result or an async handle. Render a brie
 
 **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.
+Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead_by_id\` in NEXT STEPS.
 
 
 ---
 
 ## NEXT STEPS \u2014 after an import
 
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
 | Observation                                    | Suggest                                                       | Calls                                                  |
 |------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|
 | Status: running                                | "Check progress"                                              | leadbay_import_status(handle_id)                       |
@@ -831,7 +1151,7 @@ Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_res
 | 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.
+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_by_id. For MCP clients with short transport timeouts, pass \`wait_for_completion:false\` to return quickly with \`{status:'running', handle_id}\`; poll leadbay_import_status with that handle. For end-to-end import+qualify in one call, prefer leadbay_import_and_qualify. For messy files, prefer the \`leadbay_import_file\` prompt which walks an agent through scan \u2192 resolve \u2192 preserve \u2192 commit phases.
 
 TWO MODES: (A) Domain-list shortcut \u2014 pass \`domains: [{domain, name?}]\`. The tool builds a 2-column CSV (LEAD_NAME, LEAD_WEBSITE) and imports with the default mapping. (B) Custom records + mapping \u2014 pass \`records: [{Col1, Col2, ...}]\` plus \`mappings.fields: {Col1: 'LEAD_NAME', ...}\`. \`mappings.fields\` must include LEADBAY_ID, CRM_ID, SIREN, LEAD_NAME, or LEAD_WEBSITE (resolver needs at least one identity key). Pass exactly one of \`domains\` / \`records\`. Reserved column \`MCP_ROW_ID\` cannot appear in records/mappings \u2014 the tool injects it for stable reconciliation.
 
@@ -839,7 +1159,7 @@ MUTATES USER STATE: each call creates a row in the user's CRM-imports list (visi
 
 WHEN TO USE: you have a list of company domains from another system (CRM, analytics, email correspondents) and need stable Leadbay leadIds; or CRM-shaped rows with custom columns and want to drive the wizard with explicit field mappings.
 
-WHEN NOT TO USE: for prospect discovery (use leadbay_pull_leads); for one specific company's profile (use leadbay_research_company); when you can't tolerate the side effects above; when you also want qualification in the same call (use leadbay_import_and_qualify).
+WHEN NOT TO USE: for prospect discovery (use leadbay_pull_leads); for one specific company's profile (use leadbay_research_lead_by_name_fuzzy); when you can't tolerate the side effects above; when you also want qualification in the same call (use leadbay_import_and_qualify).
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 
@@ -862,13 +1182,39 @@ The response carries either a completed result or an async handle. Render a brie
 
 **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.
+Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead_by_id\` in NEXT STEPS.
 
 
 ---
 
 ## NEXT STEPS \u2014 after an import
 
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
 | Observation                                    | Suggest                                                       | Calls                                                  |
 |------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|
 | Status: running                                | "Check progress"                                              | leadbay_import_status(handle_id)                       |
@@ -922,6 +1268,42 @@ WHEN TO USE: low-level.
 
 WHEN NOT TO USE: from agent flow \u2014 leadbay_enrich_titles handles selection lifecycle, preview, launch, and cleanup.
 
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+`;
+var leadbay_like_lead = `## WHEN TO USE
+
+Trigger phrases: "I like this lead", "thumbs up", "this one looks good", "save this one", "this is a good fit", "more like this", "yes to this one".
+
+Do NOT use for: "remind me about this lead later / snooze it" \u2192 \`leadbay_set_pushback\`; "not relevant / wrong fit / thumbs down" \u2192 \`leadbay_dislike_lead\`.
+
+Prefer when: user expresses durable positive interest in a specific lead; pass the lead's UUID as \`lead_id\`
+
+Examples that SHOULD invoke this tool:
+- "I like this lead \u2014 show me more like it."
+- "Thumbs up on Acme Corp, save it."
+- "This one's a perfect fit, keep them in the rotation."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Skip this for now, I'll look at it next week."
+- "Not relevant \u2014 wrong industry."
+- "Just show me the top leads today."
+
+## RENDER (quick)
+
+One short confirmation line after the call returns ("\u{1F44D} Liked **{company_name}** \u2014
+positive signal sent."), then continue the current flow (don't dump the full
+lead card again).
+
+---
+
+Mark a lead as liked. This is the same action as clicking the thumbs-up on the Leadbay website. The signal is fed back into the scoring engine: liked leads improve the quality of future batches by teaching Leadbay what the user finds relevant.
+
+Pass the lead's UUID as \`lead_id\`.
+
+WHEN TO USE: the user explicitly approves of a lead ("this one looks good", "I like this", "thumbs up", "save this one", "this is a good fit"). Also use after \`leadbay_research_lead\` reveals strong signals.
+
+WHEN NOT TO USE: the user is just reading or researching a lead without expressing approval. Use \`leadbay_dislike_lead\` for negative signals; use \`leadbay_set_pushback\` for "remind me later" / temporary snooze (like is durable; pushback is reversible).
+
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
 var leadbay_list_lenses = `List all available Leadbay lenses (saved lead-search configurations). Each lens defines a different target market or buyer segment. The lens with \`is_last_active=true\` is used by default for lead discovery.
@@ -930,6 +1312,14 @@ WHEN TO USE: when the user wants to switch lens or asks "what lenses do I have".
 
 WHEN NOT TO USE: in normal flow \u2014 composites auto-resolve the active lens via \`/me.last_requested_lens\`.
 `;
+var leadbay_list_locations = `Search the geo / admin-area taxonomy by free-text name and return the matching admin_area ids. This is the primary way to turn a user's "leads in Berlin" / "filter to Lyon" intent into the \`{type: "location_ids", locations: [<id>]}\` shape that the backend filter expects.
+
+The response has two arrays: \`results\` (top-10 prefix matches ranked by relevance) and \`parents\` (the admin-area chain referenced by \`results[].parent_ids\`, useful for disambiguation breadcrumbs). Each entry: \`{id, country, level, name, parent_ids}\`. The \`level\` is the admin depth \u2014 **5** = region, **6** = county, **7** = township-area, **8** = city/town.
+
+WHEN TO USE: to resolve a free-text city/region name before passing it to a \`location_ids\` filter (e.g. on \`leadbay_pull_followups({set_filter})\` or \`leadbay_adjust_audience\`). The composite \`leadbay_pull_followups\` accepts \`city: <free-text>\` directly and runs this resolver internally \u2014 prefer that path; reach for this granular tool only when you need to surface candidates to the user before committing.
+
+WHEN NOT TO USE: when you already have an admin_area id \u2014 pass it as \`city_id\` (composite path) or directly inside the FilterCriterion.
+`;
 var leadbay_list_mappable_fields = `List every CRM field the agent can target when calling leadbay_import_leads or leadbay_import_and_qualify. Returns two arrays: \`standard_fields\` (Leadbay's built-in StandardCrmFieldType enum \u2014 LEAD_NAME, LEAD_WEBSITE, LEAD_STATUS, contact + location + sector fields) and \`custom_fields\` (this org's user-defined fields \u2014 id, name, type, and the literal \`mapping_value\` you pass in \`mappings.fields\`). For custom fields, \`mapping_value\` is the wire-format string \`CUSTOM.<id>\` \u2014 pass it verbatim.
 
 For contact exports, map person data to CONTACT_* fields and still provide parent-company identity via LEADBAY_ID/LEAD_WEBSITE/LEAD_NAME/CRM_ID/SIREN. When contact emails contain business domains, agents may derive a clean company-domain column for LEAD_WEBSITE only when the domain agrees with the row's company/deal/brand context, while preserving the original email as CONTACT_EMAIL. For import files, audit every meaningful source column. If no standard/contact field fits, preserve the data by creating or reusing a custom field unless the column is blank, duplicate plumbing, raw unparsed noise after useful extraction, or harmful to data quality. For HubSpot or other source-system deep links, create or reuse an EXTERNAL_ID/TEXT custom field with leadbay_create_custom_field, then map the source id/link to the returned \`mapping_value\`. Backend mapping_hints are advisory only; for contact files, do not accept hints such as first_name -> LEAD_NAME when the column is clearly a person field.
@@ -982,6 +1372,17 @@ WHEN NOT TO USE: if a token is already preconfigured \u2014 you'll just overwrit
 
 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_open_billing_portal = `Generate a one-shot Stripe customer-portal URL. Wraps \`GET /1.5/stripe/portal\` \u2192 \`{url}\`. Returns a fresh Stripe-hosted URL the user can open to manage their existing Leadbay subscription: change plan tier, swap payment method, view invoices. The agent does NOT make subscription changes itself \u2014 it surfaces the URL and lets the user act.
+
+Sibling of \`leadbay_create_topup_link\`. Use cases differ:
+
+- **Top-up** (\`leadbay_create_topup_link\`) = one-shot purchase of AI credits to clear an immediate quota throttle. Doesn't change the plan.
+- **Billing portal** (this tool) = ongoing subscription management. Plan upgrades persist; they raise the recurring window caps (daily/weekly/monthly) rather than buying a one-time bucket.
+
+WHEN TO USE: when the user asks to upgrade / downgrade / change plan; manage payment methods; view invoices; or "open my billing".
+
+WHEN NOT TO USE: for one-off credit top-ups (use \`leadbay_create_topup_link\`); for read-only quota state (use \`leadbay_account_status\` / \`leadbay_get_quota\`).
+`;
 var leadbay_pick_clarification = `Answer the pending clarification question \u2014 either by picking one of the offered options (\`option_id\`) or by typing a free-text answer. The answer is stored as the new user_prompt and triggers regeneration. Admin-only.
 
 WHEN TO USE: low-level.
@@ -990,7 +1391,36 @@ 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 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.
+var leadbay_prepare_outreach = `## WHEN TO USE
+
+Trigger phrases: "draft outreach for <Contact>", "write an email to <Contact>", "prep me to call <Contact>", "outreach package for <Company>", "I'm about to reach out to <X>".
+
+Do NOT use for: "research a lead I haven't picked yet" \u2192 \`leadbay_research_lead_by_id\`; "log outreach I already sent" \u2192 \`leadbay_report_outreach\`; "enrich a batch of contacts" \u2192 \`leadbay_enrich_titles\`.
+
+Prefer when: user is about to act \u2014 has picked the lead AND the contact. Single-lead, action-imminent context
+
+Examples that SHOULD invoke this tool:
+- "Draft an email to Sarah at Acme."
+- "Help me write outreach for John Smith."
+- "I'm about to call Acme's CTO \u2014 prep me."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "I just sent that email \u2014 log it."
+- "Enrich the contacts on these 20 leads."
+- "Research the Acme lead before I commit."
+
+## RENDER (quick)
+
+Route the draft through \`message_compose_v1\` (Claude's email composer)
+with 2\u20133 strategic variants \u2014 labels describe STRATEGY, not tone
+("Push for alignment", "Reference M&A signal", "Soft intro \u2014 peer
+reference"). Above the composer, emit ONE short markdown paragraph
+with score callout + sector fit + linked contact name + bare phone /
+email. Do NOT paste the email body into chat prose alongside.
+
+---
+
+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\`.
 
@@ -1001,7 +1431,73 @@ IRON LAW \u2014 OUTCOME AFTER OUTREACH. The moment the user reports outreach hap
 
 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).
+WHEN NOT TO USE: across many leads \u2014 use leadbay_enrich_titles for bulk; for general lead detail use leadbay_research_lead_by_id (richer signals); to actually log the outreach action use leadbay_report_outreach (requires verification).
+
+---
+
+## RENDER \u2014 host-native message composer is the PRIMARY surface
+
+\`message_compose_v1\` is the canonical surface for outreach drafts on this tool. The composer gives the user inline edit + send affordances and beats any prose code-fenced draft. **If the host exposes \`message_compose_v1\`, route every draft through it.** Don't paste email body or call-opener body into chat prose alongside \u2014 the composer IS the visual.
+
+Above the composer, emit ONE short markdown context paragraph: the lead's score callout + sector fit + recommended-contact name (LinkedIn-markdown-linked) + bare phone/email pills. That gives the user the "why this lead" context. The composer below carries the actionable draft.
+
+**Single draft:**
+
+\`\`\`
+message_compose_v1({
+  kind: "email",
+  summary_title: "Outreach to <Contact Name> at <Company>",
+  variants: [{
+    label: "Lead with the M&A signal",
+    subject: "<one-line subject \u2014 references the angle>",
+    body: "<5-8 sentence email; salesperson voice; references signal + a clear next step>"
+  }]
+})
+\`\`\`
+
+**Strategic options (preferred when split_ai_summary surfaces multiple angles):**
+
+\`\`\`
+message_compose_v1({
+  kind: "email",
+  summary_title: "Three angles for <Company> outreach",
+  variants: [
+    { label: "Push for alignment",  subject: "...", body: "..." },
+    { label: "Reference the M&A signal", subject: "...", body: "..." },
+    { label: "Soft intro \u2014 peer reference", subject: "...", body: "..." }
+  ]
+})
+\`\`\`
+
+Constraints:
+- **Labels describe STRATEGY, not tone.** "Push for alignment", "Reference M&A signal", "Lead with peer reference" \u2014 not "Friendly" / "Formal" / "Aggressive".
+- **2\u20133 variants when strategic options are clearly distinct.** One variant when you have a single best-angle draft.
+- Subject required for \`kind: "email"\`. Phone/call openers use \`kind: "other"\` with the opener in \`body\`.
+
+The composer becomes the single visual. **Don't also paste the email body into chat prose** \u2014 that's just noise next to the composer.
+
+For phone-only contacts (no email enriched), use \`kind: "other"\` with a 60-second call opener.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
 
 ---
 
@@ -1029,7 +1525,7 @@ Present as the richest single-record card the MCP emits. The user is seconds-to-
 **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.
+- 3\u20134 bullets distilling \`split_ai_summary.next_step\` and any signals from a prior \`research_lead_by_id\` 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]**
@@ -1042,7 +1538,7 @@ Same shape as the contact history, but only include items NOT duplicated from th
 
 **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)\`.
+One line: \`+N more contacts at this company \u2014 [see them all](leadbay_research_lead_by_id)\`.
 
 **Closing line** (when enrichment is in progress): \`*Enrichment running \u2014 I'll refresh once email/phone lands.*\`
 
@@ -1078,6 +1574,32 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 ## NEXT STEPS \u2014 after the outreach brief
 
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
 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                                                  |
@@ -1088,7 +1610,7 @@ Offer 2\u20133 follow-ups. Choose based on enrichment state + available channels
 | 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)                       |
+| History is empty                                | "Pull the strategic overview before drafting"                 | leadbay_research_lead_by_id(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                           |
@@ -1109,7 +1631,36 @@ 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_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.
+var leadbay_pull_followups = `## WHEN TO USE
+
+Trigger phrases: "what should I follow up on", "leads I've already worked", "leads I haven't contacted", "what's overdue", "stale leads", "before my trip", "this month", "what's going on with my pipeline", "leads in <city / state / country>".
+
+Do NOT use for: "show me leads / new leads / today's prospects" \u2192 \`leadbay_pull_leads\`; "I'm going to <city> / in person / trip" \u2192 \`leadbay_followups_map\`; "Texas / California / France etc. \u2014 place names go in \`city\`, NOT \`keywords\`" \u2192 \`leadbay_pull_followups\`.
+
+Prefer when: user names a city / sector / recency window \u2192 pass \`city\` (or \`set_filter\`) so the result is narrowed AND persists for the next session
+
+Examples that SHOULD invoke this tool:
+- "What should I follow up on this week?"
+- "Which leads have I not contacted in 30 days?"
+- "What's overdue in my pipeline?"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me today's new leads."
+- "I'm flying to Berlin Thursday \u2014 who can I meet?"
+- "Draft an email to Sarah at Acme."
+
+## RENDER (quick)
+
+4-col markdown table sorted by \`last_monitor_action_at\` desc, NO
+score bar (status badges instead). Col 1 = status (\u{1F3AF}\u26A1\u{1F7E2}\u{1F4A4}\u2728\u{1F525}\u2744) +
+company link + location/size. Col 2 = AI take (3 lines from
+\`split_ai_summary\`). Col 3 = history + notes. Col 4 = contacts
+(\u2605 recommended, \u260E \u{1F4E7} pills). Active-filters chip line ABOVE the
+table. Detail + status priority below.
+
+---
+
+Pull KNOWN leads from the user's Monitor view \u2014 the re-engagement entry point. Use when the user asks "what should I follow up on", "leads I haven't contacted", "leads in [city]", "before my trip", or any phrasing implying pre-existing pipeline context. For NEW leads from Discover, use \`leadbay_pull_leads\`.
 
 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.
 
@@ -1126,7 +1677,9 @@ Practical mapping from user phrasing to criterion:
 | "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.
+Geo filtering needs \`admin_area_id\` resolution \u2014 backend rejects free-text in \`location_ids\`. Pass \`city: "<free-text>"\` and the composite calls \`/geo/search\` internally, picks the best match, merges its id into \`set_filter\`. Ambiguous matches return \`status: "ambiguous_locations"\` + \`location_ambiguities[]\` \u2014 pick an id and re-call with \`city_id\`. For multi-city cases, call \`leadbay_list_locations\` then pass \`set_filter.criteria\` with \`{type: "location_ids", is_excluded: false, locations: [...]}\`.
+
+**Place names go through \`city\`, NEVER \`keywords\`.** This includes any geographic token the user names \u2014 cities (\`"Berlin"\`, \`"NYC"\`), states / provinces / regions (\`"Texas"\`, \`"California"\`, \`"Bavaria"\`), countries (\`"France"\`, \`"United States"\`), neighborhoods (\`"Brooklyn"\`, \`"SoHo"\`). The \`/geo/search\` resolver handles all admin levels \u2014 level 4 (state) and level 2 (country) resolve just as well as level 5 (city). If you put \`"Texas"\` in \`keywords\` you get a TEXT-MATCH against company descriptions (\u22480 hits) instead of a real state filter. If a place name resolves ambiguously, surface the choices to the user \u2014 do NOT silently fall back to keyword search or to the unfiltered Monitor view. If \`keywords: ["Texas"]\` returned empty, the next call is \`city: "Texas"\`, not \`keywords: []\`.
 
 **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.
 
@@ -1134,7 +1687,7 @@ WHEN TO USE: re-engaging pipeline ("what should I follow up on", "stale leads"),
 
 WHEN NOT TO USE: for NEW leads \u2014 that's \`leadbay_pull_leads\` (Discover).
 
-**Anti-confusion guardrail.** If you're iterating \`pull_leads\` pages looking for rows with \`prospecting_actions_count > 0\` or \`notes_count > 0\`, STOP \u2014 wrong entry point. The two read different backend tables; a lead with follow-up history may not appear in \`pull_leads\` (already aged out of the new-leads queue). Call \`pull_followups\` instead.
+**Anti-confusion guardrail.** Iterating \`pull_leads\` pages looking for \`prospecting_actions_count > 0\` or \`notes_count > 0\` rows is the wrong entry point \u2014 the two read different tables. Leads with follow-up history live in \`pull_followups\`.
 
 ---
 
@@ -1227,6 +1780,32 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 ## NEXT STEPS \u2014 after the follow-ups table
 
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
 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                                                                                              |
@@ -1236,16 +1815,47 @@ Always include at least one filter-modification offer (users think in filters: b
 | \`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)                                            |
+| User planning a trip / in a city              | "Group by city for trip planning"                        | leadbay_pull_followups({city: "<their city>"}) \u2014 composite resolves admin_area_id via /geo/search  |
 | 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)                                   |
+| One obvious priority row                      | "Take me to that lead's full brief"                      | leadbay_prepare_outreach(leadId) / leadbay_research_lead_by_id(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.
+var leadbay_pull_leads = `## WHEN TO USE
+
+Trigger phrases: "show me leads", "today's prospects", "what's new today", "let's prospect", "best new leads", "my batch".
+
+Do NOT use for: "leads I should follow up with" \u2192 \`leadbay_pull_followups\`; "leads I've already worked" \u2192 \`leadbay_pull_followups\`; "I'm going to <city>" \u2192 \`leadbay_followups_map\`; "in person" \u2192 \`leadbay_followups_map\`.
+
+Prefer when: user has named a specific lens \u2014 pass \`lensId\` and pin it for the rest of the session
+
+Examples that SHOULD invoke this tool:
+- "Show me today's leads."
+- "What's in my inbox this morning?"
+- "Pull my best new prospects."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Which leads should I follow up with this week?"
+- "Show leads I've already contacted."
+- "I'm flying to Berlin Thursday \u2014 who should I meet?"
+
+## RENDER (quick)
+
+3-col markdown table sorted by \`score\` desc \u2014 DO NOT print the numeric
+score. Col 1 = inline-code 10-segment bar (\`\u25B0\` firmographic, \`\u2756\` AI
+booster cap at the right end of the filled run, \`\u25B1\` empty;
+filled=round(score/10), ai=round(avg_boost/3.3)) + \`<br>\` + linked
+company \xB7 location \xB7 size. Col 2 = why-fits \u226420 words. Col 3 = linked
+contact + title. Full algorithm + linking rules below.
+
+---
+
+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.
 
@@ -1300,7 +1910,7 @@ If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is nul
 **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\`.
+- 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_by_id\` or \`leadbay_research_lead_by_name_fuzzy\`.
 - 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.
 
@@ -1340,14 +1950,40 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 ## 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.
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick 2\u20133 items below based on what was actually observed in the response. The table is the source of truth for which moves are valid.
 
 | 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})    |
+| User points at a single row                                | "Research [Company] in depth"                                | leadbay_research_lead_by_id(leadId)                    |
+| User only has a name (no leadId in context)                | "Look up [Company] by name"                                  | leadbay_research_lead_by_name_fuzzy(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)                       |
@@ -1369,7 +2005,7 @@ var leadbay_qualify_status = `Retrieve the current state of an import_and_qualif
 
 WHEN TO USE: after leadbay_import_and_qualify or leadbay_bulk_qualify_leads returned a \`qualify_id\` with non-empty \`still_running[]\`, call this tool a few minutes later (or hours) to retrieve the now-completed qualifications without re-running the import or re-spending qualify quota.
 
-WHEN NOT TO USE: as a substitute for leadbay_research_lead \u2014 that's a deeper per-lead profile and includes contacts. This tool is purely the qualification answers + signals_count.
+WHEN NOT TO USE: as a substitute for leadbay_research_lead_by_id \u2014 that's a deeper per-lead profile and includes contacts. This tool is purely the qualification answers + signals_count.
 `;
 var leadbay_recall_ordered_titles = `Show job titles the org has previously enriched, so the agent can repeat the same titles for new leads (or skip already-saturated ones). Two implementation paths: (1) PREFERRED \u2014 a selection-scoped preview call that reads \`previously_enriched_titles\` from the backend (newer prod field). (2) FALLBACK \u2014 live aggregation across each lead's enriched contacts. The composite picks transparently.
 
@@ -1413,13 +2049,64 @@ WHEN NOT TO USE: BEFORE doing the outreach (use \`dry_run:true\` to validate arg
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
-var leadbay_research_company = `Deep-dive research on a specific company by NAME (fuzzy match against the active lens's wishlist). Pass \`companyName\` (matches the top-scoring lead with that name) or \`leadId\` (takes precedence when both supplied).
+var leadbay_research_lead_by_id = `## WHEN TO USE
+
+Trigger phrases: "tell me about this lead", "deep dive on the lead I just picked", "is <lead> a fit", "should I pursue <lead>", "everything you know about lead <UUID>", "research this lead".
 
-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).
+Do NOT use for: "user names a company in prose without a Leadbay lead id" \u2192 \`leadbay_research_lead_by_name_fuzzy\`; "draft outreach for <Contact>" \u2192 \`leadbay_prepare_outreach\`.
 
-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.
+Prefer when: user already picked a row from pull_leads/pull_followups \u2014 you have the UUID. Pass it via \`leadId\`.
 
-WHEN NOT TO USE: when you already have the lead_id and need the bundled deeper lens-scoped data \u2014 use leadbay_research_lead.
+Examples that SHOULD invoke this tool:
+- "Tell me everything about that lead I just picked."
+- "Deep dive on the lead at the top of my list."
+- "Is this one actually a fit \u2014 what does the AI think?"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Look up Acme Corp for me."
+- "What do we know about Globex?"
+- "Show me today's leads."
+
+---
+
+Tell me everything decision-relevant about a single lead, identified by its
+Leadbay UUID. 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 two-tier contact set (\`enriched\` + \`org\`), the
+unified \`recent_activities\` timeline, the engagement counts, and a
+\`_meta.has_reachable_contact\` hint that drives NEXT STEPS. Order is
+deliberate: qualification first, then signals, then firmographics, then
+contacts, then recent activity.
+
+Scoring has two layers: the basic \`score\` (firmographic, always present,
+already decent) and the AI qualification layer (\`ai_agent_lead_score\` +
+per-question answers + web_fetch signals). The AI layer is pre-populated for
+roughly the top 10 of each daily batch, and on-demand (via
+leadbay_bulk_qualify_leads) for anything below that. Combine both layers when
+judging a lead.
+
+The companion tool **leadbay_research_lead_by_name_fuzzy** wraps this one for
+the case where the user names a company in prose without a UUID \u2014 it
+fuzzy-resolves the name against the active lens's wishlist, then delegates
+here. Both return the same shape; the fuzzy wrapper just adds
+\`_meta.resolved_from\` and \`_meta.match_candidates\` so you can offer
+disambiguation.
+
+WHEN TO USE: when picking up a single lead from
+leadbay_pull_leads (or any list that exposed a leadId) 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.
 
 ---
 
@@ -1427,7 +2114,7 @@ WHEN NOT TO USE: when you already have the lead_id and need the bundled deeper l
 
 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 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_by_id\`, 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\`.
 
@@ -1502,49 +2189,278 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 ## 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.
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Offer 2\u20133 follow-ups that match what the lead's response actually contains.
 
-### MODE A (Discovery)
+**Primary branching signal**: \`contacts.reachable[]\` vs \`contacts.candidates[]\`.
+- \`contacts.reachable[]\` = people with an email or phone right now. Message them directly.
+- \`contacts.candidates[]\` = people identified at this company (LinkedIn-only), \`enrichment_done: false\`. Cannot be messaged without first calling \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach({enrich:true})\`).
+- \`_meta.has_reachable_contact\` is the boolean shortcut \u2014 true iff \`reachable.length > 0\` or the recommended_contact has a channel.
 
-| 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)             |
+Always offer a cross-mode pivot at the end so the user can redirect if you guessed wrong.
 
-End MODE A with the pivot offer: \`"Want the contact-prep view for [recommended contact name]?"\`
+### MODE A \u2014 Nobody reachable yet (\`contacts.reachable\` is empty)
 
-### MODE B (Contact preparation)
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| \`contacts.candidates[]\` non-empty                      | "Enrich N candidate contacts to acquire emails / phones" | leadbay_enrich_titles({ leadIds: [leadId] })                   |
+| User wants outreach now anyway                         | "Enrich + draft outreach in one shot"                    | leadbay_prepare_outreach({ leadId, enrich: true })             |
+| \`qualification[]\` is empty                             | "Run AI qualification on this lead first"                | leadbay_bulk_qualify_leads([leadId])                           |
+| \`web_insights_fetched_at\` older than 30 days           | "Refresh the web research \u2014 this is stale"               | leadbay_research_lead_by_id({ leadId }) \u2014 re-runs the fetch    |
+| User is exploring multiple companies                   | "Back to the lead list"                                  | leadbay_pull_leads                                             |
 
-| 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 A with the pivot offer: \`"Want the strategic overview before
+enriching? (already shown above)"\`
 
-End MODE B with the pivot offer: \`"Want the full strategic overview instead?"\`
+### MODE B \u2014 At least one reachable contact (\`contacts.reachable[]\` non-empty OR recommended_contact has channels)
+
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| Recommended contact has an email                       | "Draft the outreach email"                               | leadbay_prepare_outreach({ leadId })                           |
+| \`firmographics.phone_numbers[]\` non-empty              | "Show full call notes + a 60-second opener"              | leadbay_prepare_outreach({ leadId })                           |
+| \`recent_activities[]\` non-empty                        | "Log a follow-up touchpoint"                             | leadbay_report_outreach                                        |
+| Adding pre-call context                                | "Add a note to this lead"                                | leadbay_add_note                                               |
+| \`qualification[]\` non-empty                            | "Expand the AI qualification answers"                    | (render qualification[] as a sub-card)                         |
+
+End MODE B with the pivot offer: \`"Want to qualify deeper before reaching
+out?"\`
+
+### Cross-mode rows (always available)
+
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| User is done with this lead                            | "Back to the inbox"                                      | leadbay_pull_leads                                             |
 `;
-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.
+var leadbay_research_lead_by_name_fuzzy = `## WHEN TO USE
+
+Trigger phrases: "look up <Company>", "research <Company>", "what do we know about <Company>", "find <Company> in my pipeline", "tell me about <Company>".
+
+Do NOT use for: "user picked a row from a previous list (you have leadId)" \u2192 \`leadbay_research_lead_by_id\`; "draft outreach for <Contact>" \u2192 \`leadbay_prepare_outreach\`.
+
+Prefer when: user names a company in prose without a Leadbay id \u2014 composite fuzzy-matches against the active lens's wishlist.
+
+Examples that SHOULD invoke this tool:
+- "Look up Acme Corp for me."
+- "What do we know about Globex?"
+- "Find Initech in my pipeline."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Tell me about that lead I just picked."
+- "Show me today's prospects."
+- "Draft outreach to Acme's CTO."
+
+---
+
+Thin wrapper around **leadbay_research_lead_by_id**. Accepts a \`companyName\`,
+fuzzy-matches it against the top 50 of the active (or supplied) lens's
+wishlist, picks the highest-scoring substring hit, and delegates the actual
+research to \`leadbay_research_lead_by_id\`. Returns the **same payload shape**
+as \`_by_id\`, with two additions on \`_meta\`:
+
+- \`_meta.resolved_from\`: \`"companyName"\` (so the agent knows the entry point).
+- \`_meta.resolved_query\`: the original \`companyName\` string.
+- \`_meta.match_candidates[]\`: up to 4 next-best substring matches as
+  \`{leadId, name, score}\` \u2014 surface these when ambiguity is plausible so the
+  user can redirect.
+
+On zero matches, throws \`LEAD_NOT_FOUND\` with a \`nearest_names[]\` payload (the
+top 5 by score from the lens, regardless of substring) so the agent can offer
+"did you mean\u2026" disambiguation.
+
+WHEN TO USE: when the user references a company by
+name and you don't yet have its \`lead_id\`. If \`_meta.match_candidates\` is
+non-empty, offer the next-best matches in NEXT STEPS so the user can correct
+a wrong fuzzy hit.
+
+WHEN NOT TO USE: when you already have the UUID \u2014 use
+leadbay_research_lead_by_id directly. This wrapper costs one extra
+\`discoverLeads\` round-trip; skipping it when you can is cheaper.
+
+---
+
+## 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_by_id\`, 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
+
+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
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
 
-Scoring has two layers: the basic \`score\` (firmographic, always present, already decent) and the AI qualification layer (\`ai_agent_lead_score\` + per-question answers + web_fetch signals). The AI layer is pre-populated for roughly the top 10 of each daily batch, and on-demand (via leadbay_bulk_qualify_leads) for anything below that. Combine both layers when judging a lead.
 
-WHEN TO USE: when picking up a single lead from leadbay_pull_leads to decide whether to act on it.
+Offer 2\u20133 follow-ups that match what the lead's response actually contains.
 
-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.)
+**Primary branching signal**: \`contacts.reachable[]\` vs \`contacts.candidates[]\`.
+- \`contacts.reachable[]\` = people with an email or phone right now. Message them directly.
+- \`contacts.candidates[]\` = people identified at this company (LinkedIn-only), \`enrichment_done: false\`. Cannot be messaged without first calling \`leadbay_enrich_titles\` (or \`leadbay_prepare_outreach({enrich:true})\`).
+- \`_meta.has_reachable_contact\` is the boolean shortcut \u2014 true iff \`reachable.length > 0\` or the recommended_contact has a channel.
 
-**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.
+Always offer a cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### MODE A \u2014 Nobody reachable yet (\`contacts.reachable\` is empty)
+
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| \`contacts.candidates[]\` non-empty                      | "Enrich N candidate contacts to acquire emails / phones" | leadbay_enrich_titles({ leadIds: [leadId] })                   |
+| User wants outreach now anyway                         | "Enrich + draft outreach in one shot"                    | leadbay_prepare_outreach({ leadId, enrich: true })             |
+| \`qualification[]\` is empty                             | "Run AI qualification on this lead first"                | leadbay_bulk_qualify_leads([leadId])                           |
+| \`web_insights_fetched_at\` older than 30 days           | "Refresh the web research \u2014 this is stale"               | leadbay_research_lead_by_id({ leadId }) \u2014 re-runs the fetch    |
+| User is exploring multiple companies                   | "Back to the lead list"                                  | leadbay_pull_leads                                             |
+
+End MODE A with the pivot offer: \`"Want the strategic overview before
+enriching? (already shown above)"\`
+
+### MODE B \u2014 At least one reachable contact (\`contacts.reachable[]\` non-empty OR recommended_contact has channels)
+
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| Recommended contact has an email                       | "Draft the outreach email"                               | leadbay_prepare_outreach({ leadId })                           |
+| \`firmographics.phone_numbers[]\` non-empty              | "Show full call notes + a 60-second opener"              | leadbay_prepare_outreach({ leadId })                           |
+| \`recent_activities[]\` non-empty                        | "Log a follow-up touchpoint"                             | leadbay_report_outreach                                        |
+| Adding pre-call context                                | "Add a note to this lead"                                | leadbay_add_note                                               |
+| \`qualification[]\` non-empty                            | "Expand the AI qualification answers"                    | (render qualification[] as a sub-card)                         |
+
+End MODE B with the pivot offer: \`"Want to qualify deeper before reaching
+out?"\`
+
+### Cross-mode rows (always available)
+
+| Observation                                            | Suggest                                                  | Calls                                                          |
+|--------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------|
+| User is done with this lead                            | "Back to the inbox"                                      | leadbay_pull_leads                                             |
+
+
+When \`_meta.match_candidates\` is non-empty, prepend one extra NEXT STEPS row:
+
+| Observation                                            | Suggest                                                              | Calls                                                                  |
+|--------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------|
+| \`_meta.match_candidates\` non-empty                     | "Did you mean **&lt;next-best.name&gt;**?"                                | leadbay_research_lead_by_id(leadId=&lt;next-best.leadId&gt;)                |
 `;
 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.
+WHEN NOT TO USE: for prospect discovery from scratch (use leadbay_pull_leads); for one known company profile (use leadbay_research_lead_by_name_fuzzy / leadbay_research_lead_by_id); or when the file already has clean, final LEADBAY_ID/CRM_ID/SIREN mappings and no row-level identity disambiguation is needed.
 
 ---
 
@@ -2380,30 +3296,77 @@ var listSectors = {
     idempotentHint: true,
     openWorldHint: true
   },
-  description: leadbay_list_sectors,
-  inputSchema: {
+  description: leadbay_list_sectors,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lang: { type: "string", description: "BCP-47 language tag (default: en)" },
+      includeInvisible: {
+        type: "boolean",
+        description: "Include sectors hidden from the UI (default false; ~91k items if true)"
+      }
+    },
+    additionalProperties: false
+  },
+  execute: async (client, params) => {
+    let lang = params.lang;
+    if (!lang) {
+      try {
+        const me = await client.resolveMe();
+        lang = me.language ?? "en";
+      } catch {
+        lang = "en";
+      }
+    }
+    const includeInvisible = params.includeInvisible ? "true" : "false";
+    const path = `/sectors/all?lang=${encodeURIComponent(lang)}&includeInvisible=${includeInvisible}`;
+    return await client.request("GET", path);
+  }
+};
+
+// ../core/dist/tools/list-locations.js
+var listLocations = {
+  name: "leadbay_list_locations",
+  annotations: {
+    title: "Search the geo / admin-area taxonomy",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_list_locations,
+  inputSchema: {
+    type: "object",
+    properties: {
+      q: {
+        type: "string",
+        description: "Free-text city / region name (e.g. 'Berlin', 'NYC', 'S\xE3o Paulo'). Returns top-10 prefix matches sorted by relevance, each with an admin_area id usable in FilterCriterion.location_ids."
+      }
+    },
+    required: ["q"],
+    additionalProperties: false
+  },
+  outputSchema: {
     type: "object",
     properties: {
-      lang: { type: "string", description: "BCP-47 language tag (default: en)" },
-      includeInvisible: {
-        type: "boolean",
-        description: "Include sectors hidden from the UI (default false; ~91k items if true)"
+      results: {
+        type: "array",
+        description: "Matches sorted by relevance. Each entry: {id, country, level, name, parent_ids}. `level` is admin depth (5=region, 6=county, 7=township-area, 8=city/town).",
+        items: { type: "object" }
+      },
+      parents: {
+        type: "array",
+        description: "Parent admin areas referenced by `results[].parent_ids`, returned for breadcrumb / hover-disambiguation rendering.",
+        items: { type: "object" }
       }
     },
-    additionalProperties: false
+    required: ["results", "parents"]
   },
   execute: async (client, params) => {
-    let lang = params.lang;
-    if (!lang) {
-      try {
-        const me = await client.resolveMe();
-        lang = me.language ?? "en";
-      } catch {
-        lang = "en";
-      }
-    }
-    const includeInvisible = params.includeInvisible ? "true" : "false";
-    const path = `/sectors/all?lang=${encodeURIComponent(lang)}&includeInvisible=${includeInvisible}`;
+    const q = (params.q ?? "").trim();
+    if (!q)
+      return { results: [], parents: [] };
+    const path = `/geo/search?q=${encodeURIComponent(q)}`;
     return await client.request("GET", path);
   }
 };
@@ -2587,7 +3550,7 @@ var getWebFetch = {
   },
   outputSchema: {
     type: "object",
-    description: "Raw LeadWebFetchPayload as returned by /leads/{id}/web_fetch. Permissive shape \u2014 backend dict structure is documented in detail by leadbay_research_lead which reshapes it.",
+    description: "Raw LeadWebFetchPayload as returned by /leads/{id}/web_fetch. Permissive shape \u2014 backend dict structure is documented in detail by leadbay_research_lead_by_id which reshapes it.",
     properties: {
       content: {
         description: "Backend dict content (object or string), or null when no fetch yet."
@@ -4188,6 +5151,60 @@ function coerceCsvValue(v) {
   return "";
 }
 
+// ../core/dist/tools/create-topup-link.js
+var createTopupLink = {
+  name: "leadbay_create_topup_link",
+  annotations: {
+    title: "Generate Stripe checkout URL for AI-credits top-up",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  description: leadbay_create_topup_link,
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "Stripe-hosted checkout URL. Surface as a clickable link; the user completes payment in their browser. Top-up clears the throttle immediately after Stripe webhook lands."
+      }
+    },
+    required: ["url"]
+  },
+  execute: async (client) => {
+    return await client.request("POST", "/stripe/topup_checkout", {});
+  }
+};
+
+// ../core/dist/tools/open-billing-portal.js
+var openBillingPortal = {
+  name: "leadbay_open_billing_portal",
+  annotations: {
+    title: "Generate Stripe customer-portal URL for subscription management",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  description: leadbay_open_billing_portal,
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "Stripe customer-portal URL. Surface as a clickable link; the user manages subscription / payment methods / invoices in their browser."
+      }
+    },
+    required: ["url"]
+  },
+  execute: async (client) => {
+    return await client.request("GET", "/stripe/portal");
+  }
+};
+
 // ../core/dist/tools/select-leads.js
 var selectLeads = {
   name: "leadbay_select_leads",
@@ -4994,87 +6011,63 @@ var createCustomField = {
   }
 };
 
-// ../core/dist/composite/research-company.js
-var researchCompany = {
-  name: "leadbay_research_company",
+// ../core/dist/tools/like-lead.js
+var likeLead = {
+  name: "leadbay_like_lead",
   annotations: {
-    title: "Research a company by name",
-    readOnlyHint: true,
+    title: "Like a lead",
+    readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true
   },
-  description: leadbay_research_company,
+  description: leadbay_like_lead,
+  optional: true,
+  write: true,
   inputSchema: {
     type: "object",
     properties: {
-      companyName: {
-        type: "string",
-        description: "Company name to research (one of companyName or leadId required). Matches the top-scoring lead with this name."
-      },
-      leadId: {
+      lead_id: {
         type: "string",
-        description: "Lead UUID if already known (one of companyName or leadId required). Takes precedence over companyName."
+        description: "UUID of the lead to like."
       }
     },
+    required: ["lead_id"],
     additionalProperties: false
   },
-  outputSchema: {
+  execute: async (client, params) => {
+    await client.requestVoid("POST", `/leads/${params.lead_id}/like`);
+    return { applied: true, lead_id: params.lead_id, action: "liked" };
+  }
+};
+
+// ../core/dist/tools/dislike-lead.js
+var dislikeLead = {
+  name: "leadbay_dislike_lead",
+  annotations: {
+    title: "Dislike a lead",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_dislike_lead,
+  optional: true,
+  write: true,
+  inputSchema: {
     type: "object",
     properties: {
-      lead: {
-        type: "object",
-        description: "Lead profile basics (id, name, score, ai_agent_lead_score, location, description, short_description, size, website, logo, ai_summary, tags, phone_numbers, keywords, contacts_count, recommended_contact_title, recommended_contact, web_fetch_in_progress)."
-      },
-      qualification: {
-        type: ["array", "null"],
-        description: "Per-question AI qualification answers ({question, score, response, computed_at, outdated_at}), or null if none.",
-        items: { type: "object" }
-      },
-      contacts: {
-        type: "array",
-        description: "Merged org + paid contacts. Each: {id, first_name, last_name, email, phone_number, linkedin_page, job_title, recommended, enrichment, source:'org'|'paid'}.",
-        items: { type: "object" }
-      },
-      web_insights: {
-        description: "Latest /web_fetch content (string) or null when no fetch is available."
-      },
-      web_insights_fetched_at: {
-        description: "ISO timestamp of the latest /web_fetch (string) or null."
-      },
-      recent_activities: {
-        type: "array",
-        description: "Recent activities for this lead (top 20). Each is the activity payload as returned by /leads/{id}/activities.",
-        items: { type: "object" }
+      lead_id: {
+        type: "string",
+        description: "UUID of the lead to dislike."
       }
     },
-    required: ["lead", "contacts", "recent_activities"]
+    required: ["lead_id"],
+    additionalProperties: false
   },
-  execute: async (client, params, ctx) => {
-    if (!params.leadId && !params.companyName) {
-      throw client.makeError("INVALID_PARAMS", "Pass either leadId or companyName", "Call leadbay_pull_leads first to surface candidate leads with their IDs, then call this with leadId.");
-    }
-    let leadId = params.leadId;
-    if (!leadId && params.companyName) {
-      const results = await discoverLeads.execute(client, { count: 50, page: 0 }, ctx);
-      const needle = params.companyName.toLowerCase();
-      const match = results.leads.find((l) => l.name.toLowerCase().includes(needle));
-      if (!match) {
-        throw client.makeError("LEAD_NOT_FOUND", `No lead matching "${params.companyName}" in the current lens`, "Call leadbay_pull_leads (optionally with a broader lensId) to see what's available, then call this with leadId.");
-      }
-      leadId = match.id;
-    }
-    const [profile, activities] = await Promise.allSettled([
-      getLeadProfile.execute(client, { leadId }, ctx),
-      getLeadActivities.execute(client, { leadId, count: 20 }, ctx)
-    ]);
-    if (profile.status === "rejected") {
-      throw profile.reason;
-    }
-    return {
-      ...profile.value,
-      recent_activities: activities.status === "fulfilled" ? activities.value.activities : []
-    };
+  execute: async (client, params) => {
+    await client.requestVoid("POST", `/leads/${params.lead_id}/dislike`);
+    return { applied: true, lead_id: params.lead_id, action: "disliked" };
   }
 };
 
@@ -5441,6 +6434,119 @@ var pullLeads = {
   }
 };
 
+// ../core/dist/composite/_geo-helpers.js
+var looksLikeId = (s) => /^\d+$/.test(s);
+var CITY_ALIASES = {
+  nyc: "City of New York",
+  "ny city": "City of New York",
+  "new york": "City of New York",
+  // user typing "New York" almost always means the city
+  "new york city": "City of New York",
+  manhattan: "City of New York",
+  "the big apple": "City of New York",
+  la: "Los Angeles",
+  "l.a.": "Los Angeles",
+  sf: "San Francisco",
+  "s.f.": "San Francisco",
+  "san fran": "San Francisco",
+  dc: "Washington",
+  "d.c.": "Washington",
+  "washington d.c.": "Washington",
+  "washington dc": "Washington",
+  philly: "Philadelphia",
+  vegas: "Las Vegas",
+  nola: "New Orleans"
+};
+function expandAlias(text) {
+  const key = text.trim().toLowerCase();
+  return CITY_ALIASES[key] ?? text;
+}
+function scoreMatch(text, match) {
+  const t = text.trim().toLowerCase();
+  const n = match.name.trim().toLowerCase();
+  if (n === t)
+    return 1;
+  if (n.startsWith(t))
+    return 0.6 + 0.2 * (t.length / n.length);
+  const wantTokens = new Set(t.split(/\s+/));
+  const haveTokens = new Set(n.split(/\s+/));
+  let intersect = 0;
+  for (const w of wantTokens)
+    if (haveTokens.has(w))
+      intersect += 1;
+  const union = (/* @__PURE__ */ new Set([...wantTokens, ...haveTokens])).size;
+  return union > 0 ? intersect / union : 0;
+}
+async function resolveLocations(client, texts) {
+  const direct = texts.filter((t) => looksLikeId(t));
+  const free = texts.filter((t) => t && !looksLikeId(t));
+  if (free.length === 0)
+    return { resolved: direct, ambiguities: [] };
+  const resolved = [...direct];
+  const ambiguities = [];
+  for (const originalText of free) {
+    const text = expandAlias(originalText);
+    const path = `/geo/search?q=${encodeURIComponent(text)}`;
+    let response;
+    try {
+      response = await client.request("GET", path);
+    } catch {
+      ambiguities.push({ location_text: originalText, matches: [] });
+      continue;
+    }
+    const results = response.results ?? [];
+    if (results.length === 0) {
+      ambiguities.push({ location_text: originalText, matches: [] });
+      continue;
+    }
+    const levelPreference = (level) => {
+      switch (level) {
+        case 5:
+          return 4;
+        // city proper
+        case 8:
+          return 3;
+        // standard city/town
+        case 6:
+          return 2;
+        // county
+        case 7:
+          return 1;
+        // township-area
+        case 4:
+          return 0;
+        // state/region
+        default:
+          return 0;
+      }
+    };
+    const ranked = results.map((r) => ({
+      id: r.id,
+      name: r.name,
+      country: r.country,
+      level: r.level,
+      score: scoreMatch(text, r)
+    })).sort((a, b) => {
+      if (b.score !== a.score)
+        return b.score - a.score;
+      return levelPreference(b.level) - levelPreference(a.level);
+    });
+    const top = ranked[0];
+    const runnerUp = ranked[1];
+    const isConfident = top.score >= 0.95 || // exact-name match
+    ranked.length === 1 || top.score >= 0.66 && (!runnerUp || top.score - runnerUp.score >= 0.34);
+    if (isConfident) {
+      resolved.push(top.id);
+    } else {
+      ambiguities.push({
+        location_text: originalText,
+        matches: ranked.slice(0, 5)
+      });
+    }
+  }
+  return { resolved, ambiguities };
+}
+
 // ../core/dist/composite/pull-followups.js
 function normalizeLinkedinPage4(v) {
   if (v == null)
@@ -5460,6 +6566,23 @@ function augmentContact(c) {
     linkedin_page: normalizeLinkedinPage4(c.linkedin_page ?? null)
   };
 }
+function mergeLocationIds(filter, ids) {
+  const criteria = filter?.criteria ? [...filter.criteria] : [];
+  const idx = criteria.findIndex((c) => c?.type === "location_ids" && c?.is_excluded === false);
+  if (idx >= 0) {
+    const cur = criteria[idx];
+    const existing = Array.isArray(cur.locations) ? cur.locations : [];
+    const merged = Array.from(/* @__PURE__ */ new Set([...existing, ...ids]));
+    criteria[idx] = { ...cur, locations: merged };
+  } else {
+    criteria.push({
+      type: "location_ids",
+      is_excluded: false,
+      locations: ids
+    });
+  }
+  return { criteria };
+}
 var pullFollowups = {
   name: "leadbay_pull_followups",
   annotations: {
@@ -5503,6 +6626,14 @@ var pullFollowups = {
             items: { type: "object" }
           }
         }
+      },
+      city: {
+        type: "string",
+        description: "Free-text city / region (e.g. 'Berlin', 'NYC', 'S\xE3o Paulo'). The composite resolves it to an admin_area id via GET /geo/search and merges it into the active Monitor filter as a `location_ids` FilterCriterion. Ambiguous matches surface as `status: 'ambiguous_locations'` with `location_ambiguities[]` \u2014 the agent picks an id and re-calls via `city_id`."
+      },
+      city_id: {
+        type: "string",
+        description: "Pre-resolved admin_area id (numeric string). Use when the user / agent has already picked one of the ambiguity candidates. Bypasses the resolver."
       }
     },
     additionalProperties: false
@@ -5527,6 +6658,15 @@ var pullFollowups = {
         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."
       },
+      status: {
+        type: "string",
+        description: "`ambiguous_locations` when a passed `city` matched multiple admin_areas; the agent picks an id from `location_ambiguities` and re-calls with `city_id`. Absent on the happy path."
+      },
+      location_ambiguities: {
+        type: "array",
+        description: "Per ambiguous city: {location_text, matches:[{id, name, country, level, score}]}. Only present when `status === 'ambiguous_locations'`.",
+        items: { type: "object" }
+      },
       _meta: {
         type: "object",
         description: "Operator context: region + last-call latency.",
@@ -5544,9 +6684,35 @@ var pullFollowups = {
     const liked = params.liked ?? false;
     const page = params.page ?? 0;
     const count = Math.min(params.count ?? 20, 200);
-    if (params.set_filter) {
+    let effectiveSetFilter = params.set_filter;
+    const geoTexts = [];
+    if (params.city)
+      geoTexts.push(params.city);
+    if (params.city_id)
+      geoTexts.push(params.city_id);
+    if (geoTexts.length > 0) {
+      const { resolved, ambiguities } = await resolveLocations(client, geoTexts);
+      if (ambiguities.length > 0) {
+        return {
+          status: "ambiguous_locations",
+          location_ambiguities: ambiguities,
+          leads: [],
+          active_filters: null,
+          pagination: null,
+          total_excluded_by_pushback: 0,
+          _meta: {
+            region: client.region,
+            latency_ms: client.lastMeta?.latency_ms ?? null
+          }
+        };
+      }
+      if (resolved.length > 0) {
+        effectiveSetFilter = mergeLocationIds(effectiveSetFilter, resolved);
+      }
+    }
+    if (effectiveSetFilter) {
       try {
-        await client.requestVoid("POST", "/monitor/filter", params.set_filter);
+        await client.requestVoid("POST", "/monitor/filter", effectiveSetFilter);
       } catch (err) {
         ctx?.logger?.warn?.(`pull_followups: POST /monitor/filter failed: ${err?.message ?? err?.code ?? err}`);
       }
@@ -5606,7 +6772,28 @@ var pullFollowups = {
   }
 };
 
-// ../core/dist/composite/research-lead.js
+// ../core/dist/composite/followups-map.js
+var followupsMap = {
+  name: "leadbay_followups_map",
+  // NO ui binding — see the file-level comment above. The agent
+  // routes into host-native widgets via the description's RENDER
+  // directives instead of an auto-rendered MCP Apps widget.
+  annotations: {
+    title: "Plot follow-up leads on a map (travel / in-person intent)",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_followups_map,
+  // Delegate everything else verbatim — same params, same output, same
+  // city resolver / set_filter / pushback exclusion behavior.
+  inputSchema: pullFollowups.inputSchema,
+  outputSchema: pullFollowups.outputSchema,
+  execute: pullFollowups.execute
+};
+
+// ../core/dist/composite/research-lead-by-id.js
 function normalizeLinkedinPage5(v) {
   if (v == null)
     return null;
@@ -5661,18 +6848,33 @@ ${firm.short_description}`);
     }
   }
   const contacts = shape.contacts ?? {};
-  const enriched = Array.isArray(contacts.enriched) ? contacts.enriched : [];
-  if (enriched.length > 0) {
+  const reachable = Array.isArray(contacts.reachable) ? contacts.reachable : [];
+  if (reachable.length > 0) {
     out.push(`
-## Contacts (enriched)`);
-    for (const c of enriched.slice(0, 10)) {
+## Contacts \u2014 reachable now`);
+    for (const c of reachable.slice(0, 10)) {
       const fn = c.first_name ?? "";
       const ln = c.last_name ?? "";
       const title = c.job_title ?? "\u2014";
-      const email = c.email ?? "no email";
-      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${email}`);
+      const channel = c.email ?? c.phone_number ?? "\u2014";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${channel}`);
     }
   }
+  const candidates = Array.isArray(contacts.candidates) ? contacts.candidates : [];
+  if (candidates.length > 0) {
+    out.push(`
+## Contacts \u2014 candidates (need enrichment)`);
+    for (const c of candidates.slice(0, 10)) {
+      const fn = c.first_name ?? "";
+      const ln = c.last_name ?? "";
+      const title = c.job_title ?? "\u2014";
+      const li = c.linkedin_page ? `LinkedIn` : "no LinkedIn";
+      out.push(`- **${(fn + " " + ln).trim() || "(unknown)"}** \u2014 ${title} \xB7 ${li}`);
+    }
+    if (candidates.length > 10)
+      out.push(`- _${candidates.length - 10} more \u2026_`);
+  }
+  const recentActivities = Array.isArray(shape.recent_activities) ? shape.recent_activities : [];
   const engagement = shape.engagement ?? {};
   const counts = [
     ["notes", engagement.notes_count],
@@ -5680,7 +6882,7 @@ ${firm.short_description}`);
     ["prospecting", engagement.prospecting_actions_count]
   ];
   const activeCounts = counts.filter(([, v]) => typeof v === "number" && v > 0);
-  if (activeCounts.length > 0 || engagement.liked || engagement.disliked) {
+  if (activeCounts.length > 0 || engagement.liked || engagement.disliked || recentActivities.length > 0) {
     out.push(`
 ## Engagement`);
     if (engagement.liked)
@@ -5690,6 +6892,15 @@ ${firm.short_description}`);
     for (const [k, v] of activeCounts) {
       out.push(`- ${k}: ${v}`);
     }
+    if (recentActivities.length > 0) {
+      out.push(`
+### Recent activity`);
+      for (const a of recentActivities.slice(0, 10)) {
+        const type = a.type ?? "?";
+        const date = a.date ?? "";
+        out.push(`- ${type} \xB7 ${date}`);
+      }
+    }
   }
   if (shape.truncated) {
     out.push(`
@@ -5729,16 +6940,23 @@ function reshapeWebFetchContent(content) {
   });
   return sections;
 }
-var researchLead = {
-  name: "leadbay_research_lead",
+function isReachable(c) {
+  if (!c)
+    return false;
+  const email = typeof c.email === "string" ? c.email.trim() : "";
+  const phone = typeof c.phone_number === "string" ? c.phone_number.trim() : "";
+  return email.length > 0 || phone.length > 0;
+}
+var researchLeadById = {
+  name: "leadbay_research_lead_by_id",
   annotations: {
-    title: "Research a Leadbay lead in depth",
+    title: "Research a Leadbay lead in depth (by UUID)",
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true
   },
-  description: leadbay_research_lead,
+  description: leadbay_research_lead_by_id,
   inputSchema: {
     type: "object",
     properties: {
@@ -5889,16 +7107,31 @@ var researchLead = {
       },
       contacts: {
         type: "object",
-        description: "Two-tier contact set: `enriched` (paid contacts known on this lens for this lead) and `org` (org-level contacts visible beyond the lens).",
+        description: "Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend's paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable.",
         properties: {
-          enriched: { type: "array", items: { type: "object" } },
-          org: { type: "array", items: { type: "object" } }
+          reachable: { type: "array", items: { type: "object" } },
+          candidates: { type: "array", items: { type: "object" } }
         },
         additionalProperties: false
       },
+      recent_activities: {
+        type: "array",
+        description: "Unified activity timeline (top 20 most recent) from /leads/{id}/activities. Each entry: {type, date}. Replaces the per-category recent_notes/recent_epilogue/recent_prospecting arrays from the prior schema \u2014 counts stay on `engagement` as the cheap signal.",
+        items: {
+          type: "object",
+          properties: {
+            type: { type: "string" },
+            date: { type: "string" }
+          }
+        }
+      },
+      web_insights_fetched_at: {
+        type: ["string", "null"],
+        description: "ISO timestamp of the latest /web_fetch run. Use as a staleness signal \u2014 if older than 30 days, offer to refresh."
+      },
       engagement: {
         type: "object",
-        description: "What humans/prior agent runs already did: liked/disliked flags, recommended_contact, counts (notes/epilogue/prospecting), and the most-recent items (recent_notes, recent_epilogue, recent_prospecting). Counts > 0 trigger conditional fan-out for the recent_* fields.",
+        description: "What humans/prior agent runs already did: liked/disliked flags, recommended_contact, and counts (notes/epilogue/prospecting). Recent items live in `recent_activities` at the top level.",
         properties: {
           liked: { type: "boolean" },
           disliked: { type: "boolean" },
@@ -5906,27 +7139,38 @@ var researchLead = {
           recommended_contact: { type: ["object", "null"] },
           notes_count: { type: "number" },
           epilogue_actions_count: { type: "number" },
-          prospecting_actions_count: { type: "number" },
-          recent_notes: { type: "array", items: { type: "object" } },
-          recent_epilogue: { type: "array", items: { type: "object" } },
-          recent_prospecting: { type: "array", items: { type: "object" } }
+          prospecting_actions_count: { type: "number" }
         },
         additionalProperties: false
       },
       _meta: {
         type: "object",
-        description: "Operator context: region (us/fr/custom), lens_id (the lens used for the lead-by-id fetch), web_fetch_in_progress (true if the backend is still hydrating signals).",
+        description: "Operator context: region (us/fr/custom), lens_id (the lens used for the lead-by-id fetch), web_fetch_in_progress (true if the backend is still hydrating signals), has_reachable_contact (true if at least one contact or recommended_contact has email or phone \u2014 drives NEXT STEPS routing between enrichment vs outreach). When the call was routed via leadbay_research_lead_by_name_fuzzy, also: resolved_from='companyName', resolved_query='<needle>', match_candidates=[{leadId,name,score}].",
         properties: {
           region: { type: "string" },
           lens_id: { type: "number" },
-          web_fetch_in_progress: { type: "boolean" }
+          web_fetch_in_progress: { type: "boolean" },
+          has_reachable_contact: { type: "boolean" },
+          resolved_from: { type: ["string", "null"] },
+          resolved_query: { type: ["string", "null"] },
+          match_candidates: {
+            type: ["array", "null"],
+            items: { type: "object" }
+          }
         },
         additionalProperties: false
       }
     },
-    required: ["qualification", "signals", "firmographics", "contacts", "engagement"]
+    required: [
+      "qualification",
+      "signals",
+      "firmographics",
+      "contacts",
+      "engagement",
+      "recent_activities"
+    ]
   },
-  execute: async (client, params, ctx) => {
+  execute: async (client, params, _ctx) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
     const leadId = params.leadId;
     void client.request("POST", "/interactions", [
@@ -5934,28 +7178,18 @@ var researchLead = {
       { type: "LEAD_CLICKED", leadId, lensId: String(lensId) }
     ]).catch(() => {
     });
-    const [profileR, qualR, contactsR, webFetchR] = await Promise.allSettled([
+    const [profileR, qualR, contactsR, webFetchR, activitiesR, orgContactsR] = await Promise.allSettled([
       client.request("GET", `/lenses/${lensId}/leads/${leadId}`),
       client.request("GET", `/leads/${leadId}/ai_agent_responses`),
       client.request("GET", `/leads/${leadId}/enrich/contacts?IncludeEnriched=true`),
-      client.request("GET", `/leads/${leadId}/web_fetch`)
+      client.request("GET", `/leads/${leadId}/web_fetch`),
+      client.request("GET", `/leads/${leadId}/activities?count=20`),
+      client.request("GET", `/leads/${leadId}/contacts?IncludeEnriched=true`)
     ]);
     if (profileR.status === "rejected") {
       throw profileR.reason;
     }
     const lead = profileR.value;
-    const wantNotes = (lead.notes_count ?? 0) > 0;
-    const wantEpilogue = (lead.epilogue_actions_count ?? 0) > 0;
-    const wantProspecting = (lead.prospecting_actions_count ?? 0) > 0;
-    const wantOrgContacts = (lead.org_contacts_count ?? 0) > 0;
-    const engagementFetches = await Promise.allSettled([
-      wantNotes ? client.request("GET", `/leads/${leadId}/notes`) : Promise.resolve(null),
-      wantEpilogue ? client.request("GET", `/leads/${leadId}/epilogue_responses?count=10&page=0`) : Promise.resolve(null),
-      wantProspecting ? client.request("GET", `/leads/${leadId}/prospecting_actions?count=10&page=0`) : Promise.resolve(null),
-      wantOrgContacts ? client.request("GET", `/leads/${leadId}/contacts?IncludeEnriched=true`) : Promise.resolve(null)
-    ]);
-    const [notesR, epilogueR, prospR, orgContactsR] = engagementFetches;
-    const valOrNull = (r) => r.status === "fulfilled" ? r.value ?? null : null;
     let signals = reshapeWebFetchContent(webFetchR.status === "fulfilled" ? webFetchR.value?.content ?? null : null);
     if (params.concise) {
       signals = signals.map((s) => ({
@@ -5964,7 +7198,42 @@ var researchLead = {
       })).filter((s) => s.entries.length > 0);
     }
     const paidContacts = contactsR.status === "fulfilled" ? contactsR.value : [];
-    const orgContacts = valOrNull(orgContactsR) ?? [];
+    const orgContacts = orgContactsR.status === "fulfilled" ? orgContactsR.value : [];
+    const shapePaid = (c) => ({
+      id: c.id,
+      first_name: c.first_name,
+      last_name: c.last_name,
+      job_title: c.job_title,
+      email: c.email,
+      phone_number: c.phone_number,
+      linkedin_page: normalizeLinkedinPage5(c.linkedin_page),
+      recommended: c.recommended,
+      enrichment_done: c.enrichment?.done ?? false,
+      source: "paid"
+    });
+    const shapeOrg = (c) => ({
+      id: c.id,
+      first_name: c.first_name,
+      last_name: c.last_name,
+      job_title: c.job_title,
+      email: c.email,
+      phone_number: c.phone_number ?? null,
+      linkedin_page: normalizeLinkedinPage5(c.linkedin_page ?? null),
+      recommended: c.recommended,
+      enrichment_done: true,
+      source: "org"
+    });
+    const allContacts = [
+      ...paidContacts.map(shapePaid),
+      ...orgContacts.map(shapeOrg)
+    ];
+    const reachableContacts = allContacts.filter((c) => isReachable(c));
+    const candidateContacts = allContacts.filter((c) => !isReachable(c));
+    const recommendedContact = lead.recommended_contact ? {
+      ...lead.recommended_contact,
+      linkedin_page: normalizeLinkedinPage5(lead.recommended_contact.linkedin_page ?? null)
+    } : null;
+    const hasReachableContact = reachableContacts.length > 0 || isReachable(recommendedContact);
     const TRUNCATE_CHAR_BUDGET = 25e3;
     let truncated = false;
     let truncationHint = null;
@@ -5987,14 +7256,10 @@ var researchLead = {
         }));
       }
     }
+    const recentActivities = activitiesR.status === "fulfilled" ? activitiesR.value.items.slice(0, 20).map((a) => ({ type: a.type, date: a.date })) : [];
+    const webFetchFetchedAt = webFetchR.status === "fulfilled" ? webFetchR.value?.fetch_at ?? null : null;
     return {
-      // 1) qualification — single most important block for "is this lead worth pursuing"
-      // boost_score is the canonical field (per AiAgentResponse.score). The valid
-      // set is the discrete -10/0/10/20 boost (see types.ts comment), NOT a 0-10
-      // average — the eval doc flagged the old `score_0_to_10` field name as
-      // misleading. We now ship `boost_score` as canonical alongside an explicit
-      // `score_scale` annotation; `score_0_to_10` is kept as a deprecated alias
-      // for one minor version (0.6.x) and removed in 0.7.0. See MIGRATION.md.
+      // 1) qualification
       qualification: qualR.status === "fulfilled" ? qualR.value.map((r) => ({
         question: r.question,
         boost_score: r.score,
@@ -6005,7 +7270,7 @@ var researchLead = {
         response: r.response,
         computed_at: r.computed_at
       })) : [],
-      // 2) signals — knowledge-base food (may be trimmed when truncated:true)
+      // 2) signals
       signals: signalsForReturn,
       truncated,
       truncation_hint: truncationHint,
@@ -6030,59 +7295,40 @@ var researchLead = {
         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.
+      // 4) contacts — partitioned by reachability (not by source endpoint)
       contacts: {
-        enriched: paidContacts.map((c) => ({
-          id: c.id,
-          first_name: c.first_name,
-          last_name: c.last_name,
-          job_title: c.job_title,
-          email: c.email,
-          phone_number: c.phone_number,
-          linkedin_page: normalizeLinkedinPage5(c.linkedin_page),
-          recommended: c.recommended,
-          enrichment_done: c.enrichment?.done ?? false
-        })),
-        org: orgContacts.map((c) => ({
-          id: c.id,
-          first_name: c.first_name,
-          last_name: c.last_name,
-          job_title: c.job_title,
-          email: c.email,
-          linkedin_page: normalizeLinkedinPage5(c.linkedin_page ?? null)
-        }))
-      },
-      // 5) engagement — what humans/prior agent runs already did.
-      // B8: `recommended_contact_title` dropped — it duplicates
-      // `recommended_contact.job_title` and just confused agents.
+        reachable: reachableContacts,
+        candidates: candidateContacts
+      },
+      // 5) unified recent activity timeline
+      recent_activities: recentActivities,
+      // 6) staleness signal (for "refresh research" NEXT STEPS row)
+      web_insights_fetched_at: webFetchFetchedAt,
+      // 7) engagement — counts + curation flags only; recent items live in
+      // recent_activities[].
       engagement: {
         liked: lead.liked,
         disliked: lead.disliked,
         new: lead.new ?? false,
-        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,
+        recommended_contact: recommendedContact,
         notes_count: lead.notes_count ?? 0,
         epilogue_actions_count: lead.epilogue_actions_count ?? 0,
-        prospecting_actions_count: lead.prospecting_actions_count ?? 0,
-        recent_notes: valOrNull(notesR)?.slice(0, 3) ?? [],
-        recent_epilogue: valOrNull(epilogueR)?.items?.slice(0, 3) ?? [],
-        recent_prospecting: valOrNull(prospR)?.items?.slice(0, 5) ?? []
+        prospecting_actions_count: lead.prospecting_actions_count ?? 0
       },
       _meta: {
         region: client.region,
         lens_id: lensId,
-        web_fetch_in_progress: webFetchR.status === "fulfilled" ? webFetchR.value?.in_progress : false
+        web_fetch_in_progress: webFetchR.status === "fulfilled" ? webFetchR.value?.in_progress : false,
+        has_reachable_contact: hasReachableContact,
+        resolved_from: params._resolved?.from ?? null,
+        resolved_query: params._resolved?.query ?? null,
+        match_candidates: params._resolved?.candidates ?? null
       }
     };
   }
 };
-var _innerExecute = researchLead.execute;
-researchLead.execute = async (client, params, ctx) => {
+var _innerExecute = researchLeadById.execute;
+researchLeadById.execute = async (client, params, ctx) => {
   const result = await _innerExecute(client, params, ctx);
   if (params.response_format !== "markdown")
     return result;
@@ -6097,6 +7343,92 @@ researchLead.execute = async (client, params, ctx) => {
   return envelope;
 };
 
+// ../core/dist/composite/research-lead-by-name-fuzzy.js
+function rankSubstringMatches(needle, candidates) {
+  const n = needle.toLowerCase();
+  const hits = candidates.filter((c) => typeof c.name === "string" && c.name.toLowerCase().includes(n));
+  hits.sort((a, b) => {
+    const aScore = a.score ?? -Infinity;
+    const bScore = b.score ?? -Infinity;
+    return bScore - aScore;
+  });
+  return hits;
+}
+var researchLeadByNameFuzzy = {
+  name: "leadbay_research_lead_by_name_fuzzy",
+  annotations: {
+    title: "Look up a lead by company name (fuzzy)",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_research_lead_by_name_fuzzy,
+  inputSchema: {
+    type: "object",
+    properties: {
+      companyName: {
+        type: "string",
+        description: "Company name to look up. Substring fuzzy-match against the top 50 of the active lens's wishlist; ties broken by descending lead score."
+      },
+      lensId: {
+        type: "number",
+        description: "Lens id (escape hatch \u2014 normally omit; auto-resolves to the active lens)"
+      },
+      concise: {
+        type: "boolean",
+        description: "Forwarded to leadbay_research_lead_by_id. If true, trims signals to hot=true items only."
+      },
+      response_format: {
+        type: "string",
+        enum: ["json", "markdown"],
+        description: "Forwarded to leadbay_research_lead_by_id. Default 'json'."
+      }
+    },
+    required: ["companyName"],
+    additionalProperties: false
+  },
+  // Output shape matches leadbay_research_lead_by_id; the only additions are
+  // _meta.resolved_from / resolved_query / match_candidates which are
+  // documented on _by_id's output schema. Defer to _by_id for the schema —
+  // duplicating it would just rot.
+  outputSchema: {
+    type: "object",
+    description: "Same shape as leadbay_research_lead_by_id, with _meta.resolved_from='companyName', _meta.resolved_query='<needle>', and _meta.match_candidates=[{leadId,name,score}] populated.",
+    additionalProperties: true
+  },
+  execute: async (client, params, ctx) => {
+    if (!params.companyName || typeof params.companyName !== "string") {
+      throw client.makeError("INVALID_PARAMS", "companyName is required", "Pass the company name as a string. If you already have the lead UUID, call leadbay_research_lead_by_id directly.");
+    }
+    const lensId = params.lensId ?? await client.resolveDefaultLens();
+    const results = await discoverLeads.execute(client, { lensId, count: 50, page: 0 }, ctx);
+    const allLeads = results.leads;
+    const ranked = rankSubstringMatches(params.companyName, allLeads);
+    if (ranked.length === 0) {
+      const nearestNames = [...allLeads].sort((a, b) => (b.score ?? -Infinity) - (a.score ?? -Infinity)).slice(0, 5).map((l) => ({ leadId: l.id, name: l.name, score: l.score }));
+      throw client.makeError("LEAD_NOT_FOUND", `No lead matching "${params.companyName}" in the current lens (top-50 wishlist)`, `Call leadbay_pull_leads to see what's available. Top-scoring leads currently in this lens: ${nearestNames.map((n) => n.name).join(", ")}.`);
+    }
+    const [primary, ...rest] = ranked;
+    const candidates = rest.slice(0, 4).map((m) => ({
+      leadId: m.id,
+      name: m.name,
+      score: m.score
+    }));
+    return await researchLeadById.execute(client, {
+      leadId: primary.id,
+      lensId,
+      concise: params.concise,
+      response_format: params.response_format,
+      _resolved: {
+        from: "companyName",
+        query: params.companyName,
+        candidates
+      }
+    }, ctx);
+  }
+};
+
 // ../core/dist/composite/recall-ordered-titles.js
 var recallOrderedTitles = {
   name: "leadbay_recall_ordered_titles",
@@ -8929,7 +10261,7 @@ var enrichTitles = {
           launched_at: bulkRecord?.launched_at,
           durability: bulkRecord?.durability,
           message: bulkRecord ? "Enrichment job launched. Backend has no server-side bulk_id yet; MCP minted a client-side bulk_id (persisted to disk by default) so you can poll via leadbay_bulk_enrich_status." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
-          next_action: bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead or leadbay_get_contacts on the leads you care about."
+          next_action: bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
         };
       } finally {
         try {
@@ -9211,9 +10543,9 @@ function bestMatches(text, taxonomy) {
   return ranked.slice(0, 5);
 }
 async function resolveSectors(client, texts) {
-  const looksLikeId = (s) => /^\d+$/.test(s);
-  const direct = texts.filter(looksLikeId);
-  const free = texts.filter((s) => !looksLikeId(s));
+  const looksLikeId2 = (s) => /^\d+$/.test(s);
+  const direct = texts.filter(looksLikeId2);
+  const free = texts.filter((s) => !looksLikeId2(s));
   if (free.length === 0)
     return { resolved: direct, ambiguities: [] };
   const me = await client.resolveMe().catch(() => null);
@@ -10032,6 +11364,7 @@ var granularReadTools = [
   getLensFilter,
   getLensScoring,
   listSectors,
+  listLocations,
   getUserPrompt,
   getClarification,
   getLeadNotes,
@@ -10040,7 +11373,9 @@ var granularReadTools = [
   getWebFetch,
   getSelectionIds,
   getEnrichmentJobTitles,
-  listMappableFields
+  listMappableFields,
+  createTopupLink,
+  openBillingPortal
 ];
 var granularWriteTools = [
   qualifyLead,
@@ -10065,7 +11400,9 @@ var granularWriteTools = [
   removePushback,
   previewBulkEnrichment,
   launchBulkEnrichment,
-  createCustomField
+  createCustomField,
+  likeLead,
+  dislikeLead
 ];
 var granularTools = [
   login,
@@ -10078,7 +11415,9 @@ granularTools.forEach((t) => {
 var compositeReadTools = [
   pullLeads,
   pullFollowups,
-  researchLead,
+  followupsMap,
+  researchLeadById,
+  researchLeadByNameFuzzy,
   recallOrderedTitles,
   accountStatus,
   bulkEnrichStatus,
@@ -10089,8 +11428,14 @@ var compositeReadTools = [
   // it for discoverability; expose it always-on so agents can find custom fields
   // without needing LEADBAY_MCP_ADVANCED=1.
   listMappableFields,
-  // Keep the existing composites available too.
-  researchCompany,
+  // Billing / top-up tools — granular-shaped but ALWAYS exposed because
+  // they're the canonical recovery path from a QUOTA_EXCEEDED wall. If
+  // they were gated behind LEADBAY_MCP_ADVANCED=1 the agent would
+  // know about the wall but not the door out. Read-only from the
+  // agent's POV (creating a Stripe session URL doesn't charge anyone;
+  // the user pays in their browser).
+  createTopupLink,
+  openBillingPortal,
   prepareOutreach
 ];
 var compositeWriteTools = [
@@ -10107,7 +11452,11 @@ var compositeWriteTools = [
   createCustomField,
   // addNote is granular-shaped but file-import prompts depend on it to preserve
   // meaningful source-file notes after imports return lead ids.
-  addNote
+  addNote,
+  // likeLead/dislikeLead are granular-shaped but should always be available
+  // to the agent without requiring LEADBAY_MCP_ADVANCED=1.
+  likeLead,
+  dislikeLead
 ];
 var compositeTools = [
   ...compositeReadTools,
@@ -10137,6 +11486,7 @@ export {
   getLensFilter,
   getLensScoring,
   listSectors,
+  listLocations,
   getUserPrompt,
   getClarification,
   getLeadNotes,
@@ -10147,6 +11497,8 @@ export {
   getEnrichmentJobTitles,
   importLeads,
   listMappableFields,
+  createTopupLink,
+  openBillingPortal,
   selectLeads,
   deselectLeads,
   clearSelection,
@@ -10167,11 +11519,14 @@ export {
   previewBulkEnrichment,
   launchBulkEnrichment,
   createCustomField,
-  researchCompany,
+  likeLead,
+  dislikeLead,
   prepareOutreach,
   pullLeads,
   pullFollowups,
-  researchLead,
+  followupsMap,
+  researchLeadById,
+  researchLeadByNameFuzzy,
   recallOrderedTitles,
   accountStatus,
   bulkQualifyLeads,