@coldiq/mcp 0.1.19 → 0.2.5

package/src/tools/find-emails.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { callApi } from '../client.js'
+import { callApi, type ApiResponse } from '../client.js'
 import { executeWithFallback, isExecutionError } from '../executor.js'
 import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS } from '../utils/provider-resolver.js'
 
@@ -7,6 +7,13 @@ import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS }
 // 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
 
+// Chunk inputs of >10 people into independent waterfalls. Empirically, Prospeo bulk on 25-50
+// names regularly exceeds the 30s client timeout; 10 keeps each Prospeo call well under it.
+export const FIND_EMAILS_CHUNK_SIZE = 10
+// Concurrency cap keeps peak in-flight calls (per-chunk fan-out × concurrent chunks) under
+// the undici Agent's 32-connection budget (client.ts).
+const CHUNK_CONCURRENCY = 3
+
 // 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 {
@@ -37,11 +44,14 @@ export const findEmailsDescription =
   'Find professional emails for multiple people in one batch. ' +
   'Uses Prospeo bulk first; for any misses, runs FullEnrich and FindyMail/IcyPeas in parallel — ' +
   'whichever provider returns an email first wins. ' +
-  'Much faster than calling find_email one-by-one. Max 50 people per call. ' +
+  'Much faster than calling find_email one-by-one. Max 50 people per call — ' +
+  `inputs are split into chunks of ${FIND_EMAILS_CHUNK_SIZE} internally for reliability, so larger batches work transparently. ` +
   'Each person needs a unique id to match results back. ' +
   'Always pass first_name, last_name, and domain — they are the primary enrichment signal. ' +
   'Also pass linkedin_url when available, but never rely on it alone as some providers cannot resolve vanity URLs. ' +
-  'ColdIQ automatically picks the best waterfall — pass use_providers only if you need specific tools.'
+  'ColdIQ automatically picks the best waterfall — pass use_providers only if you need specific tools. ' +
+  'Response includes `_meta.batch_status` (complete|partial|failed) and per-provider call stats so callers can ' +
+  'tell a real "no coverage" result apart from a provider-level failure.'
 
 export const findEmailsSchema = {
   people: z
@@ -74,6 +84,49 @@ interface EmailResult {
   provider: string | null
 }
 
+interface ProviderStats {
+  attempted: number
+  failed: number
+}
+
+interface BatchStats {
+  prospeo: ProviderStats
+  fullenrich: ProviderStats
+  findymail: ProviderStats
+  icypeas: ProviderStats
+  single_fallback: ProviderStats
+}
+
+function newBatchStats(): BatchStats {
+  return {
+    prospeo: { attempted: 0, failed: 0 },
+    fullenrich: { attempted: 0, failed: 0 },
+    findymail: { attempted: 0, failed: 0 },
+    icypeas: { attempted: 0, failed: 0 },
+    single_fallback: { attempted: 0, failed: 0 },
+  }
+}
+
+function mergeStats(into: BatchStats, from: BatchStats): void {
+  for (const key of Object.keys(into) as (keyof BatchStats)[]) {
+    into[key].attempted += from[key].attempted
+    into[key].failed += from[key].failed
+  }
+}
+
+function totalFailures(s: BatchStats): number {
+  let n = 0
+  for (const key of Object.keys(s) as (keyof BatchStats)[]) n += s[key].failed
+  return n
+}
+
+// A call counts as a "failure" when callApi never received a usable response: network error,
+// abort/timeout (status === 0), or upstream 5xx. Upstream 4xx is a data-shape problem, not a
+// provider outage — we don't surface it as a batch-level failure.
+function isCallFailure(res: ApiResponse): boolean {
+  return !res.ok && (res.status === 0 || res.status >= 500)
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -82,7 +135,75 @@ function missesOf(people: PersonInput[], results: EmailResult[]): PersonInput[]
   return people.filter((p) => !results.find((r) => r.id === p.id)?.email)
 }
 
-async function fullEnrichStep(misses: PersonInput[], results: EmailResult[]): Promise<void> {
+function chunkArray<T>(arr: T[], size: number): T[][] {
+  if (arr.length <= size) return [arr]
+  const out: T[][] = []
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size))
+  return out
+}
+
+async function withConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  fn: (item: T, idx: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length)
+  let cursor = 0
+  const workerCount = Math.min(concurrency, items.length)
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      const i = cursor++
+      if (i >= items.length) return
+      results[i] = await fn(items[i]!, i)
+    }
+  })
+  await Promise.all(workers)
+  return results
+}
+
+async function prospeoBulkStep(
+  chunk: PersonInput[],
+  results: EmailResult[],
+  stats: BatchStats,
+): Promise<void> {
+  const bulkBody = {
+    data: chunk.map((p) =>
+      p.linkedin_url
+        ? { identifier: p.id, linkedin_url: p.linkedin_url }
+        : { identifier: p.id, first_name: p.first_name, last_name: p.last_name, company_name: p.domain },
+    ),
+  }
+
+  stats.prospeo.attempted += 1
+  const bulkRes = await callApi('POST', '/prospeo/bulk-enrich-person', bulkBody)
+  if (isCallFailure(bulkRes)) stats.prospeo.failed += 1
+  if (!bulkRes.ok) return
+
+  const data = bulkRes.data as {
+    results?: Array<{
+      identifier: string
+      person?: { email?: { email?: string } }
+    }>
+  }
+  for (const item of data.results ?? []) {
+    const email = item.person?.email?.email
+    if (typeof email === 'string' && email.includes('@')) {
+      const hit = results.find((r) => r.id === item.identifier)
+      if (hit) {
+        hit.email = email
+        hit.provider = 'prospeo'
+      }
+    }
+  }
+}
+
+async function fullEnrichStep(
+  misses: PersonInput[],
+  results: EmailResult[],
+  stats: BatchStats,
+): Promise<void> {
+  stats.fullenrich.attempted += 1
+
   const feBody = {
     name: 'mcp-enrich-batch',
     data: misses.map((p) => ({
@@ -96,10 +217,16 @@ async function fullEnrichStep(misses: PersonInput[], results: EmailResult[]): Pr
   }
 
   const feCreateRes = await callApi('POST', '/fullenrich/contact/enrich/bulk', feBody)
-  if (!feCreateRes.ok) return
+  if (!feCreateRes.ok) {
+    if (isCallFailure(feCreateRes)) stats.fullenrich.failed += 1
+    return
+  }
 
   const enrichmentId = (feCreateRes.data as Record<string, unknown>).enrichment_id as string | undefined
-  if (!enrichmentId) return
+  if (!enrichmentId) {
+    // No id returned but POST 2xx — treat as a soft skip, not a network failure.
+    return
+  }
 
   // Tightened from 90s → 45s: Step 3 runs in parallel and typically fills misses
   // faster, so FullEnrich's marginal value decays past this point.
@@ -130,9 +257,17 @@ async function fullEnrichStep(misses: PersonInput[], results: EmailResult[]): Pr
     }
     return
   }
+  // Polling deadline reached without DONE/FAILED — count as a failure so the caller
+  // sees fullenrich didn't actually finish.
+  stats.fullenrich.failed += 1
 }
 
-async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[], allowedProviders?: string[]): Promise<void> {
+async function findymailIcypeasStep(
+  misses: PersonInput[],
+  results: EmailResult[],
+  stats: BatchStats,
+  allowedProviders?: string[],
+): Promise<void> {
   const useFindymail = !allowedProviders || allowedProviders.includes('findymail')
   const useIcypeas = !allowedProviders || allowedProviders.includes('icypeas')
 
@@ -147,10 +282,12 @@ async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[
       if (useFindymail) {
         const fullName = [person.first_name, person.last_name].filter(Boolean).join(' ')
 
+        stats.findymail.attempted += 1
         const fmRes = await callApi('POST', '/findymail/search/name', {
           name: fullName,
           domain: person.domain,
         })
+        if (isCallFailure(fmRes)) stats.findymail.failed += 1
         if (!hit.email && fmRes.ok) {
           const d = fmRes.data as Record<string, unknown>
           if (typeof d.email === 'string' && d.email.includes('@')) {
@@ -163,11 +300,13 @@ async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[
 
       if (hit.email || !useIcypeas) return
 
+      stats.icypeas.attempted += 1
       const icyRes = await callApi('POST', '/icypeas/email-search', {
         firstname: person.first_name,
         lastname: person.last_name,
         domainOrCompany: person.domain,
       })
+      if (isCallFailure(icyRes)) stats.icypeas.failed += 1
       if (!hit.email && icyRes.ok) {
         const d = icyRes.data as Record<string, unknown>
         const email =
@@ -185,50 +324,62 @@ async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[
   )
 }
 
-export async function findEmailsHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const people = restInput.people as PersonInput[]
+async function singleFallbackStep(
+  stragglers: PersonInput[],
+  results: EmailResult[],
+  stats: BatchStats,
+  fallbackProviders: string[],
+): Promise<void> {
+  if (fallbackProviders.length === 0 || stragglers.length === 0) return
 
-  const resolved = resolvePreferredProviders('find_emails', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-
-  const allowedProviders = resolved.providers
-  const isConstrained = allowedProviders.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,
+      }
+      stats.single_fallback.attempted += 1
+      // 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) {
+        // Race timed out — none of the fallback providers returned in time.
+        stats.single_fallback.failed += 1
+        return
+      }
+      if (isExecutionError(raced)) {
+        // Every fallback provider returned an error. Only count as `failed` when at least
+        // one of them looked like a real network/upstream failure — providers that responded
+        // 200 with no result are legitimate "no coverage", not a batch failure.
+        const hadRealFailure = raced.providers_tried.some((p) => p.status === 0 || p.status >= 500)
+        if (hadRealFailure) stats.single_fallback.failed += 1
+        return
+      }
+      const email = extractEmail(raced.data)
+      if (email && !hit.email) {
+        hit.email = email
+        hit.provider = raced._meta.provider
+      }
+    }),
+  )
+}
 
-  const results: EmailResult[] = people.map((p) => ({ id: p.id, email: null, provider: null }))
+async function processChunk(
+  chunk: PersonInput[],
+  allowedProviders: string[],
+  isConstrained: boolean,
+): Promise<{ results: EmailResult[]; stats: BatchStats }> {
+  const results: EmailResult[] = chunk.map((p) => ({ id: p.id, email: null, provider: null }))
+  const stats = newBatchStats()
 
-  // Step 1: Prospeo bulk — 1 call for all people
+  // Step 1: Prospeo bulk — 1 call for everyone in this chunk.
   if (!isConstrained || allowedProviders.includes('prospeo')) {
-    const bulkBody = {
-      data: people.map((p) =>
-        p.linkedin_url
-          ? { identifier: p.id, linkedin_url: p.linkedin_url }
-          : { identifier: p.id, first_name: p.first_name, last_name: p.last_name, company_name: p.domain },
-      ),
-    }
-
-    const bulkRes = await callApi('POST', '/prospeo/bulk-enrich-person', bulkBody)
-
-    if (bulkRes.ok) {
-      const data = bulkRes.data as {
-        results?: Array<{
-          identifier: string
-          person?: { email?: { email?: string } }
-        }>
-      }
-      for (const item of data.results ?? []) {
-        const email = item.person?.email?.email
-        if (typeof email === 'string' && email.includes('@')) {
-          const hit = results.find((r) => r.id === item.identifier)
-          if (hit) {
-            hit.email = email
-            hit.provider = 'prospeo'
-          }
-        }
-      }
-    }
+    await prospeoBulkStep(chunk, results, stats)
   }
 
   // Steps 2 & 3 run concurrently for misses.
@@ -237,15 +388,14 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
   // Both branches write to the shared `results` array; every write site checks
   // `if (hit.email)` first so whichever provider arrives first wins and the
   // other does not overwrite.
-  const misses = missesOf(people, results)
-
+  const misses = missesOf(chunk, results)
   if (misses.length > 0) {
     const steps: Promise<void>[] = []
     if (!isConstrained || allowedProviders.includes('fullenrich')) {
-      steps.push(fullEnrichStep(misses, results))
+      steps.push(fullEnrichStep(misses, results, stats))
     }
     if (!isConstrained || allowedProviders.includes('findymail') || allowedProviders.includes('icypeas')) {
-      steps.push(findymailIcypeasStep(misses, results, isConstrained ? allowedProviders : undefined))
+      steps.push(findymailIcypeasStep(misses, results, stats, isConstrained ? allowedProviders : undefined))
     }
     if (steps.length > 0) await Promise.allSettled(steps)
   }
@@ -254,54 +404,75 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
   // 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)
+  const stragglers = missesOf(chunk, 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
-          }
-        }),
-      )
-    }
+    await singleFallbackStep(stragglers, results, stats, fallbackProviders)
   }
 
+  return { results, stats }
+}
+
+function computeBatchStatus(found: number, total: number, stats: BatchStats): 'complete' | 'partial' | 'failed' {
+  const failures = totalFailures(stats)
+  if (failures === 0) return 'complete'
+  if (found === 0 && total > 0) return 'failed'
+  return 'partial'
+}
+
+export async function findEmailsHandler(input: Record<string, unknown>) {
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const people = restInput.people as PersonInput[]
+
+  const resolved = resolvePreferredProviders('find_emails', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
+  }
+
+  const allowedProviders = resolved.providers
+  const isConstrained = allowedProviders.length > 0
+
+  const chunks = chunkArray(people, FIND_EMAILS_CHUNK_SIZE)
+  const chunkOutputs = await withConcurrency(chunks, CHUNK_CONCURRENCY, (chunk) =>
+    processChunk(chunk, allowedProviders, isConstrained),
+  )
+
+  const results: EmailResult[] = chunkOutputs.flatMap((c) => c.results)
+  const aggregateStats = newBatchStats()
+  for (const c of chunkOutputs) mergeStats(aggregateStats, c.stats)
+
   const found = results.filter((r) => r.email !== null).length
+  const batchStatus = computeBatchStatus(found, people.length, aggregateStats)
 
+  // Constrained-mode behaviour preserved: if the caller pinned providers and got zero, push back.
   if (isConstrained && found === 0) {
     const err = buildAllFailedError(allowedProviders, 'find_emails', FIND_EMAILS_PROVIDERS)
     return { content: [{ type: 'text' as const, text: JSON.stringify(err) }], isError: true }
   }
 
-  const meta = resolved.matchedFrom && Object.keys(resolved.matchedFrom).length > 0
-    ? { matchedFrom: resolved.matchedFrom }
-    : undefined
+  const meta: Record<string, unknown> = {
+    providers: aggregateStats,
+    batch_status: batchStatus,
+    chunk_size: FIND_EMAILS_CHUNK_SIZE,
+    chunk_count: chunks.length,
+  }
+  if (resolved.matchedFrom && Object.keys(resolved.matchedFrom).length > 0) {
+    meta.matchedFrom = resolved.matchedFrom
+  }
+
+  // Surface the silent-failure case the user reported: 200 OK with all-nulls is misleading
+  // when the nulls were caused by provider failures rather than legitimate no-coverage.
+  const isError = batchStatus === 'failed'
 
   return {
     content: [
       {
         type: 'text' as const,
-        text: JSON.stringify({ data: { results, found, total: people.length }, ...(meta ? { _meta: meta } : {}) }),
+        text: JSON.stringify({ data: { results, found, total: people.length }, _meta: meta }),
       },
     ],
+    ...(isError ? { isError: true } : {}),
   }
 }

package/src/tools/find-people.ts

@@ -3,6 +3,7 @@ import { executeWithFallback, isExecutionError } from '../executor.js'
 import { callApi } from '../client.js'
 import { getProviders } from '../registry.js'
 import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { compactPayload } from '../utils/compact-people.js'
 
 export const findPeopleName = 'find_people'
 
@@ -15,7 +16,9 @@ export const findPeopleDescription =
   'Prefer company_linkedin_urls when available — they make the search faster. Only pass company_domains when you have no LinkedIn URLs. ' +
   'Pass job_titles EXACTLY as stated — never expand or generate variants (e.g. do NOT turn "CEO" into ["CEO", "Chief Executive Officer", "Founder"]). LeadsFactory handles fuzzy title matching internally; adding variants wastes personas and degrades results. ' +
   'Do NOT pass seniorities unless explicitly asked — job titles alone produce better results. ' +
-  'Returns names, titles, LinkedIn URLs. Default limit: 25.'
+  'Returns names, titles, LinkedIn URLs, plus company name/domain/linkedin/headcount when available. Default limit: 25. ' +
+  'Response is compact by default (~99% smaller than the raw provider payload). Set fields="verbose" only when you specifically need employment history, skills, languages, or company descriptions. ' +
+  'When the matched provider is Apollo, last names are partially obfuscated and emails/LinkedIn URLs are omitted unless reveal=true is passed (adds 1 credit per revealed person).'
 
 export const findPeopleSchema = {
   company_linkedin_urls: z.array(z.string()).optional().describe('Company LinkedIn URLs (preferred over domains when available, e.g. ["https://linkedin.com/company/microsoft"])'),
@@ -24,12 +27,26 @@ export const findPeopleSchema = {
   seniorities: z.array(z.string()).optional().describe('Seniority levels (e.g. ["c_suite", "vp", "director"])'),
   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.'),
+  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. Note: when the matched provider is Apollo, results are capped at 100 per call (Apollo upstream limit).'),
+  fields: z.enum(['compact', 'verbose']).default('compact').describe('Response shape. "compact" (default) returns a small, predictable per-person record: name, title, linkedin_url, company {name, domain, linkedin_url, headcount}, plus seniority/email/location when the upstream provider includes them. "verbose" returns the raw provider passthrough (~30KB+ per record from FullEnrich: employment history, every company office, descriptions, skills, languages) — only use when you specifically need those fields.'),
+  reveal: z.boolean().optional().describe('Apollo-only: when true, follow the obfuscated Apollo people-search results with /apollo/people/bulk-match to reveal full names, emails, and LinkedIn URLs. Costs 1 extra credit per revealed person on top of the search credit. Has no effect for other providers (their data is already unobfuscated). Default false to protect credits.'),
   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.`),
 }
 
+function buildSuccess(
+  result: { data: unknown; _meta: { provider: string; latencyMs: number; matchedFrom?: Record<string, string> } },
+  fields: 'compact' | 'verbose',
+) {
+  const payload = fields === 'compact'
+    ? { ...result, data: compactPayload(result.data, result._meta.provider) }
+    : result
+  return { content: [{ type: 'text' as const, text: JSON.stringify(payload) }] }
+}
+
 export async function findPeopleHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
+  const { use_providers: rawUseProviders, reveal: rawReveal, fields: rawFields, ...restInput } = input
+  const reveal = rawReveal === true
+  const fields: 'compact' | 'verbose' = rawFields === 'verbose' ? 'verbose' : 'compact'
   const resolved = resolvePreferredProviders('find_people', restInput, rawUseProviders)
   if (!resolved.ok) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
@@ -39,6 +56,54 @@ export async function findPeopleHandler(input: Record<string, unknown>) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
 
+  // Apollo's /people/search returns obfuscated data (last names like "Ar***t",
+  // no emails). When the caller opts in with reveal=true, follow up with
+  // /apollo/people/bulk-match (10 IDs per call, Apollo's bulk cap) to swap each
+  // person object for its fully-revealed counterpart. Costs 1 extra credit per
+  // revealed person on top of the original search credit.
+  if (reveal && result._meta.provider === 'apollo') {
+    const data = result.data as Record<string, unknown>
+    const people = (data.people as Array<Record<string, unknown>> | undefined) ?? []
+    const ids = people
+      .map((p) => p.id)
+      .filter((id): id is string => typeof id === 'string' && id.length > 0)
+
+    if (ids.length > 0) {
+      const matches: Array<Record<string, unknown>> = []
+      for (let i = 0; i < ids.length; i += 10) {
+        const chunk = ids.slice(i, i + 10)
+        const res = await callApi('POST', '/apollo/people/bulk-match', {
+          details: chunk.map((id) => ({ id })),
+          reveal_personal_emails: true,
+        })
+        if (res.ok && res.data && typeof res.data === 'object') {
+          const body = res.data as Record<string, unknown>
+          const chunkMatches = (body.matches as Array<Record<string, unknown>> | undefined) ?? []
+          matches.push(...chunkMatches)
+        }
+      }
+
+      if (matches.length > 0) {
+        const matchById = new Map<string, Record<string, unknown>>()
+        for (const m of matches) {
+          const id = m.id
+          if (typeof id === 'string') matchById.set(id, m)
+        }
+        const revealedPeople = people.map((p) => {
+          const id = p.id
+          if (typeof id === 'string' && matchById.has(id)) return matchById.get(id)!
+          return p
+        })
+        // Only claim `revealed: true` when bulk-match returned a result for every ID.
+        // Partial reveals (some entries remain obfuscated) would otherwise mislead
+        // callers into trusting `last_name` / `email` that aren't actually filled.
+        const fullyRevealed = matchById.size >= ids.length
+        const merged = { ...data, people: revealedPeople, revealed: fullyRevealed }
+        return buildSuccess({ ...result, data: merged }, fields)
+      }
+    }
+  }
+
   // Gap-fill: if LeadsFactory missed some domains, try Apollo for those.
   // Only runs when domains were the input — if we sent LinkedIn URLs, no_results_domains
   // is unreliable (LF may resolve arbitrary domains from URLs, e.g. linkedin.com itself).
@@ -64,13 +129,11 @@ export async function findPeopleHandler(input: Record<string, unknown>) {
               ...(apolloRes.data as Record<string, unknown>),
             },
           }
-          return {
-            content: [{ type: 'text' as const, text: JSON.stringify({ ...result, data: merged }) }],
-          }
+          return buildSuccess({ ...result, data: merged }, fields)
         }
       }
     }
   }
 
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return buildSuccess(result, fields)
 }

package/src/tools/get-credit-balance.ts

@@ -0,0 +1,24 @@
+import { callApi } from '../client.js'
+
+export const getCreditBalanceName = 'get_credit_balance'
+
+export const getCreditBalanceDescription =
+  'Get the current ColdIQ credit balance and month-to-date usage for the authenticated account. Use before bulk or fan-out operations (e.g. find_emails over many people) to project cost and avoid mid-run insufficient-credit failures. Returns { balance, usedThisMonth }.'
+
+export const getCreditBalanceSchema = {}
+
+export async function getCreditBalanceHandler(_input: Record<string, unknown>) {
+  const res = await callApi('GET', '/me/credits')
+  if (!res.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: 'Failed to fetch credit balance', status: res.status, data: res.data }),
+        },
+      ],
+      isError: true,
+    }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify({ data: res.data }) }] }
+}