@leadbay/mcp 0.39.5 → 0.39.7

package/dist/bin.js

@@ -6169,13 +6169,11 @@ key. It survives a misspelled company name and is what turns "not in your
 list" into an answer. With only a contact email, pass \`email\`: the company
 domain is derived from it, consumer mailboxes ignored.
 
-When the registry cannot pick one company it returns \`{resolution:
-"ambiguous", query, candidates:[\u2026]}\` instead of a card. Ask which one; never
-guess from \`score\`.
-
-\`LEAD_NOT_FOUND\` is not a dead end: its hint names the field that would have
-found it \u2014 \`website\` or \`registry_number\`, both params. Ask for it and call
-again. Do not offer an import before asking.
+Both \`resolution\` answers below are successes, not cards. \`"ambiguous"\`
+carries \`candidates[]\`: ask which one, never guess from \`score\`.
+\`"not_found"\` carries \`summary\` + \`next_step\`: nobody has it, so say that and
+do what \`next_step\` says \u2014 usually ask for the param \`would_help\` names, then
+call again. Do not offer an import before asking.
 
 ---
 
@@ -6316,7 +6314,7 @@ out?"\`
 
 When \`resolution\` is \`"ambiguous"\`, render no card: use \`ask_user_input_v0\`,
 ONE \`single_select\` question ("Which one?"), one short label per candidate
-combining \`name\` and \`location\`.
+combining \`name\` and \`location\`. \`"not_found"\` renders no card either.
 
 When \`_meta.match_candidates\` is non-empty, prepend one extra NEXT STEPS row:
 
@@ -7088,17 +7086,18 @@ WHEN NOT TO USE: the user wants a lead list (leadbay_pull_leads / leadbay_pull_f
 `;
     leadbay_tour_plan = `## WHEN TO USE
 
-Trigger phrases: "visiting <city> in <N> days", "I'm in <city> next week / Tuesday \u2014 who's worth meeting", "I'm going to <city> \u2014 who should I see", "who's worth meeting in <city>", "field tour in <city>", "plan a tour in <city>", "who should I meet in <city>", "customers plus prospects in <city>", "tour itinerary".
+Trigger phrases: "visiting <city> in <N> days", "I'm in <city> next week / Tuesday \u2014 who's worth meeting", "I'm going to <city> \u2014 who should I see", "who's worth meeting in <city>", "field tour in <city>", "plan a tour in <city>", "who should I meet in <city>", "prospects within <N> km of <city>", "<city> and the surrounding area", "customers plus prospects in <city>", "tour itinerary".
 
 Do NOT use for: "follow-ups only, no new prospects" \u2192 \`leadbay_followups_map\`; "new leads only" \u2192 \`leadbay_pull_leads\`; "research one account" \u2192 \`leadbay_research_lead_by_id\`.
 
-Prefer when: user wants known accounts plus new discoveries in one geographic itinerary; NEVER a country name \u2014 unlike the Monitor tools, do NOT omit \`city\`; a city-less tour is arbitrary nationwide leads, so ask which city or region
+Prefer when: known accounts plus new discoveries in one itinerary; pass \`radius_km\` when they name a radius; NEVER a country name, and do NOT omit \`city\`: a city-less tour is arbitrary nationwide leads, so ask which city or region
 
 Examples that SHOULD invoke this tool:
 - "I'm flying to Limoges in 4 days \u2014 give me 3 customers, 3 qualified prospects, and 3 new high-potential."
 - "I'm in San Francisco next Tuesday. Who's worth meeting?"
 - "Plan my tour next Tuesday in Lyon: known accounts plus discoveries."
 - "Build a mixed itinerary for Berlin \u2014 I want both follow-ups and fresh leads."
+- "J'ai un rdv le 19 ao\xFBt \xE0 Colmar \u2014 trouve-moi les prospects dans un rayon de 10km."
 
 Examples that should NOT invoke this tool (sound similar, route elsewhere):
 - "Show me my follow-ups for the SF trip."
@@ -7153,6 +7152,8 @@ same instruction in its \`hint\`.
 
 **Counts**: \`followups_count\` (default 6 \u2014 generous so the agent can split into "customers + qualified" client-side) and \`discover_count\` (default 6 after client-side geo filter). The composite over-pulls Discover (30 raw) because the wishlist endpoint has no server-side geo filter \u2014 it then keeps the leads whose own \`location.city\` names the requested city, and falls back to \`location.state\` only when no city matched (which is what a regional ask like "Texas" or "\xCEle-de-France" looks like). \`location.country\` is never consulted. \`discover_filter_note\` reports the ratio and which field carried it, so the agent can be honest about coverage. **When it says no Discover lead is in the city, say that** \u2014 return the Monitor half and offer \`leadbay_find_new_leads\` for that city. Never fill the gap with leads from elsewhere.
 
+**The next town over**: a tour is a day of driving, so after the town's own leads are found the composite adds the Discover leads whose own coordinates put them within **\`radius_km\` (default 20)** of it \u2014 West Sacramento on a tour of Sacramento, Courbevoie and Ivry-sur-Seine on a tour of Paris. The town's own leads always come first. **Pass the user's own number when they give one** ("dans un rayon de 10km autour de Colmar" \u2192 \`radius_km: 10\`; "within 15 miles" \u2192 \`radius_km: 24\`), and \`radius_km: 0\` to keep the tour strictly inside the named town. The radius applies to Discover leads only; the Monitor half is scoped server-side and is untouched. When \`discover_filter_note\` splits the stops into "N in '<city>' and M in <other towns>", **repeat that split** \u2014 say which town each nearby stop is actually in rather than presenting every stop as being in the city the user named.
+
 **What \`tour_plan\` does NOT do**: it doesn't persist the tour as a campaign artifact. To do that \u2014 create a "Limoges Tour \u2013 May 24" campaign and attach the selected accounts \u2014 chain into \`leadbay_create_campaign({lead_ids: [...selected_ids], name: 'Limoges Tour \u2013 <date>'})\` after the user picks. See the \`leadbay_plan_tour_in_city\` prompt for the full end-to-end orchestrator.
 
 ---
@@ -15370,23 +15371,75 @@ function stateFieldOf(lead) {
   const state = lead?.location?.state;
   return typeof state === "string" ? normalizeGeo(state) : "";
 }
-function filterDiscoverByCity(leads, cityHint) {
+function posOf(lead) {
+  const pos = lead?.location?.pos;
+  const valid = Array.isArray(pos) && pos.length === 2 && pos.every((n) => typeof n === "number" && Number.isFinite(n));
+  return valid ? [pos[0], pos[1]] : null;
+}
+function distanceKm(a, b) {
+  const toRad = (d) => d * Math.PI / 180;
+  const dLat = toRad(b[0] - a[0]);
+  const dLng = toRad(b[1] - a[1]);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a[0])) * Math.cos(toRad(b[0])) * Math.sin(dLng / 2) ** 2;
+  return 2 * 6371 * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+function withinRadius(leads, anchors, radiusKm) {
+  if (anchors.length === 0 || !(radiusKm > 0))
+    return [];
+  return leads.filter((l) => {
+    const p = posOf(l);
+    return p !== null && anchors.some((a) => distanceKm(a, p) <= radiusKm);
+  });
+}
+function filterDiscoverByCity(leads, cityHint, monitorLeads, radiusKm) {
   const hint = cityHint ? cityHintCore(cityHint) : { name: "", isCity: false };
   if (!hint.name)
-    return { leads, matchedOn: null };
+    return { leads, matchedOn: null, nearby: [], anchored: false };
   const cityOf = (l) => typeof l?.location?.city === "string" ? townName(l.location.city) : "";
+  const positions = (ls) => ls.map(posOf).filter((p) => p !== null);
   const byCity = leads.filter((l) => cityOf(l) === hint.name);
-  if (byCity.length > 0)
-    return { leads: byCity, matchedOn: "city" };
-  if (hint.isCity)
-    return { leads: [], matchedOn: "city" };
-  const byState = leads.filter((l) => stateFieldOf(l) === hint.name);
-  return { leads: byState, matchedOn: "state" };
+  const anchors = positions([
+    ...byCity,
+    ...monitorLeads.filter((l) => cityOf(l) === hint.name)
+  ]);
+  if (byCity.length > 0) {
+    const inTown = new Set(byCity);
+    const nearby2 = withinRadius(leads.filter((l) => !inTown.has(l)), anchors, radiusKm);
+    return { leads: [...byCity, ...nearby2], matchedOn: "city", nearby: nearby2, anchored: true };
+  }
+  const anchored = anchors.length > 0;
+  if (!hint.isCity) {
+    const byState = leads.filter((l) => stateFieldOf(l) === hint.name);
+    if (byState.length > 0)
+      return { leads: byState, matchedOn: "state", nearby: [], anchored };
+  }
+  const nearby = withinRadius(leads, anchors, radiusKm);
+  if (nearby.length > 0)
+    return { leads: nearby, matchedOn: "city", nearby, anchored };
+  return {
+    leads: [],
+    matchedOn: hint.isCity ? "city" : "state",
+    nearby: [],
+    anchored
+  };
+}
+function townsOf(leads) {
+  const seen = [];
+  let unnamed = 0;
+  for (const l of leads) {
+    const city = typeof l?.location?.city === "string" ? l.location.city.trim() : "";
+    const name = city.replace(/^(?:City|Town|Village|Borough|Township|Municipality) of /i, "");
+    if (!name)
+      unnamed += 1;
+    else if (!seen.includes(name))
+      seen.push(name);
+  }
+  const rest = unnamed > 0 ? `${unnamed} whose record names no town` : "";
+  return [seen.join(", "), rest].filter(Boolean).join(", plus ");
 }
 function toMapLocation(lead, mode) {
-  const pos = lead?.location?.pos;
-  const valid = Array.isArray(pos) && pos.length === 2 && pos.every((n) => typeof n === "number");
-  if (!valid)
+  const pos = posOf(lead);
+  if (pos === null)
     return null;
   const loc = lead.location;
   const c = lead.recommended_contact;
@@ -15431,7 +15484,7 @@ function buildMap(monitorLeads, discoverLeads2) {
     }
   };
 }
-var DEFAULT_FOLLOWUPS_COUNT, DEFAULT_DISCOVER_COUNT, DISCOVER_OVER_PULL, ADMIN_PREFIX, tourPlan;
+var DEFAULT_FOLLOWUPS_COUNT, DEFAULT_DISCOVER_COUNT, DISCOVER_OVER_PULL, DEFAULT_RADIUS_KM, ADMIN_PREFIX, tourPlan;
 var init_tour_plan = __esm({
   "../core/dist/composite/tour-plan.js"() {
     "use strict";
@@ -15444,6 +15497,7 @@ var init_tour_plan = __esm({
     DEFAULT_FOLLOWUPS_COUNT = 6;
     DEFAULT_DISCOVER_COUNT = 6;
     DISCOVER_OVER_PULL = 30;
+    DEFAULT_RADIUS_KM = 20;
     ADMIN_PREFIX = /^(?:city|town|village|borough|township|municipality) of /;
     tourPlan = {
       name: "leadbay_tour_plan",
@@ -15473,6 +15527,10 @@ var init_tour_plan = __esm({
           discover_count: {
             type: "number",
             description: `Top-N Discover leads (active lens wishlist) to return after client-side city filter. Default ${DEFAULT_DISCOVER_COUNT}.`
+          },
+          radius_km: {
+            type: "number",
+            description: `How far outside the named town a Discover stop may be, in km. Default ${DEFAULT_RADIUS_KM}, which is roughly a metro area \u2014 it is what puts West Sacramento on a tour of Sacramento and Courbevoie on a tour of Paris. Pass the user's own number when they name one ("dans un rayon de 10km", "zone 20km", "within 15 miles" \u2192 24). Pass 0 to keep the tour inside the town's own name. Leads in the town itself always come first; the radius only adds to them. It applies to Discover leads only \u2014 the Monitor half is scoped server-side and is untouched.`
           }
         },
         additionalProperties: false
@@ -15489,12 +15547,12 @@ var init_tour_plan = __esm({
           },
           discover_leads: {
             type: "array",
-            description: "Fresh Discover leads from the active lens, filtered client-side to match the city. Pulls a larger candidate set internally to compensate for the missing server-side geo filter.",
+            description: "Fresh Discover leads from the active lens, filtered client-side to match the city, then extended with the ones whose own coordinates put them within `radius_km` of it. The town's own leads come first. Pulls a larger candidate set internally to compensate for the missing server-side geo filter.",
             items: { type: "object" }
           },
           discover_filter_note: {
             type: "string",
-            description: "Human-readable summary of the client-side geo filter applied to Discover leads (e.g. 'matched 3/30 by city/state')."
+            description: "Human-readable summary of the client-side geo filter applied to Discover leads. Says how many stops are in the named town, how many are within `radius_km` of it, and which towns those are in \u2014 repeat that split to the user rather than presenting every stop as being in the city they named."
           },
           map_locations: {
             type: "array",
@@ -15618,12 +15676,21 @@ var init_tour_plan = __esm({
         const cityName = params.city && !/^\d+$/.test(params.city.trim()) ? params.city : void 0;
         const knownId = params.city_id ?? (cityName ? void 0 : params.city);
         const idOnly = Boolean(knownId) && !cityName;
-        const { leads: filtered, matchedOn } = idOnly ? { leads: [], matchedOn: null } : filterDiscoverByCity(rawDiscover, cityName);
+        const radiusKm = params.radius_km ?? DEFAULT_RADIUS_KM;
+        const { leads: filtered, matchedOn, nearby, anchored } = idOnly ? {
+          leads: [],
+          matchedOn: null,
+          nearby: [],
+          anchored: false
+        } : filterDiscoverByCity(rawDiscover, cityName, monitorLeads, radiusKm);
         const discoverLeads2 = filtered.slice(0, discoverCount);
         const pulledLensId = leadsResult.status === "fulfilled" ? leadsResult.value?.lens?.id : null;
         if (pulledLensId != null) {
           reportLeadInteractions(client, pulledLensId, discoverLeads2.map((l) => l.id), ["LEAD_SEEN"], ctx?.logger);
         }
+        const nearbySet = new Set(nearby);
+        const nearShown = discoverLeads2.filter((l) => nearbySet.has(l));
+        const inTownShown = discoverLeads2.length - nearShown.length;
         let filterNote;
         if (idOnly) {
           filterNote = `Discover leads need the NAME of the place, and this call passed an area id (${knownId}) and no name. Re-call with \`city\` set to the name of that area, keeping \`city_id\` so the Monitor half stays on the area you picked. The follow-ups below are already scoped to it.`;
@@ -15631,10 +15698,16 @@ var init_tour_plan = __esm({
           filterNote = `No city filter applied; returning top ${discoverLeads2.length} Discover leads.`;
         } else if (matchedOn === null) {
           filterNote = `No usable city filter in '${params.city}'; returning top ${discoverLeads2.length} Discover leads.`;
+        } else if (filtered.length === 0 && anchored && radiusKm > 0) {
+          filterNote = `No Discover lead in the active lens names '${params.city}' as its town, and none is within ${radiusKm} km of the leads that do (checked ${rawDiscover.length} candidates). Say so; do NOT present leads from elsewhere as if they were in '${params.city}'.`;
         } else if (filtered.length === 0) {
           filterNote = `No Discover lead in the active lens is in '${params.city}' (checked ${rawDiscover.length} candidates by city, then by state/region). Say so; do NOT present leads from elsewhere as if they were in '${params.city}'.`;
+        } else if (nearShown.length > 0 && inTownShown === 0) {
+          filterNote = `No Discover lead in the active lens names '${params.city}' as its town; ${nearby.length}/${rawDiscover.length} are within ${radiusKm} km of it. Returning top ${discoverLeads2.length}, in ${townsOf(nearShown)}. Name the town each stop is actually in rather than calling them all '${params.city}'.`;
+        } else if (nearShown.length > 0) {
+          filterNote = `Matched ${filtered.length - nearby.length}/${rawDiscover.length} Discover leads to '${params.city}' by city, plus ${nearby.length} within ${radiusKm} km of it. Returning top ${discoverLeads2.length}: ${inTownShown} in '${params.city}' and ${nearShown.length} in ${townsOf(nearShown)}. Name the town each nearby stop is in.`;
         } else {
-          filterNote = `Matched ${filtered.length}/${rawDiscover.length} Discover leads to '${params.city}' by ${matchedOn === "city" ? "city" : "state/region"}; returning top ${discoverLeads2.length}.`;
+          filterNote = `Matched ${filtered.length - nearby.length}/${rawDiscover.length} Discover leads to '${params.city}' by ${matchedOn === "city" ? "city" : "state/region"}; returning top ${discoverLeads2.length}.`;
         }
         return {
           city: params.city ?? null,
@@ -17122,7 +17195,7 @@ var init_research_lead_by_name_fuzzy = __esm({
       // of a research card.
       outputSchema: {
         type: "object",
-        description: "Same shape as leadbay_research_lead_by_id, with _meta.resolved_from='companyName'|'resolver', _meta.resolved_query='<needle>', _meta.resolved_matched_on=[...], and _meta.match_candidates=[{leadId,name,score}] populated. When the registry resolver cannot pick one company, returns {resolution:'ambiguous', query, candidates:[{leadId,name,website,location,registry_ids,score,matched_on}]} instead \u2014 ask the user which one, then call leadbay_research_lead_by_id.",
+        description: "Same shape as leadbay_research_lead_by_id, with _meta.resolved_from='companyName'|'resolver', _meta.resolved_query='<needle>', _meta.resolved_matched_on=[...], and _meta.match_candidates=[{leadId,name,score}] populated. When the registry resolver cannot pick one company, returns {resolution:'ambiguous', query, candidates:[{leadId,name,website,location,registry_ids,score,matched_on}]} instead \u2014 ask the user which one, then call leadbay_research_lead_by_id. When neither the user's leads nor the registry hold the company, returns {resolution:'not_found', query, summary, would_help, next_step} \u2014 a successful answer, not an error: do what next_step says, which is normally to ask the user for the field would_help names ('website' or 'registry_number') and call again. would_help is empty when the search was scoped to one lens, where the remedy is to drop the scope, not to ask the user for a field.",
         additionalProperties: true
       },
       execute: async (client, params, ctx) => {
@@ -17136,7 +17209,18 @@ var init_research_lead_by_name_fuzzy = __esm({
           if (scoped.length > 0) {
             return await delegate(scoped, params.lensId);
           }
-          throw client.makeError("LEAD_NOT_FOUND", `No lead matching "${query}" in lens ${params.lensId}`, "This lookup was intentionally restricted to the supplied lens. Omit lensId to search your visible leads across Discover, Monitor, and Activate and then the Leadbay company registry.");
+          return {
+            resolution: "not_found",
+            query,
+            summary: `No lead matching "${query}" in lens ${params.lensId}`,
+            would_help: [],
+            next_step: "This lookup was intentionally restricted to the supplied lens. Omit lensId to search your visible leads across Discover, Monitor, and Activate and then the Leadbay company registry.",
+            _meta: {
+              region: client.region,
+              lens_id: params.lensId,
+              resolved_query: query
+            }
+          };
         }
         async function delegate(matches, fallbackLens) {
           const [primary, ...rest] = matches;
@@ -17231,7 +17315,23 @@ var init_research_lead_by_name_fuzzy = __esm({
         const wanted = resolved.type === "none" && resolved.would_help.length > 0 ? resolved.would_help : ["website", "registry_number"];
         const asks = wanted.map((f) => f === "registry_number" ? "a registry number (SIREN/SIRET) for `registry_number`" : f === "website" ? "the company website for `website`" : `\`${f}\``).join(" or ");
         const hint = resolved.type === "unidentifiable" ? `The registry could not identify a company from this input (${resolved.reason}). Ask the user for ${asks}, then call this tool again with it.` : `The registry found no company for what was supplied. It would match on ${asks}. Ask the user for that \u2014 "what's their website?" usually settles it \u2014 then call this tool again. Do not offer an import before asking.`;
-        throw client.makeError("LEAD_NOT_FOUND", `No company matching "${query}" ${searched}`, hint, "POST /leads/resolve");
+        if (!corpusSearched) {
+          throw client.makeError("LEAD_NOT_FOUND", `No company matching "${query}" ${searched}`, `${hint} But this lookup did not complete \u2014 the lead search route was unreachable, so their own leads were never checked. Retry once before telling the user the company is absent.`, "POST /leads/resolve");
+        }
+        return {
+          resolution: "not_found",
+          query,
+          resolver_payload: payload,
+          summary: `No company matching "${query}" ${searched}`,
+          would_help: wanted,
+          next_step: hint,
+          _meta: {
+            region: client.region,
+            resolved_from: "resolver",
+            resolved_query: query,
+            endpoint: "POST /leads/resolve"
+          }
+        };
       }
     };
   }
@@ -27260,7 +27360,7 @@ Split the returned \`monitor_leads\` into two buckets client-side using their en
 
 \`discover_leads\` are the **New** bucket.
 
-Aim for a 3+3+3 split if possible. If the customers bucket has fewer than 3, fill from qualified. If discover_filter_note indicates a low match ratio for the city, mention it: "Only N/30 fresh leads matched your city" \u2014 better honest than padded.
+Aim for a 3+3+3 split if possible. If the customers bucket has fewer than 3, fill from qualified. If discover_filter_note indicates a low match ratio for the city, mention it: "Only N/30 fresh leads matched your city" \u2014 better honest than padded. When it splits the stops into the ones in the city and the ones within \`radius_km\` of it, repeat that split and name the town each nearby stop is in \u2014 a company in Courbevoie is a stop on a Paris day, but it is not in Paris. If I named a radius ("within 10 km", "rayon de 20km"), pass it as \`radius_km\`.
 
 # PHASE 3 \u2014 PRESENT THE ITINERARY + OFFER THE MAP
 
@@ -27839,10 +27939,12 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 
 # PHASE 2 \u2014 NOT FOUND
-If the resolver returns \`LEAD_NOT_FOUND\`, read its hint: it names the field
-that would have found the company (\`would_help\`, usually \`website\`). **Ask the
-user for that field first** \u2014 "what's their website?" \u2014 and call the tool again
-with it. Only when they cannot supply it should you say both their leads and
+If the resolver returns \`resolution: "not_found"\`, that call SUCCEEDED \u2014 it is
+the answer, not a failure. Do what its \`next_step\` says. Usually that is to ask
+for the field \`would_help\` names (normally \`website\`): **ask the user for it
+first** \u2014 "what's their website?" \u2014 and call the tool again with it. When
+\`would_help\` is empty the search was scoped to one lens, and \`next_step\` says
+to drop the scope rather than to ask the user for anything. Only when they cannot supply it should you say both their leads and
 the Leadbay registry were searched.
 **Do NOT call \`leadbay_import_and_qualify\` automatically.**
 Offer to import and qualify as a separate, explicit next step; only call it
@@ -32035,7 +32137,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.39.5";
+var VERSION = "0.39.7";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -1531,7 +1531,7 @@ Split the returned \`monitor_leads\` into two buckets client-side using their en
 
 \`discover_leads\` are the **New** bucket.
 
-Aim for a 3+3+3 split if possible. If the customers bucket has fewer than 3, fill from qualified. If discover_filter_note indicates a low match ratio for the city, mention it: "Only N/30 fresh leads matched your city" \u2014 better honest than padded.
+Aim for a 3+3+3 split if possible. If the customers bucket has fewer than 3, fill from qualified. If discover_filter_note indicates a low match ratio for the city, mention it: "Only N/30 fresh leads matched your city" \u2014 better honest than padded. When it splits the stops into the ones in the city and the ones within \`radius_km\` of it, repeat that split and name the town each nearby stop is in \u2014 a company in Courbevoie is a stop on a Paris day, but it is not in Paris. If I named a radius ("within 10 km", "rayon de 20km"), pass it as \`radius_km\`.
 
 # PHASE 3 \u2014 PRESENT THE ITINERARY + OFFER THE MAP
 
@@ -2110,10 +2110,12 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 
 
 # PHASE 2 \u2014 NOT FOUND
-If the resolver returns \`LEAD_NOT_FOUND\`, read its hint: it names the field
-that would have found the company (\`would_help\`, usually \`website\`). **Ask the
-user for that field first** \u2014 "what's their website?" \u2014 and call the tool again
-with it. Only when they cannot supply it should you say both their leads and
+If the resolver returns \`resolution: "not_found"\`, that call SUCCEEDED \u2014 it is
+the answer, not a failure. Do what its \`next_step\` says. Usually that is to ask
+for the field \`would_help\` names (normally \`website\`): **ask the user for it
+first** \u2014 "what's their website?" \u2014 and call the tool again with it. When
+\`would_help\` is empty the search was scoped to one lens, and \`next_step\` says
+to drop the scope rather than to ask the user for anything. Only when they cannot supply it should you say both their leads and
 the Leadbay registry were searched.
 **Do NOT call \`leadbay_import_and_qualify\` automatically.**
 Offer to import and qualify as a separate, explicit next step; only call it
@@ -9117,13 +9119,11 @@ key. It survives a misspelled company name and is what turns "not in your
 list" into an answer. With only a contact email, pass \`email\`: the company
 domain is derived from it, consumer mailboxes ignored.
 
-When the registry cannot pick one company it returns \`{resolution:
-"ambiguous", query, candidates:[\u2026]}\` instead of a card. Ask which one; never
-guess from \`score\`.
-
-\`LEAD_NOT_FOUND\` is not a dead end: its hint names the field that would have
-found it \u2014 \`website\` or \`registry_number\`, both params. Ask for it and call
-again. Do not offer an import before asking.
+Both \`resolution\` answers below are successes, not cards. \`"ambiguous"\`
+carries \`candidates[]\`: ask which one, never guess from \`score\`.
+\`"not_found"\` carries \`summary\` + \`next_step\`: nobody has it, so say that and
+do what \`next_step\` says \u2014 usually ask for the param \`would_help\` names, then
+call again. Do not offer an import before asking.
 
 ---
 
@@ -9264,7 +9264,7 @@ out?"\`
 
 When \`resolution\` is \`"ambiguous"\`, render no card: use \`ask_user_input_v0\`,
 ONE \`single_select\` question ("Which one?"), one short label per candidate
-combining \`name\` and \`location\`.
+combining \`name\` and \`location\`. \`"not_found"\` renders no card either.
 
 When \`_meta.match_candidates\` is non-empty, prepend one extra NEXT STEPS row:
 
@@ -10036,17 +10036,18 @@ WHEN NOT TO USE: the user wants a lead list (leadbay_pull_leads / leadbay_pull_f
 `;
 var leadbay_tour_plan = `## WHEN TO USE
 
-Trigger phrases: "visiting <city> in <N> days", "I'm in <city> next week / Tuesday \u2014 who's worth meeting", "I'm going to <city> \u2014 who should I see", "who's worth meeting in <city>", "field tour in <city>", "plan a tour in <city>", "who should I meet in <city>", "customers plus prospects in <city>", "tour itinerary".
+Trigger phrases: "visiting <city> in <N> days", "I'm in <city> next week / Tuesday \u2014 who's worth meeting", "I'm going to <city> \u2014 who should I see", "who's worth meeting in <city>", "field tour in <city>", "plan a tour in <city>", "who should I meet in <city>", "prospects within <N> km of <city>", "<city> and the surrounding area", "customers plus prospects in <city>", "tour itinerary".
 
 Do NOT use for: "follow-ups only, no new prospects" \u2192 \`leadbay_followups_map\`; "new leads only" \u2192 \`leadbay_pull_leads\`; "research one account" \u2192 \`leadbay_research_lead_by_id\`.
 
-Prefer when: user wants known accounts plus new discoveries in one geographic itinerary; NEVER a country name \u2014 unlike the Monitor tools, do NOT omit \`city\`; a city-less tour is arbitrary nationwide leads, so ask which city or region
+Prefer when: known accounts plus new discoveries in one itinerary; pass \`radius_km\` when they name a radius; NEVER a country name, and do NOT omit \`city\`: a city-less tour is arbitrary nationwide leads, so ask which city or region
 
 Examples that SHOULD invoke this tool:
 - "I'm flying to Limoges in 4 days \u2014 give me 3 customers, 3 qualified prospects, and 3 new high-potential."
 - "I'm in San Francisco next Tuesday. Who's worth meeting?"
 - "Plan my tour next Tuesday in Lyon: known accounts plus discoveries."
 - "Build a mixed itinerary for Berlin \u2014 I want both follow-ups and fresh leads."
+- "J'ai un rdv le 19 ao\xFBt \xE0 Colmar \u2014 trouve-moi les prospects dans un rayon de 10km."
 
 Examples that should NOT invoke this tool (sound similar, route elsewhere):
 - "Show me my follow-ups for the SF trip."
@@ -10101,6 +10102,8 @@ same instruction in its \`hint\`.
 
 **Counts**: \`followups_count\` (default 6 \u2014 generous so the agent can split into "customers + qualified" client-side) and \`discover_count\` (default 6 after client-side geo filter). The composite over-pulls Discover (30 raw) because the wishlist endpoint has no server-side geo filter \u2014 it then keeps the leads whose own \`location.city\` names the requested city, and falls back to \`location.state\` only when no city matched (which is what a regional ask like "Texas" or "\xCEle-de-France" looks like). \`location.country\` is never consulted. \`discover_filter_note\` reports the ratio and which field carried it, so the agent can be honest about coverage. **When it says no Discover lead is in the city, say that** \u2014 return the Monitor half and offer \`leadbay_find_new_leads\` for that city. Never fill the gap with leads from elsewhere.
 
+**The next town over**: a tour is a day of driving, so after the town's own leads are found the composite adds the Discover leads whose own coordinates put them within **\`radius_km\` (default 20)** of it \u2014 West Sacramento on a tour of Sacramento, Courbevoie and Ivry-sur-Seine on a tour of Paris. The town's own leads always come first. **Pass the user's own number when they give one** ("dans un rayon de 10km autour de Colmar" \u2192 \`radius_km: 10\`; "within 15 miles" \u2192 \`radius_km: 24\`), and \`radius_km: 0\` to keep the tour strictly inside the named town. The radius applies to Discover leads only; the Monitor half is scoped server-side and is untouched. When \`discover_filter_note\` splits the stops into "N in '<city>' and M in <other towns>", **repeat that split** \u2014 say which town each nearby stop is actually in rather than presenting every stop as being in the city the user named.
+
 **What \`tour_plan\` does NOT do**: it doesn't persist the tour as a campaign artifact. To do that \u2014 create a "Limoges Tour \u2013 May 24" campaign and attach the selected accounts \u2014 chain into \`leadbay_create_campaign({lead_ids: [...selected_ids], name: 'Limoges Tour \u2013 <date>'})\` after the user picks. See the \`leadbay_plan_tour_in_city\` prompt for the full end-to-end orchestrator.
 
 ---
@@ -17758,6 +17761,7 @@ var followupsMap = {
 var DEFAULT_FOLLOWUPS_COUNT = 6;
 var DEFAULT_DISCOVER_COUNT = 6;
 var DISCOVER_OVER_PULL = 30;
+var DEFAULT_RADIUS_KM = 20;
 function normalizeGeo(value) {
   return value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
 }
@@ -17782,23 +17786,75 @@ function stateFieldOf(lead) {
   const state = lead?.location?.state;
   return typeof state === "string" ? normalizeGeo(state) : "";
 }
-function filterDiscoverByCity(leads, cityHint) {
+function posOf(lead) {
+  const pos = lead?.location?.pos;
+  const valid = Array.isArray(pos) && pos.length === 2 && pos.every((n) => typeof n === "number" && Number.isFinite(n));
+  return valid ? [pos[0], pos[1]] : null;
+}
+function distanceKm(a, b) {
+  const toRad = (d) => d * Math.PI / 180;
+  const dLat = toRad(b[0] - a[0]);
+  const dLng = toRad(b[1] - a[1]);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a[0])) * Math.cos(toRad(b[0])) * Math.sin(dLng / 2) ** 2;
+  return 2 * 6371 * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+function withinRadius(leads, anchors, radiusKm) {
+  if (anchors.length === 0 || !(radiusKm > 0))
+    return [];
+  return leads.filter((l) => {
+    const p = posOf(l);
+    return p !== null && anchors.some((a) => distanceKm(a, p) <= radiusKm);
+  });
+}
+function filterDiscoverByCity(leads, cityHint, monitorLeads, radiusKm) {
   const hint = cityHint ? cityHintCore(cityHint) : { name: "", isCity: false };
   if (!hint.name)
-    return { leads, matchedOn: null };
+    return { leads, matchedOn: null, nearby: [], anchored: false };
   const cityOf = (l) => typeof l?.location?.city === "string" ? townName(l.location.city) : "";
+  const positions = (ls) => ls.map(posOf).filter((p) => p !== null);
   const byCity = leads.filter((l) => cityOf(l) === hint.name);
-  if (byCity.length > 0)
-    return { leads: byCity, matchedOn: "city" };
-  if (hint.isCity)
-    return { leads: [], matchedOn: "city" };
-  const byState = leads.filter((l) => stateFieldOf(l) === hint.name);
-  return { leads: byState, matchedOn: "state" };
+  const anchors = positions([
+    ...byCity,
+    ...monitorLeads.filter((l) => cityOf(l) === hint.name)
+  ]);
+  if (byCity.length > 0) {
+    const inTown = new Set(byCity);
+    const nearby2 = withinRadius(leads.filter((l) => !inTown.has(l)), anchors, radiusKm);
+    return { leads: [...byCity, ...nearby2], matchedOn: "city", nearby: nearby2, anchored: true };
+  }
+  const anchored = anchors.length > 0;
+  if (!hint.isCity) {
+    const byState = leads.filter((l) => stateFieldOf(l) === hint.name);
+    if (byState.length > 0)
+      return { leads: byState, matchedOn: "state", nearby: [], anchored };
+  }
+  const nearby = withinRadius(leads, anchors, radiusKm);
+  if (nearby.length > 0)
+    return { leads: nearby, matchedOn: "city", nearby, anchored };
+  return {
+    leads: [],
+    matchedOn: hint.isCity ? "city" : "state",
+    nearby: [],
+    anchored
+  };
+}
+function townsOf(leads) {
+  const seen = [];
+  let unnamed = 0;
+  for (const l of leads) {
+    const city = typeof l?.location?.city === "string" ? l.location.city.trim() : "";
+    const name = city.replace(/^(?:City|Town|Village|Borough|Township|Municipality) of /i, "");
+    if (!name)
+      unnamed += 1;
+    else if (!seen.includes(name))
+      seen.push(name);
+  }
+  const rest = unnamed > 0 ? `${unnamed} whose record names no town` : "";
+  return [seen.join(", "), rest].filter(Boolean).join(", plus ");
 }
 function toMapLocation(lead, mode) {
-  const pos = lead?.location?.pos;
-  const valid = Array.isArray(pos) && pos.length === 2 && pos.every((n) => typeof n === "number");
-  if (!valid)
+  const pos = posOf(lead);
+  if (pos === null)
     return null;
   const loc = lead.location;
   const c = lead.recommended_contact;
@@ -17871,6 +17927,10 @@ var tourPlan = {
       discover_count: {
         type: "number",
         description: `Top-N Discover leads (active lens wishlist) to return after client-side city filter. Default ${DEFAULT_DISCOVER_COUNT}.`
+      },
+      radius_km: {
+        type: "number",
+        description: `How far outside the named town a Discover stop may be, in km. Default ${DEFAULT_RADIUS_KM}, which is roughly a metro area \u2014 it is what puts West Sacramento on a tour of Sacramento and Courbevoie on a tour of Paris. Pass the user's own number when they name one ("dans un rayon de 10km", "zone 20km", "within 15 miles" \u2192 24). Pass 0 to keep the tour inside the town's own name. Leads in the town itself always come first; the radius only adds to them. It applies to Discover leads only \u2014 the Monitor half is scoped server-side and is untouched.`
       }
     },
     additionalProperties: false
@@ -17887,12 +17947,12 @@ var tourPlan = {
       },
       discover_leads: {
         type: "array",
-        description: "Fresh Discover leads from the active lens, filtered client-side to match the city. Pulls a larger candidate set internally to compensate for the missing server-side geo filter.",
+        description: "Fresh Discover leads from the active lens, filtered client-side to match the city, then extended with the ones whose own coordinates put them within `radius_km` of it. The town's own leads come first. Pulls a larger candidate set internally to compensate for the missing server-side geo filter.",
         items: { type: "object" }
       },
       discover_filter_note: {
         type: "string",
-        description: "Human-readable summary of the client-side geo filter applied to Discover leads (e.g. 'matched 3/30 by city/state')."
+        description: "Human-readable summary of the client-side geo filter applied to Discover leads. Says how many stops are in the named town, how many are within `radius_km` of it, and which towns those are in \u2014 repeat that split to the user rather than presenting every stop as being in the city they named."
       },
       map_locations: {
         type: "array",
@@ -18016,12 +18076,21 @@ var tourPlan = {
     const cityName = params.city && !/^\d+$/.test(params.city.trim()) ? params.city : void 0;
     const knownId = params.city_id ?? (cityName ? void 0 : params.city);
     const idOnly = Boolean(knownId) && !cityName;
-    const { leads: filtered, matchedOn } = idOnly ? { leads: [], matchedOn: null } : filterDiscoverByCity(rawDiscover, cityName);
+    const radiusKm = params.radius_km ?? DEFAULT_RADIUS_KM;
+    const { leads: filtered, matchedOn, nearby, anchored } = idOnly ? {
+      leads: [],
+      matchedOn: null,
+      nearby: [],
+      anchored: false
+    } : filterDiscoverByCity(rawDiscover, cityName, monitorLeads, radiusKm);
     const discoverLeads2 = filtered.slice(0, discoverCount);
     const pulledLensId = leadsResult.status === "fulfilled" ? leadsResult.value?.lens?.id : null;
     if (pulledLensId != null) {
       reportLeadInteractions(client, pulledLensId, discoverLeads2.map((l) => l.id), ["LEAD_SEEN"], ctx?.logger);
     }
+    const nearbySet = new Set(nearby);
+    const nearShown = discoverLeads2.filter((l) => nearbySet.has(l));
+    const inTownShown = discoverLeads2.length - nearShown.length;
     let filterNote;
     if (idOnly) {
       filterNote = `Discover leads need the NAME of the place, and this call passed an area id (${knownId}) and no name. Re-call with \`city\` set to the name of that area, keeping \`city_id\` so the Monitor half stays on the area you picked. The follow-ups below are already scoped to it.`;
@@ -18029,10 +18098,16 @@ var tourPlan = {
       filterNote = `No city filter applied; returning top ${discoverLeads2.length} Discover leads.`;
     } else if (matchedOn === null) {
       filterNote = `No usable city filter in '${params.city}'; returning top ${discoverLeads2.length} Discover leads.`;
+    } else if (filtered.length === 0 && anchored && radiusKm > 0) {
+      filterNote = `No Discover lead in the active lens names '${params.city}' as its town, and none is within ${radiusKm} km of the leads that do (checked ${rawDiscover.length} candidates). Say so; do NOT present leads from elsewhere as if they were in '${params.city}'.`;
     } else if (filtered.length === 0) {
       filterNote = `No Discover lead in the active lens is in '${params.city}' (checked ${rawDiscover.length} candidates by city, then by state/region). Say so; do NOT present leads from elsewhere as if they were in '${params.city}'.`;
+    } else if (nearShown.length > 0 && inTownShown === 0) {
+      filterNote = `No Discover lead in the active lens names '${params.city}' as its town; ${nearby.length}/${rawDiscover.length} are within ${radiusKm} km of it. Returning top ${discoverLeads2.length}, in ${townsOf(nearShown)}. Name the town each stop is actually in rather than calling them all '${params.city}'.`;
+    } else if (nearShown.length > 0) {
+      filterNote = `Matched ${filtered.length - nearby.length}/${rawDiscover.length} Discover leads to '${params.city}' by city, plus ${nearby.length} within ${radiusKm} km of it. Returning top ${discoverLeads2.length}: ${inTownShown} in '${params.city}' and ${nearShown.length} in ${townsOf(nearShown)}. Name the town each nearby stop is in.`;
     } else {
-      filterNote = `Matched ${filtered.length}/${rawDiscover.length} Discover leads to '${params.city}' by ${matchedOn === "city" ? "city" : "state/region"}; returning top ${discoverLeads2.length}.`;
+      filterNote = `Matched ${filtered.length - nearby.length}/${rawDiscover.length} Discover leads to '${params.city}' by ${matchedOn === "city" ? "city" : "state/region"}; returning top ${discoverLeads2.length}.`;
     }
     return {
       city: params.city ?? null,
@@ -19447,7 +19522,7 @@ var researchLeadByNameFuzzy = {
   // of a research card.
   outputSchema: {
     type: "object",
-    description: "Same shape as leadbay_research_lead_by_id, with _meta.resolved_from='companyName'|'resolver', _meta.resolved_query='<needle>', _meta.resolved_matched_on=[...], and _meta.match_candidates=[{leadId,name,score}] populated. When the registry resolver cannot pick one company, returns {resolution:'ambiguous', query, candidates:[{leadId,name,website,location,registry_ids,score,matched_on}]} instead \u2014 ask the user which one, then call leadbay_research_lead_by_id.",
+    description: "Same shape as leadbay_research_lead_by_id, with _meta.resolved_from='companyName'|'resolver', _meta.resolved_query='<needle>', _meta.resolved_matched_on=[...], and _meta.match_candidates=[{leadId,name,score}] populated. When the registry resolver cannot pick one company, returns {resolution:'ambiguous', query, candidates:[{leadId,name,website,location,registry_ids,score,matched_on}]} instead \u2014 ask the user which one, then call leadbay_research_lead_by_id. When neither the user's leads nor the registry hold the company, returns {resolution:'not_found', query, summary, would_help, next_step} \u2014 a successful answer, not an error: do what next_step says, which is normally to ask the user for the field would_help names ('website' or 'registry_number') and call again. would_help is empty when the search was scoped to one lens, where the remedy is to drop the scope, not to ask the user for a field.",
     additionalProperties: true
   },
   execute: async (client, params, ctx) => {
@@ -19461,7 +19536,18 @@ var researchLeadByNameFuzzy = {
       if (scoped.length > 0) {
         return await delegate(scoped, params.lensId);
       }
-      throw client.makeError("LEAD_NOT_FOUND", `No lead matching "${query}" in lens ${params.lensId}`, "This lookup was intentionally restricted to the supplied lens. Omit lensId to search your visible leads across Discover, Monitor, and Activate and then the Leadbay company registry.");
+      return {
+        resolution: "not_found",
+        query,
+        summary: `No lead matching "${query}" in lens ${params.lensId}`,
+        would_help: [],
+        next_step: "This lookup was intentionally restricted to the supplied lens. Omit lensId to search your visible leads across Discover, Monitor, and Activate and then the Leadbay company registry.",
+        _meta: {
+          region: client.region,
+          lens_id: params.lensId,
+          resolved_query: query
+        }
+      };
     }
     async function delegate(matches, fallbackLens) {
       const [primary, ...rest] = matches;
@@ -19556,7 +19642,23 @@ var researchLeadByNameFuzzy = {
     const wanted = resolved.type === "none" && resolved.would_help.length > 0 ? resolved.would_help : ["website", "registry_number"];
     const asks = wanted.map((f) => f === "registry_number" ? "a registry number (SIREN/SIRET) for `registry_number`" : f === "website" ? "the company website for `website`" : `\`${f}\``).join(" or ");
     const hint = resolved.type === "unidentifiable" ? `The registry could not identify a company from this input (${resolved.reason}). Ask the user for ${asks}, then call this tool again with it.` : `The registry found no company for what was supplied. It would match on ${asks}. Ask the user for that \u2014 "what's their website?" usually settles it \u2014 then call this tool again. Do not offer an import before asking.`;
-    throw client.makeError("LEAD_NOT_FOUND", `No company matching "${query}" ${searched}`, hint, "POST /leads/resolve");
+    if (!corpusSearched) {
+      throw client.makeError("LEAD_NOT_FOUND", `No company matching "${query}" ${searched}`, `${hint} But this lookup did not complete \u2014 the lead search route was unreachable, so their own leads were never checked. Retry once before telling the user the company is absent.`, "POST /leads/resolve");
+    }
+    return {
+      resolution: "not_found",
+      query,
+      resolver_payload: payload,
+      summary: `No company matching "${query}" ${searched}`,
+      would_help: wanted,
+      next_step: hint,
+      _meta: {
+        region: client.region,
+        resolved_from: "resolver",
+        resolved_query: query,
+        endpoint: "POST /leads/resolve"
+      }
+    };
   }
 };
 
@@ -29308,7 +29410,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.39.5" : "0.0.0-dev";
+var VERSION = true ? "0.39.7" : "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

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

package/dist/installer-gui.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.39.5",
+  "version": "0.39.7",
   "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",