@coldiq/mcp 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -16,8 +16,12 @@
     "version": "git add package.json package-lock.json",
     "postversion": "git commit -m \"chore(mcp): release $npm_package_version\" && git tag mcp-v$npm_package_version && git push && git push --tags"
   },
+  "engines": {
+    "node": ">=18.18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "undici": "^6.25.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {

package/src/client.ts

@@ -1,3 +1,5 @@
+import { Agent, setGlobalDispatcher } from 'undici'
+
 export type ApiResponse = {
   ok: boolean
   status: number
@@ -6,15 +8,29 @@ export type ApiResponse = {
 
 let _apiUrl: string
 let _apiKey: string
+let _httpTimeoutMs: number
 
 export function initClient(apiUrl?: string, apiKey?: string): void {
   _apiUrl = apiUrl ?? process.env.COLDIQ_API_URL ?? 'https://api.coldiq.com'
   _apiKey = apiKey ?? process.env.COLDIQ_API_KEY ?? ''
+  _httpTimeoutMs = parseInt(process.env.COLDIQ_HTTP_TIMEOUT_MS ?? '30000', 10)
   if (!_apiKey) {
     throw new Error('COLDIQ_API_KEY is required — set it in .mcp.json env or as an environment variable')
   }
   // Strip trailing slash
   _apiUrl = _apiUrl.replace(/\/+$/, '')
+
+  // Tune the global undici dispatcher: keep-alive + connection pool.
+  // pipelining: 1 — Cloudflare front-door does not reliably support HTTP/1.1 pipelining.
+  // connections: 32 — covers worst-case find_emails fan-out (50 people × 2 providers).
+  setGlobalDispatcher(
+    new Agent({
+      keepAliveTimeout: 30_000,
+      keepAliveMaxTimeout: 60_000,
+      connections: 32,
+      pipelining: 1,
+    }),
+  )
 }
 
 export async function callApi(
@@ -34,7 +50,11 @@ export async function callApi(
     Authorization: `Bearer ${_apiKey}`,
   }
 
-  const init: RequestInit = { method, headers }
+  const init: RequestInit = {
+    method,
+    headers,
+    signal: AbortSignal.timeout(_httpTimeoutMs),
+  }
 
   if (method === 'POST' && body !== undefined) {
     headers['Content-Type'] = 'application/json'
@@ -51,6 +71,16 @@ export async function callApi(
     }
     return { ok: res.ok, status: res.status, data }
   } catch (err) {
+    const isTimeout =
+      err instanceof Error &&
+      (err.name === 'AbortError' || err.name === 'TimeoutError')
+    if (isTimeout) {
+      return {
+        ok: false,
+        status: 0,
+        data: { error: 'Request timed out' },
+      }
+    }
     if (process.env.COLDIQ_DEBUG) {
       console.error(`[coldiq:debug] network error: ${err instanceof Error ? err.message : String(err)}`)
     }

package/src/executor.ts

@@ -51,6 +51,8 @@ async function executeAsync(
   payload: { body?: unknown; queryParams?: Record<string, string> },
 ): Promise<{ ok: boolean; data: unknown }> {
   const asyncCfg = provider.async!
+  const firstPollMs = parseInt(process.env.COLDIQ_FIRST_POLL_MS ?? '750', 10)
+  const maxPollErrors = parseInt(process.env.COLDIQ_MAX_POLL_ERRORS ?? '3', 10)
 
   // Step 1: create the job
   debug(`${provider.id} async: creating job...`)
@@ -70,28 +72,48 @@ async function executeAsync(
   if (!jobId) return { ok: false, data: { error: 'Empty job ID from async response' } }
   debug(`${provider.id} async: job created (${jobId}), polling...`)
 
-  // Step 3: poll until complete or timeout
+  // Step 3: poll until complete or timeout.
+  // First probe fires quickly — capped by both COLDIQ_FIRST_POLL_MS and the provider's
+  // configured first interval, so tests that set a short pollIntervalMs aren't blocked
+  // by the default 750ms.
   const deadline = Date.now() + asyncCfg.timeoutMs
   let pollCount = 0
+  let consecutivePollErrors = 0
+
+  const configuredFirstInterval = typeof asyncCfg.pollIntervalMs === 'function'
+    ? asyncCfg.pollIntervalMs(1)
+    : asyncCfg.pollIntervalMs
+  await sleep(Math.min(firstPollMs, configuredFirstInterval))
+
   while (Date.now() < deadline) {
+    const pollRes = await callApi('GET', asyncCfg.pollEndpoint(jobId))
+    pollCount++
+
+    if (!pollRes.ok) {
+      consecutivePollErrors++
+      if (consecutivePollErrors >= maxPollErrors) {
+        log(`${provider.id} async: poll failing (${consecutivePollErrors} consecutive errors), skipping`)
+        return { ok: false, data: { error: `Poll endpoint failed ${consecutivePollErrors} consecutive times` } }
+      }
+    } else {
+      consecutivePollErrors = 0
+      const status = (pollRes.data as Record<string, unknown>).status ?? 'unknown'
+      const progress = (pollRes.data as Record<string, unknown>).progress_percentage ?? '?'
+      debug(`${provider.id} async: poll #${pollCount} — status=${status}, progress=${progress}%`)
+
+      if (asyncCfg.isComplete(pollRes.data)) {
+        debug(`${provider.id} async: complete`)
+        return pollRes
+      }
+    }
+
+    if (Date.now() >= deadline) break
+
     const interval =
       typeof asyncCfg.pollIntervalMs === 'function'
         ? asyncCfg.pollIntervalMs(pollCount + 1)
         : asyncCfg.pollIntervalMs
     await sleep(interval)
-    pollCount++
-
-    const pollRes = await callApi('GET', asyncCfg.pollEndpoint(jobId))
-    if (!pollRes.ok) continue // transient poll errors — retry
-
-    const status = (pollRes.data as Record<string, unknown>).status ?? 'unknown'
-    const progress = (pollRes.data as Record<string, unknown>).progress_percentage ?? '?'
-    debug(`${provider.id} async: poll #${pollCount} — status=${status}, progress=${progress}%`)
-
-    if (asyncCfg.isComplete(pollRes.data)) {
-      debug(`${provider.id} async: complete`)
-      return pollRes
-    }
   }
 
   debug(`${provider.id} async: timed out after ${asyncCfg.timeoutMs / 1000}s`)

package/src/registry.ts

@@ -109,6 +109,60 @@ export function isoCountryToName(code: string): string {
   }
 }
 
+// Reverse lookup: English country name → ISO 3166-1 alpha-2. Built lazily on first use.
+// Agents routinely pass "Brazil" / "United States" instead of "BR" / "US" — without this
+// coercion, downstream providers that require ISO codes (LeadsFactory, BlitzAPI) silently
+// skip the filter.
+let _nameToCode: Map<string, string> | undefined
+function buildNameToCode(): Map<string, string> {
+  const map = new Map<string, string>()
+  // Iterate all ISO-2 codes A-Z × A-Z; keep those Intl.DisplayNames resolves.
+  for (let a = 65; a <= 90; a++) {
+    for (let b = 65; b <= 90; b++) {
+      const code = String.fromCharCode(a, b)
+      try {
+        const name = _displayNames.of(code)
+        if (name && name !== code) map.set(name.toLowerCase(), code)
+      } catch { /* skip */ }
+    }
+  }
+  // Common aliases not covered by Intl.DisplayNames defaults.
+  map.set('usa', 'US')
+  map.set('uk', 'GB')
+  map.set('south korea', 'KR')
+  map.set('north korea', 'KP')
+  map.set('russia', 'RU')
+  map.set('iran', 'IR')
+  map.set('syria', 'SY')
+  map.set('uae', 'AE')
+  map.set('emirates', 'AE')
+  return map
+}
+
+export function nameToIsoCountry(input: string): string | undefined {
+  if (typeof input !== 'string' || input.length === 0) return undefined
+  if (!_nameToCode) _nameToCode = buildNameToCode()
+  // Check aliases first — "UK" matches the ISO-2 regex but is not a valid code (GB is).
+  const aliased = _nameToCode.get(input.trim().toLowerCase())
+  if (aliased) return aliased
+  if (_ALPHA2_RE.test(input)) {
+    const upper = input.toUpperCase()
+    // Only accept if Intl actually resolves it — rejects "ZZ" etc.
+    try {
+      if (_displayNames.of(upper)) return upper
+    } catch { /* fall through */ }
+  }
+  return undefined
+}
+
+// Coerce a list of strings (mix of ISO-2 codes and country names) into ISO-2 codes.
+// Unrecognized inputs are dropped (rather than passed through) so providers don't
+// receive garbage like { code: "Brazil", name: "Brazil" }.
+export function coerceCountriesToIso(values: readonly string[] | undefined): string[] {
+  if (!values?.length) return []
+  return values.map((v) => nameToIsoCountry(v)).filter((c): c is string => typeof c === 'string')
+}
+
 // ---------------------------------------------------------------------------
 // Strict post-filter helpers
 // ---------------------------------------------------------------------------
@@ -200,9 +254,12 @@ const searchCompaniesProviders: ProviderEntry[] = [
     method: 'POST',
     priority: 1,
     mapParams: (input) => {
-      // CompanyEnrich industries require exact taxonomy matches — free-text values like
-      // "SaaS" produce empty results. Fold industries into keywords for flexible matching.
-      const keywords = [
+      // CompanyEnrich's `keywords` body field is a tag filter that does not match
+      // brand names — sending "wework" returns global defaults instead of WeWork.
+      // Route free-text input through `query` (full-text on company name + domain).
+      // Industries are folded into the same string because CompanyEnrich's `industries`
+      // field requires exact taxonomy matches and rejects free-text like "SaaS".
+      const queryTerms = [
         ...((input.keywords as string[] | undefined) ?? []),
         ...((input.industries as string[] | undefined) ?? []),
       ]
@@ -213,7 +270,7 @@ const searchCompaniesProviders: ProviderEntry[] = [
       return {
         body: {
           countries: input.countries,
-          keywords: keywords.length > 0 ? keywords : undefined,
+          query: queryTerms.length > 0 ? queryTerms.join(' ') : undefined,
           technologies: isNonEmptyArray(input.technologies) ? input.technologies : undefined,
           employees:
             input.min_employees || input.max_employees
@@ -944,6 +1001,14 @@ const findPeopleProviders: ProviderEntry[] = [
           ? [...groups.values()].map((titles) => ({ job_title: titles.join(', ') }))
           : [{ job_title: 'Decision Maker' }]
       const hasLinkedInUrls = isNonEmptyArray(input.company_linkedin_urls)
+      // LF natively scopes contacts by person location via country_codes. Coerce
+      // input.locations (which agents pass as a mix of ISO-2 codes "BR" and country
+      // names "Brazil") to ISO-2 first — LF rejects/ignores anything else and silently
+      // returns unfiltered global results.
+      const isoCodes = coerceCountriesToIso(input.locations as string[] | undefined)
+      const country_codes = isoCodes.length > 0
+        ? isoCodes.map((code) => ({ code, name: isoCountryToName(code) }))
+        : undefined
       return {
         body: {
           ...(hasLinkedInUrls && { company_linkedin_urls: input.company_linkedin_urls }),
@@ -954,6 +1019,7 @@ const findPeopleProviders: ProviderEntry[] = [
           search: {
             max_persona_results: (input.limit as number) ?? 25,
             personas,
+            ...(country_codes && { country_codes }),
           },
         },
       }
@@ -962,21 +1028,20 @@ const findPeopleProviders: ProviderEntry[] = [
       const d = data as Record<string, unknown>
       return (
         isNonEmptyArray(d.companies_personas) ||
-        (d.status === 'SUCCESSFUL' && typeof d.nb_jobs_complete === 'number' && (d.nb_jobs_complete as number) > 0)
+        (d.status === 'SUCCESSFUL' && d.nb_jobs_complete != null && (d.nb_jobs_complete as number) > 0)
       )
     },
     async: {
       pollEndpoint: (id: string) => `/leadsfactory/contact-finder/searches/${id}`,
-      // Continuously growing backoff: fast first probe (3s), then ramp up indefinitely
-      // — never plateaus, but the cumulative delay is bounded by timeoutMs.
-      // Schedule: 3s, 7s, 15s, 25s, 35s, 45s, 55s, 65s, +10s per attempt thereafter.
+      // Growing backoff: fast early probes, then steady growth bounded by timeoutMs.
+      // Schedule: 2s, 5s, 12s, 20s, 28s, 36s, +8s per attempt thereafter.
       pollIntervalMs: (attempt) =>
-        attempt === 1 ? 3000 : attempt === 2 ? 7000 : 15000 + (attempt - 3) * 10000,
+        attempt === 1 ? 2000 : attempt === 2 ? 5000 : 12000 + (attempt - 3) * 8000,
       timeoutMs: 300_000, // 5 minutes
       isComplete: (data) => {
         const d = data as Record<string, unknown>
         const status = d.status as string | undefined
-        return status === 'SUCCESSFUL' || status === 'FAILED'
+        return status === 'SUCCESSFUL' || status === 'FAILED' || status === 'INVALID_URL'
       },
       extractId: (response) => {
         const d = response as Record<string, unknown>
@@ -1368,7 +1433,7 @@ const findEmailProviders: ProviderEntry[] = [
         return d.enrichment_id as string
       },
       pollEndpoint: (id) => `/fullenrich/contact/enrich/bulk/${id}`,
-      pollIntervalMs: 5000,
+      pollIntervalMs: 2500,
       timeoutMs: 60_000,
       isComplete: (data) => {
         const d = data as Record<string, unknown>
@@ -1463,7 +1528,7 @@ const verifyEmailProviders: ProviderEntry[] = [
         throw new Error('Instantly verification response has no email field')
       },
       pollEndpoint: (email) => `/instantly/email-verification/${encodeURIComponent(email)}`,
-      pollIntervalMs: 3000,
+      pollIntervalMs: 1500,
       timeoutMs: 30_000,
       isComplete: (data) => {
         const d = data as Record<string, unknown>
@@ -1879,7 +1944,7 @@ function _hasJobFilter(input: Record<string, unknown>, keys: string[]): boolean
 }
 
 const _jobsSharedAsync = {
-  pollIntervalMs: 5_000,
+  pollIntervalMs: (attempt: number) => (attempt === 1 ? 1500 : attempt <= 3 ? 2500 : 4000),
   timeoutMs: 300_000,
   extractId: (data: unknown) => {
     const jobId = (data as { jobId?: number | string }).jobId
@@ -2013,7 +2078,7 @@ const searchJobsProviders: ProviderEntry[] = [
 // ---------------------------------------------------------------------------
 
 const _adsSharedAsync = {
-  pollIntervalMs: 5_000,
+  pollIntervalMs: (attempt: number) => (attempt === 1 ? 1500 : attempt <= 3 ? 2500 : 4000),
   timeoutMs: 300_000,
   extractId: (data: unknown) => {
     const jobId = (data as { jobId?: number | string }).jobId
@@ -2181,7 +2246,7 @@ function _hasAny(input: Record<string, unknown>, keys: readonly string[]): boole
 }
 
 const _placesSharedAsync = {
-  pollIntervalMs: 5_000,
+  pollIntervalMs: (attempt: number) => (attempt === 1 ? 1500 : attempt <= 3 ? 2500 : 4000),
   timeoutMs: 300_000,
   extractId: (data: unknown) => {
     const jobId = (data as { jobId?: number | string }).jobId
@@ -2351,7 +2416,7 @@ const findInfluencersProviders: ProviderEntry[] = [
 // ---------------------------------------------------------------------------
 
 const _redditSharedAsync = {
-  pollIntervalMs: 5_000,
+  pollIntervalMs: (attempt: number) => (attempt === 1 ? 1500 : attempt <= 3 ? 2500 : 4000),
   timeoutMs: 300_000,
   extractId: (data: unknown) => {
     const jobId = (data as { jobId?: number | string }).jobId
@@ -3093,28 +3158,45 @@ export function getProviderApplicabilityGuard(
   return providers.find((p) => p.id === providerId)?.isApplicable
 }
 
+const _providersCache = new Map<Capability, ProviderEntry[]>()
+
 /**
  * Get the ordered provider list for a capability.
- * Returns a copy sorted by priority (lower = first).
+ * Returns a frozen sorted copy — cached after the first call (registry is static).
  */
 export function getProviders(capability: Capability): ProviderEntry[] {
-  const providers = registry[capability]
-  if (!providers) throw new Error(`Unknown capability: ${capability}`)
-  return [...providers].sort((a, b) => a.priority - b.priority)
+  let cached = _providersCache.get(capability)
+  if (!cached) {
+    const providers = registry[capability]
+    if (!providers) throw new Error(`Unknown capability: ${capability}`)
+    cached = Object.freeze([...providers].sort((a, b) => a.priority - b.priority)) as ProviderEntry[]
+    _providersCache.set(capability, cached)
+  }
+  return cached
 }
 
+const _searchWebProvidersCache = new Map<boolean, ProviderEntry[]>()
+
 /**
  * Get providers for search_web, reordering for neural search preference.
+ * Result is cached per preferNeural value — registry is static.
  */
 export function getSearchWebProviders(preferNeural: boolean): ProviderEntry[] {
-  const providers = getProviders('search_web')
-  if (preferNeural) {
-    // Put Exa first when neural is requested
-    return providers.sort((a, b) => {
-      if (a.id === 'exa') return -1
-      if (b.id === 'exa') return 1
-      return a.priority - b.priority
-    })
+  let cached = _searchWebProvidersCache.get(preferNeural)
+  if (!cached) {
+    const base = getProviders('search_web')
+    if (preferNeural) {
+      cached = Object.freeze(
+        [...base].sort((a, b) => {
+          if (a.id === 'exa') return -1
+          if (b.id === 'exa') return 1
+          return a.priority - b.priority
+        }),
+      ) as ProviderEntry[]
+    } else {
+      cached = base
+    }
+    _searchWebProvidersCache.set(preferNeural, cached)
   }
-  return providers
+  return cached
 }

package/src/tools/enrich-company.ts

@@ -18,15 +18,15 @@ export async function enrichCompanyHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   if (!restInput.domain && !restInput.linkedin_url && !restInput.name) {
     const err = { error: 'At least one of domain, linkedin_url, or name is required', providers_tried: [] }
-    return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(err) }], isError: true }
   }
   const resolved = resolvePreferredProviders('enrich_company', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const result = await executeWithFallback('enrich_company', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }

package/src/tools/enrich-person.ts

@@ -25,11 +25,11 @@ export async function enrichPersonHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   const resolved = resolvePreferredProviders('enrich_person', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const result = await executeWithFallback('enrich_person', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }

package/src/tools/fetch-page-content.ts

@@ -33,11 +33,11 @@ export async function fetchPageContentHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   const resolved = resolvePreferredProviders('fetch_page_content', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const result = await executeWithFallback('fetch_page_content', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }

package/src/tools/find-email.ts

@@ -45,19 +45,19 @@ export async function findEmailHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   const resolved = resolvePreferredProviders('find_email', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const validation = inputSchema.safeParse(restInput)
   if (!validation.success) {
     const msg = validation.error.issues.map((i) => i.message).join('; ')
     return {
-      content: [{ type: 'text' as const, text: JSON.stringify({ error: msg }, null, 2) }],
+      content: [{ type: 'text' as const, text: JSON.stringify({ error: msg }) }],
       isError: true,
     }
   }
   const result = await executeWithFallback('find_email', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }

package/src/tools/find-emails.ts

@@ -1,7 +1,36 @@
 import { z } from 'zod'
 import { callApi } from '../client.js'
+import { executeWithFallback, isExecutionError } from '../executor.js'
 import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS } from '../utils/provider-resolver.js'
 
+// Single-find_email registry providers that the bulk pipeline does NOT already cover.
+// Used as a fallback waterfall for residual misses after Prospeo + FullEnrich + Findymail + Icypeas.
+const SINGLE_ONLY_FIND_EMAIL_PROVIDERS = ['limadata-work-email', 'blitzapi', 'limadata-work-email-linkedin', 'linkupapi'] as const
+
+// Pulls a string email from any of the provider-specific response shapes used in the
+// find_email registry (registry.ts:1228-1413). Keep in sync with the providers covered there.
+function extractEmail(data: unknown): string | null {
+  if (!data || typeof data !== 'object') return null
+  const d = data as Record<string, unknown>
+  if (typeof d.email === 'string' && d.email.includes('@')) return d.email
+  if (Array.isArray(d.emails) && typeof d.emails[0] === 'string' && (d.emails[0] as string).includes('@')) return d.emails[0] as string
+  const person = d.person as Record<string, unknown> | undefined
+  const personEmail = person?.email as Record<string, unknown> | undefined
+  if (typeof personEmail?.email === 'string' && (personEmail.email as string).includes('@')) return personEmail.email as string
+  const nested = d.data
+  if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+    const inner = (nested as Record<string, unknown>).email
+    if (typeof inner === 'string' && inner.includes('@')) return inner
+  }
+  if (Array.isArray(nested) && nested[0] && typeof nested[0] === 'object') {
+    const first = nested[0] as Record<string, unknown>
+    if (Array.isArray(first.emails) && typeof first.emails[0] === 'string' && (first.emails[0] as string).includes('@')) {
+      return first.emails[0] as string
+    }
+  }
+  return null
+}
+
 export const findEmailsName = 'find_emails'
 
 export const findEmailsDescription =
@@ -76,7 +105,7 @@ async function fullEnrichStep(misses: PersonInput[], results: EmailResult[]): Pr
   // faster, so FullEnrich's marginal value decays past this point.
   const deadline = Date.now() + 45_000
   while (Date.now() < deadline) {
-    await sleep(5000)
+    await sleep(2000)
     const pollRes = await callApi('GET', `/fullenrich/contact/enrich/bulk/${enrichmentId}`)
     if (!pollRes.ok) continue
 
@@ -162,7 +191,7 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
 
   const resolved = resolvePreferredProviders('find_emails', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
 
   const allowedProviders = resolved.providers
@@ -218,14 +247,49 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
     if (!isConstrained || allowedProviders.includes('findymail') || allowedProviders.includes('icypeas')) {
       steps.push(findymailIcypeasStep(misses, results, isConstrained ? allowedProviders : undefined))
     }
-    if (steps.length > 0) await Promise.all(steps)
+    if (steps.length > 0) await Promise.allSettled(steps)
+  }
+
+  // Step 4 — single-find_email fallback for stragglers.
+  // Bulk covers Prospeo + FullEnrich + FindyMail + IcyPeas. The single-find_email registry
+  // (registry.ts:1228-1413) additionally covers LimaData, BlitzAPI, LimaData-LinkedIn, LinkupAPI.
+  // Without this step, agents would observe bulk return 0 and fall back to N+1 single calls.
+  const stragglers = missesOf(people, results)
+  if (stragglers.length > 0) {
+    const fallbackProviders = isConstrained
+      ? allowedProviders.filter((p) => (SINGLE_ONLY_FIND_EMAIL_PROVIDERS as readonly string[]).includes(p))
+      : [...SINGLE_ONLY_FIND_EMAIL_PROVIDERS]
+    if (fallbackProviders.length > 0) {
+      await Promise.all(
+        stragglers.map(async (person) => {
+          const hit = results.find((r) => r.id === person.id)
+          if (!hit || hit.email) return
+          const singleInput: Record<string, unknown> = {
+            first_name: person.first_name,
+            last_name: person.last_name,
+            domain: person.domain,
+            linkedin_url: person.linkedin_url,
+          }
+          // Per-person 30s ceiling so one slow provider doesn't block the rest.
+          const exec = executeWithFallback('find_email', singleInput, { providers: fallbackProviders })
+          const timeout = new Promise<null>((resolve) => setTimeout(() => resolve(null), 30_000))
+          const raced = await Promise.race([exec, timeout])
+          if (!raced || isExecutionError(raced)) return
+          const email = extractEmail(raced.data)
+          if (email && !hit.email) {
+            hit.email = email
+            hit.provider = raced._meta.provider
+          }
+        }),
+      )
+    }
   }
 
   const found = results.filter((r) => r.email !== null).length
 
   if (isConstrained && found === 0) {
     const err = buildAllFailedError(allowedProviders, 'find_emails', FIND_EMAILS_PROVIDERS)
-    return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(err) }], isError: true }
   }
 
   const meta = resolved.matchedFrom && Object.keys(resolved.matchedFrom).length > 0
@@ -236,7 +300,7 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
     content: [
       {
         type: 'text' as const,
-        text: JSON.stringify({ data: { results, found, total: people.length }, ...(meta ? { _meta: meta } : {}) }, null, 2),
+        text: JSON.stringify({ data: { results, found, total: people.length }, ...(meta ? { _meta: meta } : {}) }),
       },
     ],
   }

package/src/tools/find-influencers.ts

@@ -31,11 +31,11 @@ export async function findInfluencersHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   const resolved = resolvePreferredProviders('find_influencers', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const result = await executeWithFallback('find_influencers', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }

package/src/tools/find-people.ts

@@ -22,7 +22,7 @@ export const findPeopleSchema = {
   company_domains: z.array(z.string()).optional().describe('Company domains to search (e.g. ["microsoft.com", "google.com"]). Use only when LinkedIn URLs are not available.'),
   job_titles: z.array(z.string()).optional().describe('Target job titles (e.g. ["CEO", "VP of Sales"])'),
   seniorities: z.array(z.string()).optional().describe('Seniority levels (e.g. ["c_suite", "vp", "director"])'),
-  locations: z.array(z.string()).optional().describe('Person or company locations'),
+  locations: z.array(z.string()).optional().describe('Person locations as either ISO-2 country codes ("BR") or English country names ("Brazil") — both are accepted and normalized internally. LeadsFactory uses these to scope contacts to the country; other providers fall back to free-text matching.'),
   keywords: z.array(z.string()).optional().describe('Free-text keyword search terms (e.g. ["growth", "AI"])'),
   limit: z.number().min(1).max(500).default(25).describe('Max results across all companies combined (default: 25, max: 500). For multiple companies multiply: e.g. 10 companies × 5 each = 50.'),
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_people').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
@@ -32,11 +32,11 @@ export async function findPeopleHandler(input: Record<string, unknown>) {
   const { use_providers: rawUseProviders, ...restInput } = input
   const resolved = resolvePreferredProviders('find_people', restInput, rawUseProviders)
   if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
   }
   const result = await executeWithFallback('find_people', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
 
   // Gap-fill: if LeadsFactory missed some domains, try Apollo for those.
@@ -65,12 +65,12 @@ export async function findPeopleHandler(input: Record<string, unknown>) {
             },
           }
           return {
-            content: [{ type: 'text' as const, text: JSON.stringify({ ...result, data: merged }, null, 2) }],
+            content: [{ type: 'text' as const, text: JSON.stringify({ ...result, data: merged }) }],
           }
         }
       }
     }
   }
 
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }