@leadbay/mcp 0.30.0 → 0.31.1

package/dist/bin.js

@@ -6832,8 +6832,10 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 \`queued\` \u2192 \u2705 "Queued <N> extra leads on lens <id>. Pull in ~30s." Do NOT
 list \`accepted_seeds\`; they're internal.
-\`quota_exceeded\` \u2192 render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`) (smaller
-count / wait until reset / upgrade).
+\`no_candidates\` \u2192 \u26D4 surface \`reason.message\`, name the criteria, offer
+\`leadbay_adjust_audience\`. Never re-call this tool on that lens.
+\`quota_exceeded\` \u2192 three options via the host's choice widget
+(smaller count / wait for reset / upgrade).
 \`refresh_in_progress\` \u2192 "lens is filling, retry in a minute".
 \`no_valid_seeds\` \u2192 silently re-call \`leadbay_seed_candidates\`, retry once.
 
@@ -6853,6 +6855,9 @@ Queue an additive extra-refill on a lens \u2014 more leads on the same criteria,
 - \`status: "quota_exceeded"\` \u2014 daily LENS_EXTRA_REFILL hit. Response carries \`quota: {used_today, resets_at}\` + a \`message\` to surface. **Render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`)**: (1) smaller \`extra_count\`, (2) wait until \`resets_at\`, (3) upgrade plan (TIER1=150, TIER2=1000). Do NOT silently retry.
 - \`status: "refresh_in_progress"\` \u2014 a refresh or extra-refill is already running. Tell the user to wait and call \`leadbay_pull_leads\` in ~30s.
 - \`status: "no_valid_seeds"\` \u2014 seeds went stale. Silently re-call \`leadbay_seed_candidates\` and retry once; only surface to the user if the second attempt also fails.
+- \`status: "no_candidates"\` \u2014 **the refill was NOT queued.** The lens's candidate pool is empty, so a refill would report success, consume no quota and deliver nothing. \`reason\` carries the same \`{code, message, retryable, criteria?, narrow_locations?}\` shape \`leadbay_pull_leads\` returns in \`empty_reason\`, with \`retryable: false\`. **Stop. Do not re-call this tool on this lens** \u2014 the outcome cannot change until the audience changes. Surface \`reason.message\`, name the criteria in play, and offer \`leadbay_adjust_audience\` (or \`leadbay_pull_followups\` when \`reason.code\` is \`no_new_leads\` and the lens already holds leads).
+
+**Extendability is checked before the write.** Every response carries \`available_count\` \u2014 how many leads a refill could still draw, read from the lens's own pool. \`0\` means the call was refused (\`no_candidates\`); \`null\` means the pool could not be read and the refill was queued anyway. An empty lens is NOT evidence of a broken refill: it is usually a lens that never had candidates. Reach for \`leadbay_adjust_audience\`, not another \`leadbay_extend_lens\`.
 
 WHEN TO USE: when the user has a bigger appetite than the daily lens fill delivers \u2014 they want MORE of the same kind of leads, on demand. Canonical phrasings: "I want more leads on this lens", "extend the lens", "give me a bigger batch today". The \`leadbay_extend_my_lens\` prompt is the user-facing entry point that orchestrates the whole flow.
 
@@ -6893,6 +6898,8 @@ Pick the row matching the response \`status\`. Seed-picking is internal; do NOT
 | \`quota_exceeded\`        | "Upgrade plan for a higher daily limit"                       | (no call \u2014 direct user to contact account manager / sales) |
 | \`refresh_in_progress\`   | "Lens is already filling \u2014 pull leads in a minute"            | \`leadbay_pull_leads()\` (after a short wait)            |
 | \`no_valid_seeds\`        | (silent retry \u2014 re-call \`leadbay_seed_candidates\` then \`leadbay_extend_lens\`) | internal \u2014 only surface if the second attempt also fails |
+| \`no_candidates\`         | "Widen the audience \u2014 this lens has nothing left to add"       | \`leadbay_adjust_audience()\` \u2014 never \`leadbay_extend_lens\` again |
+| \`no_candidates\` (\`reason.code: no_new_leads\`) | "Work the leads already in the lens"        | \`leadbay_pull_followups()\`                             |
 
 If nothing matches cleanly, default to "pull leads now to see what's queued" \u2014 never invent a tool that doesn't exist.
 `;
@@ -8596,6 +8603,11 @@ WHEN NOT TO USE: when the user has named a specific lens \u2014 pass \`lensId\`
 
 The active lens can change between calls (5-min cache + backend \`last_requested_lens\`). If a multi-step workflow depends on staying on one lens, **capture \`response.lens.id\` from the first response and pass it as the \`lensId\` argument on every subsequent Leadbay call** \u2014 including re-pulls, bulk qualifies, and research. (Field-name caveat: response nests it as \`lens.id\`; the parameter is \`lensId\`.) Re-pulling without \`lensId\` after a long-running tool may silently switch to a different lens and discard prior work.
 
+**EMPTY BATCH \u2014 route on \`empty_reason\`, never loop.** When \`leads\` is empty the response carries \`empty_reason: {code, message, retryable, criteria?, narrow_locations?}\`. \`retryable\` is the only field that decides what you do next:
+
+- \`retryable: true\` (always \`code: "computing"\`) \u2014 the lens is still building. Say so, pull ONCE more in ~30s. Do not call it empty.
+- \`retryable: false\` \u2014 no amount of re-pulling, lens-switching or \`leadbay_extend_lens\` can produce leads on these criteria. **Stop calling tools.** Surface \`message\` to the user, name the criteria from \`criteria\` (and \`narrow_locations\` first when present \u2014 a city-scale geo scope is the usual culprit), and offer \`leadbay_adjust_audience\` to widen. A refill on a zero-candidate lens answers "queued", consumes no quota and delivers nothing, so retrying reads as progress while achieving none (product#3995).
+
 ---
 
 ## RENDERING \u2014 markdown table, three columns, score-bar driven
@@ -16481,6 +16493,111 @@ var init_prepare_outreach = __esm({
   }
 });
 
+// ../core/dist/composite/_empty-lens-reason.js
+function criteriaOf(filter) {
+  return filter?.lens_filter?.items?.flatMap((i) => i.criteria ?? []) ?? [];
+}
+function summariseCriteria(criteria) {
+  const out = {};
+  for (const c of criteria) {
+    if (c.type === "sector_ids") {
+      const key = c.is_excluded ? "excluded_sector_ids" : "sector_ids";
+      out[key] = [...out[key] ?? [], ...c.sectors ?? []];
+    } else if (c.type === "location_ids") {
+      const key = c.is_excluded ? "excluded_location_ids" : "location_ids";
+      out[key] = [...out[key] ?? [], ...c.locations ?? []];
+    } else if (c.type === "size" && !c.is_excluded) {
+      out.sizes = [...out.sizes ?? [], ...c.sizes ?? []];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function narrowLocationsOf(filter, criteria) {
+  const included = new Set(criteria.filter((c) => c.type === "location_ids" && !c.is_excluded).flatMap((c) => c.locations ?? []));
+  if (included.size === 0)
+    return [];
+  const results = filter?.locations?.results ?? [];
+  return results.filter((r) => typeof r.id === "string" && included.has(r.id) && typeof r.level === "number" && r.level >= CITY_LEVEL).map((r) => ({
+    id: r.id,
+    name: typeof r.name === "string" ? r.name : "",
+    level: r.level
+  }));
+}
+function narrowGeoSentence(narrow) {
+  const names = narrow.map((n) => n.name).filter(Boolean);
+  if (names.length === 0)
+    return "";
+  return ` Its geography is pinned to ${names.join(", ")} \u2014 a city-scale area or smaller, which on an empty lens is almost always the criterion to relax first.`;
+}
+async function readAudienceShape(client, lensId) {
+  let filter = null;
+  try {
+    filter = await client.request("GET", `/lenses/${lensId}/filter`);
+  } catch {
+  }
+  const criteria = criteriaOf(filter);
+  const summary = summariseCriteria(criteria);
+  const narrow = narrowLocationsOf(filter, criteria);
+  return {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {},
+    geoSentence: narrowGeoSentence(narrow)
+  };
+}
+async function diagnoseEmptyLens(client, lensId, computing) {
+  if (computing.wishlist || computing.scores) {
+    return {
+      code: "computing",
+      retryable: true,
+      message: "This lens is still computing its leads. Pull again in ~30s \u2014 do NOT report it as empty yet."
+    };
+  }
+  let row;
+  try {
+    const lenses = await client.request("GET", "/lenses");
+    row = lenses.find((l) => String(l.id) === String(lensId));
+  } catch {
+  }
+  const { geoSentence: geo, ...extras } = await readAudienceShape(client, lensId);
+  const summary = extras.criteria;
+  if (row?.not_enough_lead_candidates) {
+    return {
+      code: "no_candidates",
+      retryable: false,
+      message: "This lens's criteria match no companies in the database, so it cannot fill." + geo + " Tell the user and offer to widen the audience (leadbay_adjust_audience) \u2014 extending or re-pulling will not help.",
+      ...extras
+    };
+  }
+  if (row?.not_enough_new_leads) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: "Every company matching this lens has already been delivered \u2014 there are no NEW leads left on these criteria. Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the existing leads via leadbay_pull_followups.",
+      ...extras
+    };
+  }
+  if (summary) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens is finished computing and holds zero leads: its criteria intersect to nothing." + geo + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience). Do NOT call leadbay_extend_lens \u2014 a refill on a zero-candidate lens reports queued, consumes no quota, and delivers nothing.",
+      ...extras
+    };
+  }
+  return {
+    code: "unknown",
+    retryable: false,
+    message: "This lens is finished computing and holds zero leads, and carries no audience criteria that would explain it. Report this to the user rather than retrying; leadbay_report_friction is the way to flag it to the Leadbay team."
+  };
+}
+var CITY_LEVEL;
+var init_empty_lens_reason = __esm({
+  "../core/dist/composite/_empty-lens-reason.js"() {
+    "use strict";
+    CITY_LEVEL = 7;
+  }
+});
+
 // ../core/dist/composite/pull-leads.js
 function normalizeLinkedinPage3(v) {
   if (v == null)
@@ -16561,6 +16678,7 @@ var init_pull_leads = __esm({
   "../core/dist/composite/pull-leads.js"() {
     "use strict";
     init_agent_memory();
+    init_empty_lens_reason();
     init_tool_descriptions_generated();
     pullLeads = {
       name: "leadbay_pull_leads",
@@ -16626,6 +16744,34 @@ var init_pull_leads = __esm({
             type: "boolean",
             description: "True if scoring is still running."
           },
+          empty_reason: {
+            type: ["object", "null"],
+            description: "Why this LENS holds zero leads. null whenever leads were returned, and null when this page is empty only because it is past the end of a non-empty lens. `retryable` is the field to route on: true ONLY on code=computing (pull again in ~30s). On every other code re-pulling and leadbay_extend_lens are both futile \u2014 a refill on a zero-candidate lens answers 'queued', consumes no quota and delivers nothing \u2014 so surface `message` to the user and offer leadbay_adjust_audience instead of retrying.",
+            properties: {
+              code: {
+                type: "string",
+                description: "computing | no_candidates | no_new_leads | audience_too_narrow | unknown"
+              },
+              message: {
+                type: "string",
+                description: "The line to surface to the user."
+              },
+              retryable: {
+                type: "boolean",
+                description: "True only while the lens is still computing. False means no amount of re-pulling or extending can produce leads."
+              },
+              criteria: {
+                type: "object",
+                description: "The lens criteria in play \u2014 what the user would have to relax. Present when the lens carries any."
+              },
+              narrow_locations: {
+                type: "array",
+                description: "Include-locations that resolved to a city-scale area or smaller ({id, name, level}). On an empty lens, name these first: this is the fingerprint of a whole-country location that fell through to a same-named village (product#3951).",
+                items: { type: "object" }
+              }
+            },
+            required: ["code", "message", "retryable"]
+          },
           next_steps: {
             type: ["object", "null"],
             description: "Ready-made NEXT STEPS for the host's choice widget. Each option has a SHORT `label` (\u22645 words, fits AskUserQuestion's label cap on Claude cowork/Claude Code) and a full `description`. For AskUserQuestion (cowork/Claude Code) pass each option as {label, description}. For ask_user_input_v0 (Claude chat/ChatGPT, string-only options) use the `description` as the option string. Use these VERBATIM, in order \u2014 do NOT re-derive, reword, or render as prose when a widget tool exists. options[0] is the artifact offer (build the lead triage board) whenever the batch is non-empty; options[1] is the enrich offer (kind:enrich_top_leads \u2014 route it to leadbay_enrich_titles scoped to the leadIds JUST shown (pass leads[].id + the pinned lens.id) with NO titles, so it runs the no-spend discovery preview; quota is only spent after the user picks titles + confirms channels on a follow-up call). When the batch is empty but the lens is still computing (computing_wishlist/computing_scores true), this carries a 'Re-pull in ~30s' option (kind:repull_computing) plus 'Refine audience' \u2014 render the widget so the user waits rather than seeing 'no leads.' null only when the batch is empty AND nothing is computing (a genuinely empty / over-narrow lens).",
@@ -16726,6 +16872,11 @@ var init_pull_leads = __esm({
           computingWishlist: res.computing_wishlist,
           computingScores: res.computing_scores
         });
+        const lensIsEmpty = leadCount === 0 && (res.pagination?.total ?? 0) === 0;
+        const emptyReason = lensIsEmpty ? await diagnoseEmptyLens(client, lensId, {
+          wishlist: res.computing_wishlist,
+          scores: res.computing_scores
+        }) : null;
         return withAgentMemoryMeta(client, {
           lens: { id: lensId },
           leads: res.items.map((lead) => ({
@@ -16737,6 +16888,7 @@ var init_pull_leads = __esm({
           next_page: nextPage,
           computing_wishlist: res.computing_wishlist,
           computing_scores: res.computing_scores,
+          empty_reason: emptyReason,
           next_steps: nextSteps,
           _meta: {
             region: client.region,
@@ -24036,11 +24188,54 @@ async function readExtraRefillQuota(client) {
     return { count: null, resets_at: null };
   }
 }
+async function readAvailablePool(client, lensId) {
+  try {
+    const preview = await client.request("GET", `/lenses/${lensId}/extra_refill_preview`);
+    return typeof preview?.available_count === "number" ? preview.available_count : null;
+  } catch {
+    return null;
+  }
+}
+async function readLensLeadTotal(client, lensId) {
+  try {
+    const page = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=1&page=0`);
+    return typeof page?.pagination?.total === "number" ? page.pagination.total : null;
+  } catch {
+    return null;
+  }
+}
+function noCandidatesReason(held, shape) {
+  const { geoSentence, ...extras } = shape;
+  const futile = " Extending again is futile \u2014 a refill on a lens with an empty candidate pool reports queued, consumes no quota and delivers nothing.";
+  if (held === 0) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens holds no leads and has none left to add: its criteria intersect to nothing." + geoSentence + futile + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience).",
+      ...extras
+    };
+  }
+  if (held !== null) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: `Every company matching this lens has already been delivered \u2014 all ${held} of them \u2014 so there is nothing left to add.` + futile + " Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the leads already in the lens (leadbay_pull_followups).",
+      ...extras
+    };
+  }
+  return {
+    code: "no_candidates",
+    retryable: false,
+    message: "This lens has no candidates left to add." + geoSentence + futile + " Tell the user and offer to widen the audience (leadbay_adjust_audience).",
+    ...extras
+  };
+}
 var extendLens;
 var init_extend_lens = __esm({
   "../core/dist/composite/extend-lens.js"() {
     "use strict";
     init_tool_descriptions_generated();
+    init_empty_lens_reason();
     extendLens = {
       name: "leadbay_extend_lens",
       annotations: {
@@ -24077,7 +24272,7 @@ var init_extend_lens = __esm({
         properties: {
           status: {
             type: "string",
-            description: "queued | quota_exceeded | refresh_in_progress | no_valid_seeds"
+            description: "queued | no_candidates | quota_exceeded | refresh_in_progress | no_valid_seeds"
           },
           lens: {
             type: "object",
@@ -24092,6 +24287,35 @@ var init_extend_lens = __esm({
             type: "string",
             description: "Human-readable summary. On error statuses, this is the line to surface to the user."
           },
+          available_count: {
+            type: ["number", "null"],
+            description: "How many leads a refill on this lens could still draw, read from /extra_refill_preview before queueing. 0 means the refill was NOT queued (status=no_candidates). null means the pool could not be read and the refill was queued anyway."
+          },
+          reason: {
+            type: "object",
+            description: "Only present on status=no_candidates. Same shape and `code` vocabulary as leadbay_pull_leads' empty_reason, so one routing rule covers both tools.",
+            properties: {
+              code: {
+                type: "string",
+                description: "audience_too_narrow (lens holds nothing and its criteria intersect to nothing) | no_new_leads (everything matching has already been delivered) | no_candidates (pool is empty; which of the two could not be determined)"
+              },
+              message: { type: "string" },
+              retryable: {
+                type: "boolean",
+                description: "Always false here. Re-calling leadbay_extend_lens cannot change the outcome \u2014 widen the audience instead."
+              },
+              criteria: {
+                type: "object",
+                description: "The criteria in play, so the agent can name them."
+              },
+              narrow_locations: {
+                type: "array",
+                description: "Include-locations that resolved to city-scale or smaller \u2014 the usual thing to relax first.",
+                items: { type: "object" }
+              }
+            },
+            required: ["code", "message", "retryable"]
+          },
           quota: {
             type: "object",
             description: "Only present on status=quota_exceeded. Shows the org's daily LENS_EXTRA_REFILL state.",
@@ -24105,6 +24329,21 @@ var init_extend_lens = __esm({
       },
       execute: async (client, params) => {
         const lensId = params.lensId ?? await client.resolveDefaultLens();
+        const availableCount = await readAvailablePool(client, lensId);
+        if (availableCount === 0) {
+          const [shape, held] = await Promise.all([
+            readAudienceShape(client, lensId),
+            readLensLeadTotal(client, lensId)
+          ]);
+          const reason = noCandidatesReason(held, shape);
+          return {
+            status: "no_candidates",
+            lens: { id: lensId },
+            available_count: 0,
+            reason,
+            message: reason.message
+          };
+        }
         const body = {
           seed_lead_ids: params.seed_lead_ids ?? []
         };
@@ -24116,6 +24355,7 @@ var init_extend_lens = __esm({
           return {
             status: "queued",
             lens: { id: lensId },
+            available_count: availableCount,
             accepted_seeds: res.accepted_seeds,
             message: "Extra refill queued. Leads stream in asynchronously \u2014 call leadbay_pull_leads in ~30s to see them."
           };
@@ -31730,7 +31970,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.30.0";
+var VERSION = "0.31.1";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -9160,8 +9160,10 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 \`queued\` \u2192 \u2705 "Queued <N> extra leads on lens <id>. Pull in ~30s." Do NOT
 list \`accepted_seeds\`; they're internal.
-\`quota_exceeded\` \u2192 render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`) (smaller
-count / wait until reset / upgrade).
+\`no_candidates\` \u2192 \u26D4 surface \`reason.message\`, name the criteria, offer
+\`leadbay_adjust_audience\`. Never re-call this tool on that lens.
+\`quota_exceeded\` \u2192 three options via the host's choice widget
+(smaller count / wait for reset / upgrade).
 \`refresh_in_progress\` \u2192 "lens is filling, retry in a minute".
 \`no_valid_seeds\` \u2192 silently re-call \`leadbay_seed_candidates\`, retry once.
 
@@ -9181,6 +9183,9 @@ Queue an additive extra-refill on a lens \u2014 more leads on the same criteria,
 - \`status: "quota_exceeded"\` \u2014 daily LENS_EXTRA_REFILL hit. Response carries \`quota: {used_today, resets_at}\` + a \`message\` to surface. **Render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`)**: (1) smaller \`extra_count\`, (2) wait until \`resets_at\`, (3) upgrade plan (TIER1=150, TIER2=1000). Do NOT silently retry.
 - \`status: "refresh_in_progress"\` \u2014 a refresh or extra-refill is already running. Tell the user to wait and call \`leadbay_pull_leads\` in ~30s.
 - \`status: "no_valid_seeds"\` \u2014 seeds went stale. Silently re-call \`leadbay_seed_candidates\` and retry once; only surface to the user if the second attempt also fails.
+- \`status: "no_candidates"\` \u2014 **the refill was NOT queued.** The lens's candidate pool is empty, so a refill would report success, consume no quota and deliver nothing. \`reason\` carries the same \`{code, message, retryable, criteria?, narrow_locations?}\` shape \`leadbay_pull_leads\` returns in \`empty_reason\`, with \`retryable: false\`. **Stop. Do not re-call this tool on this lens** \u2014 the outcome cannot change until the audience changes. Surface \`reason.message\`, name the criteria in play, and offer \`leadbay_adjust_audience\` (or \`leadbay_pull_followups\` when \`reason.code\` is \`no_new_leads\` and the lens already holds leads).
+
+**Extendability is checked before the write.** Every response carries \`available_count\` \u2014 how many leads a refill could still draw, read from the lens's own pool. \`0\` means the call was refused (\`no_candidates\`); \`null\` means the pool could not be read and the refill was queued anyway. An empty lens is NOT evidence of a broken refill: it is usually a lens that never had candidates. Reach for \`leadbay_adjust_audience\`, not another \`leadbay_extend_lens\`.
 
 WHEN TO USE: when the user has a bigger appetite than the daily lens fill delivers \u2014 they want MORE of the same kind of leads, on demand. Canonical phrasings: "I want more leads on this lens", "extend the lens", "give me a bigger batch today". The \`leadbay_extend_my_lens\` prompt is the user-facing entry point that orchestrates the whole flow.
 
@@ -9221,6 +9226,8 @@ Pick the row matching the response \`status\`. Seed-picking is internal; do NOT
 | \`quota_exceeded\`        | "Upgrade plan for a higher daily limit"                       | (no call \u2014 direct user to contact account manager / sales) |
 | \`refresh_in_progress\`   | "Lens is already filling \u2014 pull leads in a minute"            | \`leadbay_pull_leads()\` (after a short wait)            |
 | \`no_valid_seeds\`        | (silent retry \u2014 re-call \`leadbay_seed_candidates\` then \`leadbay_extend_lens\`) | internal \u2014 only surface if the second attempt also fails |
+| \`no_candidates\`         | "Widen the audience \u2014 this lens has nothing left to add"       | \`leadbay_adjust_audience()\` \u2014 never \`leadbay_extend_lens\` again |
+| \`no_candidates\` (\`reason.code: no_new_leads\`) | "Work the leads already in the lens"        | \`leadbay_pull_followups()\`                             |
 
 If nothing matches cleanly, default to "pull leads now to see what's queued" \u2014 never invent a tool that doesn't exist.
 `;
@@ -10924,6 +10931,11 @@ WHEN NOT TO USE: when the user has named a specific lens \u2014 pass \`lensId\`
 
 The active lens can change between calls (5-min cache + backend \`last_requested_lens\`). If a multi-step workflow depends on staying on one lens, **capture \`response.lens.id\` from the first response and pass it as the \`lensId\` argument on every subsequent Leadbay call** \u2014 including re-pulls, bulk qualifies, and research. (Field-name caveat: response nests it as \`lens.id\`; the parameter is \`lensId\`.) Re-pulling without \`lensId\` after a long-running tool may silently switch to a different lens and discard prior work.
 
+**EMPTY BATCH \u2014 route on \`empty_reason\`, never loop.** When \`leads\` is empty the response carries \`empty_reason: {code, message, retryable, criteria?, narrow_locations?}\`. \`retryable\` is the only field that decides what you do next:
+
+- \`retryable: true\` (always \`code: "computing"\`) \u2014 the lens is still building. Say so, pull ONCE more in ~30s. Do not call it empty.
+- \`retryable: false\` \u2014 no amount of re-pulling, lens-switching or \`leadbay_extend_lens\` can produce leads on these criteria. **Stop calling tools.** Surface \`message\` to the user, name the criteria from \`criteria\` (and \`narrow_locations\` first when present \u2014 a city-scale geo scope is the usual culprit), and offer \`leadbay_adjust_audience\` to widen. A refill on a zero-candidate lens answers "queued", consumes no quota and delivers nothing, so retrying reads as progress while achieving none (product#3995).
+
 ---
 
 ## RENDERING \u2014 markdown table, three columns, score-bar driven
@@ -18328,6 +18340,105 @@ var prepareOutreach = {
   }
 };
 
+// ../core/dist/composite/_empty-lens-reason.js
+var CITY_LEVEL = 7;
+function criteriaOf(filter) {
+  return filter?.lens_filter?.items?.flatMap((i) => i.criteria ?? []) ?? [];
+}
+function summariseCriteria(criteria) {
+  const out = {};
+  for (const c of criteria) {
+    if (c.type === "sector_ids") {
+      const key = c.is_excluded ? "excluded_sector_ids" : "sector_ids";
+      out[key] = [...out[key] ?? [], ...c.sectors ?? []];
+    } else if (c.type === "location_ids") {
+      const key = c.is_excluded ? "excluded_location_ids" : "location_ids";
+      out[key] = [...out[key] ?? [], ...c.locations ?? []];
+    } else if (c.type === "size" && !c.is_excluded) {
+      out.sizes = [...out.sizes ?? [], ...c.sizes ?? []];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function narrowLocationsOf(filter, criteria) {
+  const included = new Set(criteria.filter((c) => c.type === "location_ids" && !c.is_excluded).flatMap((c) => c.locations ?? []));
+  if (included.size === 0)
+    return [];
+  const results = filter?.locations?.results ?? [];
+  return results.filter((r) => typeof r.id === "string" && included.has(r.id) && typeof r.level === "number" && r.level >= CITY_LEVEL).map((r) => ({
+    id: r.id,
+    name: typeof r.name === "string" ? r.name : "",
+    level: r.level
+  }));
+}
+function narrowGeoSentence(narrow) {
+  const names = narrow.map((n) => n.name).filter(Boolean);
+  if (names.length === 0)
+    return "";
+  return ` Its geography is pinned to ${names.join(", ")} \u2014 a city-scale area or smaller, which on an empty lens is almost always the criterion to relax first.`;
+}
+async function readAudienceShape(client, lensId) {
+  let filter = null;
+  try {
+    filter = await client.request("GET", `/lenses/${lensId}/filter`);
+  } catch {
+  }
+  const criteria = criteriaOf(filter);
+  const summary = summariseCriteria(criteria);
+  const narrow = narrowLocationsOf(filter, criteria);
+  return {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {},
+    geoSentence: narrowGeoSentence(narrow)
+  };
+}
+async function diagnoseEmptyLens(client, lensId, computing) {
+  if (computing.wishlist || computing.scores) {
+    return {
+      code: "computing",
+      retryable: true,
+      message: "This lens is still computing its leads. Pull again in ~30s \u2014 do NOT report it as empty yet."
+    };
+  }
+  let row;
+  try {
+    const lenses = await client.request("GET", "/lenses");
+    row = lenses.find((l) => String(l.id) === String(lensId));
+  } catch {
+  }
+  const { geoSentence: geo, ...extras } = await readAudienceShape(client, lensId);
+  const summary = extras.criteria;
+  if (row?.not_enough_lead_candidates) {
+    return {
+      code: "no_candidates",
+      retryable: false,
+      message: "This lens's criteria match no companies in the database, so it cannot fill." + geo + " Tell the user and offer to widen the audience (leadbay_adjust_audience) \u2014 extending or re-pulling will not help.",
+      ...extras
+    };
+  }
+  if (row?.not_enough_new_leads) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: "Every company matching this lens has already been delivered \u2014 there are no NEW leads left on these criteria. Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the existing leads via leadbay_pull_followups.",
+      ...extras
+    };
+  }
+  if (summary) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens is finished computing and holds zero leads: its criteria intersect to nothing." + geo + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience). Do NOT call leadbay_extend_lens \u2014 a refill on a zero-candidate lens reports queued, consumes no quota, and delivers nothing.",
+      ...extras
+    };
+  }
+  return {
+    code: "unknown",
+    retryable: false,
+    message: "This lens is finished computing and holds zero leads, and carries no audience criteria that would explain it. Report this to the user rather than retrying; leadbay_report_friction is the way to flag it to the Leadbay team."
+  };
+}
+
 // ../core/dist/composite/pull-leads.js
 function normalizeLinkedinPage3(v) {
   if (v == null)
@@ -18467,6 +18578,34 @@ var pullLeads = {
         type: "boolean",
         description: "True if scoring is still running."
       },
+      empty_reason: {
+        type: ["object", "null"],
+        description: "Why this LENS holds zero leads. null whenever leads were returned, and null when this page is empty only because it is past the end of a non-empty lens. `retryable` is the field to route on: true ONLY on code=computing (pull again in ~30s). On every other code re-pulling and leadbay_extend_lens are both futile \u2014 a refill on a zero-candidate lens answers 'queued', consumes no quota and delivers nothing \u2014 so surface `message` to the user and offer leadbay_adjust_audience instead of retrying.",
+        properties: {
+          code: {
+            type: "string",
+            description: "computing | no_candidates | no_new_leads | audience_too_narrow | unknown"
+          },
+          message: {
+            type: "string",
+            description: "The line to surface to the user."
+          },
+          retryable: {
+            type: "boolean",
+            description: "True only while the lens is still computing. False means no amount of re-pulling or extending can produce leads."
+          },
+          criteria: {
+            type: "object",
+            description: "The lens criteria in play \u2014 what the user would have to relax. Present when the lens carries any."
+          },
+          narrow_locations: {
+            type: "array",
+            description: "Include-locations that resolved to a city-scale area or smaller ({id, name, level}). On an empty lens, name these first: this is the fingerprint of a whole-country location that fell through to a same-named village (product#3951).",
+            items: { type: "object" }
+          }
+        },
+        required: ["code", "message", "retryable"]
+      },
       next_steps: {
         type: ["object", "null"],
         description: "Ready-made NEXT STEPS for the host's choice widget. Each option has a SHORT `label` (\u22645 words, fits AskUserQuestion's label cap on Claude cowork/Claude Code) and a full `description`. For AskUserQuestion (cowork/Claude Code) pass each option as {label, description}. For ask_user_input_v0 (Claude chat/ChatGPT, string-only options) use the `description` as the option string. Use these VERBATIM, in order \u2014 do NOT re-derive, reword, or render as prose when a widget tool exists. options[0] is the artifact offer (build the lead triage board) whenever the batch is non-empty; options[1] is the enrich offer (kind:enrich_top_leads \u2014 route it to leadbay_enrich_titles scoped to the leadIds JUST shown (pass leads[].id + the pinned lens.id) with NO titles, so it runs the no-spend discovery preview; quota is only spent after the user picks titles + confirms channels on a follow-up call). When the batch is empty but the lens is still computing (computing_wishlist/computing_scores true), this carries a 'Re-pull in ~30s' option (kind:repull_computing) plus 'Refine audience' \u2014 render the widget so the user waits rather than seeing 'no leads.' null only when the batch is empty AND nothing is computing (a genuinely empty / over-narrow lens).",
@@ -18567,6 +18706,11 @@ var pullLeads = {
       computingWishlist: res.computing_wishlist,
       computingScores: res.computing_scores
     });
+    const lensIsEmpty = leadCount === 0 && (res.pagination?.total ?? 0) === 0;
+    const emptyReason = lensIsEmpty ? await diagnoseEmptyLens(client, lensId, {
+      wishlist: res.computing_wishlist,
+      scores: res.computing_scores
+    }) : null;
     return withAgentMemoryMeta(client, {
       lens: { id: lensId },
       leads: res.items.map((lead) => ({
@@ -18578,6 +18722,7 @@ var pullLeads = {
       next_page: nextPage,
       computing_wishlist: res.computing_wishlist,
       computing_scores: res.computing_scores,
+      empty_reason: emptyReason,
       next_steps: nextSteps,
       _meta: {
         region: client.region,
@@ -25006,6 +25151,48 @@ async function readExtraRefillQuota(client) {
     return { count: null, resets_at: null };
   }
 }
+async function readAvailablePool(client, lensId) {
+  try {
+    const preview = await client.request("GET", `/lenses/${lensId}/extra_refill_preview`);
+    return typeof preview?.available_count === "number" ? preview.available_count : null;
+  } catch {
+    return null;
+  }
+}
+async function readLensLeadTotal(client, lensId) {
+  try {
+    const page = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=1&page=0`);
+    return typeof page?.pagination?.total === "number" ? page.pagination.total : null;
+  } catch {
+    return null;
+  }
+}
+function noCandidatesReason(held, shape) {
+  const { geoSentence, ...extras } = shape;
+  const futile = " Extending again is futile \u2014 a refill on a lens with an empty candidate pool reports queued, consumes no quota and delivers nothing.";
+  if (held === 0) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens holds no leads and has none left to add: its criteria intersect to nothing." + geoSentence + futile + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience).",
+      ...extras
+    };
+  }
+  if (held !== null) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: `Every company matching this lens has already been delivered \u2014 all ${held} of them \u2014 so there is nothing left to add.` + futile + " Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the leads already in the lens (leadbay_pull_followups).",
+      ...extras
+    };
+  }
+  return {
+    code: "no_candidates",
+    retryable: false,
+    message: "This lens has no candidates left to add." + geoSentence + futile + " Tell the user and offer to widen the audience (leadbay_adjust_audience).",
+    ...extras
+  };
+}
 var extendLens = {
   name: "leadbay_extend_lens",
   annotations: {
@@ -25042,7 +25229,7 @@ var extendLens = {
     properties: {
       status: {
         type: "string",
-        description: "queued | quota_exceeded | refresh_in_progress | no_valid_seeds"
+        description: "queued | no_candidates | quota_exceeded | refresh_in_progress | no_valid_seeds"
       },
       lens: {
         type: "object",
@@ -25057,6 +25244,35 @@ var extendLens = {
         type: "string",
         description: "Human-readable summary. On error statuses, this is the line to surface to the user."
       },
+      available_count: {
+        type: ["number", "null"],
+        description: "How many leads a refill on this lens could still draw, read from /extra_refill_preview before queueing. 0 means the refill was NOT queued (status=no_candidates). null means the pool could not be read and the refill was queued anyway."
+      },
+      reason: {
+        type: "object",
+        description: "Only present on status=no_candidates. Same shape and `code` vocabulary as leadbay_pull_leads' empty_reason, so one routing rule covers both tools.",
+        properties: {
+          code: {
+            type: "string",
+            description: "audience_too_narrow (lens holds nothing and its criteria intersect to nothing) | no_new_leads (everything matching has already been delivered) | no_candidates (pool is empty; which of the two could not be determined)"
+          },
+          message: { type: "string" },
+          retryable: {
+            type: "boolean",
+            description: "Always false here. Re-calling leadbay_extend_lens cannot change the outcome \u2014 widen the audience instead."
+          },
+          criteria: {
+            type: "object",
+            description: "The criteria in play, so the agent can name them."
+          },
+          narrow_locations: {
+            type: "array",
+            description: "Include-locations that resolved to city-scale or smaller \u2014 the usual thing to relax first.",
+            items: { type: "object" }
+          }
+        },
+        required: ["code", "message", "retryable"]
+      },
       quota: {
         type: "object",
         description: "Only present on status=quota_exceeded. Shows the org's daily LENS_EXTRA_REFILL state.",
@@ -25070,6 +25286,21 @@ var extendLens = {
   },
   execute: async (client, params) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
+    const availableCount = await readAvailablePool(client, lensId);
+    if (availableCount === 0) {
+      const [shape, held] = await Promise.all([
+        readAudienceShape(client, lensId),
+        readLensLeadTotal(client, lensId)
+      ]);
+      const reason = noCandidatesReason(held, shape);
+      return {
+        status: "no_candidates",
+        lens: { id: lensId },
+        available_count: 0,
+        reason,
+        message: reason.message
+      };
+    }
     const body = {
       seed_lead_ids: params.seed_lead_ids ?? []
     };
@@ -25081,6 +25312,7 @@ var extendLens = {
       return {
         status: "queued",
         lens: { id: lensId },
+        available_count: availableCount,
         accepted_seeds: res.accepted_seeds,
         message: "Extra refill queued. Leads stream in asynchronously \u2014 call leadbay_pull_leads in ~30s to see them."
       };
@@ -28307,7 +28539,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.30.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.1" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var logger = {

package/dist/installer-electron.js

@@ -1804,7 +1804,7 @@ var init_installer_gui = __esm({
     init_install_dxt();
     init_install_shared();
     init_oauth();
-    VERSION = true ? "0.30.0" : "0.0.0-dev";
+    VERSION = true ? "0.31.1" : "0.0.0-dev";
     MESSAGES = {
       en: {
         installer: {

package/dist/installer-gui.js

@@ -1067,7 +1067,7 @@ async function oauthLogin(opts) {
 }
 
 // installer/installer-gui.ts
-var VERSION = true ? "0.30.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.1" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",