@coldiq/mcp 0.1.0

package/src/registry.ts

@@ -0,0 +1,3159 @@
+// ---------------------------------------------------------------------------
+// Provider Registry — maps capabilities to ordered provider lists
+// ---------------------------------------------------------------------------
+
+export interface AsyncConfig {
+  /** Build the poll endpoint path from the ID returned by the create call */
+  pollEndpoint: (id: string) => string
+  /** Milliseconds between poll attempts */
+  pollIntervalMs: number
+  /** Max milliseconds before giving up */
+  timeoutMs: number
+  /** Check if the async job is done */
+  isComplete: (data: unknown) => boolean
+  /** Extract the job ID from the create response */
+  extractId: (response: unknown) => string
+}
+
+export interface ProviderEntry {
+  id: string
+  endpoint: string
+  method: 'GET' | 'POST'
+  priority: number
+  mapParams: (input: Record<string, unknown>) => { body?: unknown; queryParams?: Record<string, string> }
+  hasResult: (data: unknown) => boolean
+  async?: AsyncConfig
+  /**
+   * Optional gate that returns false when the provider's required input is missing.
+   * The executor skips applicabilityFalsy providers entirely (no upstream call, no credits).
+   * Use for providers that need specific inputs (e.g. LinkedIn URL, Sales Nav URL, employee range).
+   */
+  isApplicable?: (input: Record<string, unknown>) => boolean
+  /**
+   * Optional post-processor applied to the raw API response before hasResult.
+   * Use to strip irrelevant keys, drop records that fail strict filter checks, or
+   * translate the response shape. If the filtered result fails hasResult, the executor
+   * falls through to the next provider as if the call had returned no results.
+   */
+  postFilter?: (data: unknown, input: Record<string, unknown>) => unknown
+}
+
+export type Capability =
+  | 'search_companies'
+  | 'find_people'
+  | 'find_email'
+  | 'verify_email'
+  | 'find_phone'
+  | 'enrich_company'
+  | 'enrich_person'
+  | 'search_web'
+  | 'search_jobs'
+  | 'search_ads'
+  | 'search_places'
+  | 'find_influencers'
+  | 'search_reddit'
+  | 'search_seo'
+  | 'find_signals'
+  | 'fetch_page_content'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isNonEmptyArray(v: unknown): boolean {
+  return Array.isArray(v) && v.length > 0
+}
+
+function hasAnyKey(obj: unknown, keys: string[]): boolean {
+  if (!obj || typeof obj !== 'object') return false
+  return keys.some((k) => {
+    const val = (obj as Record<string, unknown>)[k]
+    return val !== undefined && val !== null && val !== ''
+  })
+}
+
+function toLinkupFundingStage(stage: string): string | undefined {
+  const map: Record<string, string> = {
+    seed: 'Seed',
+    'series a': 'Series A',
+    series_a: 'Series A',
+    'series b': 'Series B',
+    series_b: 'Series B',
+    'series c': 'Series C',
+    series_c: 'Series C',
+    'series d': 'Series D+',
+    series_d: 'Series D+',
+    'series d+': 'Series D+',
+    'series_d+': 'Series D+',
+  }
+  return map[stage.toLowerCase()]
+}
+
+// ---------------------------------------------------------------------------
+// ISO 3166-1 alpha-2 → English country name
+// ---------------------------------------------------------------------------
+
+const _ALPHA2_RE = /^[A-Z]{2}$/i
+const _displayNames = new Intl.DisplayNames(['en'], { type: 'region' })
+
+export function isoCountryToName(code: string): string {
+  if (!_ALPHA2_RE.test(code)) return code
+  try {
+    return _displayNames.of(code.toUpperCase()) ?? code
+  } catch {
+    return code
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Strict post-filter helpers
+// ---------------------------------------------------------------------------
+
+type StrictFieldMap = {
+  foundedYearField: string
+  employeeCountField: string | string[]
+  countryField: string | string[]
+}
+
+function readNested(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>(
+    (acc, key) => (acc && typeof acc === 'object' ? (acc as Record<string, unknown>)[key] : undefined),
+    obj,
+  )
+}
+
+function applyStrictFilters(
+  orgs: Array<Record<string, unknown>>,
+  input: Record<string, unknown>,
+  map: StrictFieldMap,
+): Array<Record<string, unknown>> {
+  const minYear = input.min_founded_year as number | undefined
+  const maxYear = input.max_founded_year as number | undefined
+  const minEmp = input.min_employees as number | undefined
+  const maxEmp = input.max_employees as number | undefined
+  const wantCountries = ((input.countries as string[] | undefined) ?? []).map((c) =>
+    isoCountryToName(c).toLowerCase(),
+  )
+  const empFields = Array.isArray(map.employeeCountField) ? map.employeeCountField : [map.employeeCountField]
+  const countryFields = Array.isArray(map.countryField) ? map.countryField : [map.countryField]
+
+  return orgs.filter((o) => {
+    if (minYear !== undefined || maxYear !== undefined) {
+      const y = readNested(o, map.foundedYearField)
+      if (typeof y !== 'number') return false
+      if (minYear !== undefined && y < minYear) return false
+      if (maxYear !== undefined && y > maxYear) return false
+    }
+    if (minEmp !== undefined || maxEmp !== undefined) {
+      let e: number | undefined
+      for (const f of empFields) {
+        const v = readNested(o, f)
+        if (typeof v === 'number') { e = v; break }
+      }
+      if (e === undefined) return false
+      if (minEmp !== undefined && e < minEmp) return false
+      if (maxEmp !== undefined && e > maxEmp) return false
+    }
+    if (wantCountries.length > 0) {
+      let c: string | undefined
+      for (const f of countryFields) {
+        const v = readNested(o, f)
+        if (typeof v === 'string' && v.length > 0) { c = v; break }
+      }
+      if (!c) return false
+      if (!wantCountries.includes(isoCountryToName(c).toLowerCase())) return false
+    }
+    return true
+  })
+}
+
+// ---------------------------------------------------------------------------
+// search_companies
+// ---------------------------------------------------------------------------
+
+// LimaData company_headcount uses letter buckets: A=1-10, B=11-50, C=51-200,
+// D=201-500, E=501-1000, F=1001-5000, G=5001-10000, H=10001+
+function mapEmployeesToLimaDataHeadcount(min?: number, max?: number): string[] {
+  const buckets: Array<{ code: string; min: number; max: number }> = [
+    { code: 'A', min: 1, max: 10 },
+    { code: 'B', min: 11, max: 50 },
+    { code: 'C', min: 51, max: 200 },
+    { code: 'D', min: 201, max: 500 },
+    { code: 'E', min: 501, max: 1000 },
+    { code: 'F', min: 1001, max: 5000 },
+    { code: 'G', min: 5001, max: 10000 },
+    { code: 'H', min: 10001, max: Number.MAX_SAFE_INTEGER },
+  ]
+  const lo = min ?? 0
+  const hi = max ?? Number.MAX_SAFE_INTEGER
+  return buckets.filter((b) => b.max >= lo && b.min <= hi).map((b) => b.code)
+}
+
+const searchCompaniesProviders: ProviderEntry[] = [
+  {
+    id: 'companyenrich',
+    endpoint: '/companyenrich/companies/search',
+    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 = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ]
+      const excludeObj: Record<string, unknown> = {}
+      if (isNonEmptyArray(input.exclude_domains)) excludeObj.domains = input.exclude_domains
+      if (isNonEmptyArray(input.exclude_industries)) excludeObj.industries = input.exclude_industries
+      if (isNonEmptyArray(input.exclude_countries)) excludeObj.countries = input.exclude_countries
+      return {
+        body: {
+          countries: input.countries,
+          keywords: keywords.length > 0 ? keywords : undefined,
+          technologies: isNonEmptyArray(input.technologies) ? input.technologies : undefined,
+          employees:
+            input.min_employees || input.max_employees
+              ? [{ from: input.min_employees, to: input.max_employees }]
+              : undefined,
+          foundedYear:
+            input.min_founded_year || input.max_founded_year
+              ? { from: input.min_founded_year, to: input.max_founded_year }
+              : undefined,
+          fundingAmount:
+            input.min_funding_amount !== undefined || input.max_funding_amount !== undefined
+              ? { from: input.min_funding_amount, to: input.max_funding_amount }
+              : undefined,
+          fundingYear:
+            input.min_funding_year !== undefined || input.max_funding_year !== undefined
+              ? { from: input.min_funding_year, to: input.max_funding_year }
+              : undefined,
+          revenue:
+            input.min_revenue !== undefined || input.max_revenue !== undefined
+              ? [{ from: input.min_revenue, to: input.max_revenue }]
+              : undefined,
+          workforceGrowth:
+            typeof input.min_workforce_growth_pct === 'number'
+              ? { from: input.min_workforce_growth_pct }
+              : undefined,
+          exclude: Object.keys(excludeObj).length > 0 ? excludeObj : undefined,
+          pageSize: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.results) || isNonEmptyArray(d.companies)
+    },
+  },
+  {
+    id: 'apollo',
+    endpoint: '/apollo/organizations/search',
+    method: 'POST',
+    priority: 8,
+    isApplicable: (input) => {
+      // Apollo has no founded-year, technologies, funding, revenue, exclusion, or hiring filters — skip when set.
+      if (typeof input.min_founded_year === 'number' || typeof input.max_founded_year === 'number') return false
+      if (isNonEmptyArray(input.technologies)) return false
+      if (isNonEmptyArray(input.funding_stages)) return false
+      if (typeof input.min_funding_amount === 'number' || typeof input.max_funding_amount === 'number') return false
+      if (typeof input.min_revenue === 'number' || typeof input.max_revenue === 'number') return false
+      if (isNonEmptyArray(input.exclude_domains) || isNonEmptyArray(input.exclude_industries) || isNonEmptyArray(input.exclude_countries)) return false
+      if (typeof input.min_workforce_growth_pct === 'number') return false
+      if (input.is_hiring === true) return false
+      return true
+    },
+    mapParams: (input) => {
+      // Apollo has no dedicated industries filter — fold them into keyword tags alongside keywords.
+      const keywordTags = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ]
+      // organization_locations accepts free-text English strings ("Paris, France", "France").
+      // Translate ISO alpha-2 country codes to English names before forwarding.
+      const countryNames = ((input.countries as string[] | undefined) ?? []).map(isoCountryToName)
+      const orgLocations = [
+        ...((input.locations as string[] | undefined) ?? []),
+        ...countryNames,
+      ]
+      return {
+        body: {
+          q_organization_keyword_tags: keywordTags.length > 0 ? keywordTags : undefined,
+          organization_locations: orgLocations.length > 0 ? orgLocations : undefined,
+          organization_num_employees_ranges:
+            input.min_employees || input.max_employees
+              ? [`${(input.min_employees as number) ?? 0},${(input.max_employees as number) ?? 1000000}`]
+              : undefined,
+          per_page: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.organizations)
+    },
+    postFilter: (data, input) => {
+      const d = { ...(data as Record<string, unknown>) }
+      // CRM accounts are workspace-scoped records, not Apollo's global company DB — strip them.
+      delete d.accounts
+      const minEmp = input.min_employees as number | undefined
+      const maxEmp = input.max_employees as number | undefined
+      const wantCountries = ((input.countries as string[] | undefined) ?? []).map((c) =>
+        isoCountryToName(c).toLowerCase(),
+      )
+      const orgs = (d.organizations as Array<Record<string, unknown>> | undefined) ?? []
+      // Lenient check: only drop when the field is PRESENT and wrong (not strict-on-missing).
+      // Apollo's geo and headcount filters are fuzzy, so records missing a field still benefit
+      // from the doubt. Year filter is handled via isApplicable (Apollo is skipped entirely).
+      d.organizations = orgs.filter((o) => {
+        const emp = o.estimated_num_employees
+        if (typeof emp === 'number') {
+          if (minEmp !== undefined && emp < minEmp) return false
+          if (maxEmp !== undefined && emp > maxEmp) return false
+        }
+        if (wantCountries.length > 0) {
+          const c = o.country
+          if (typeof c === 'string' && c.length > 0) {
+            if (!wantCountries.includes(isoCountryToName(c).toLowerCase())) return false
+          }
+        }
+        return true
+      })
+      return d
+    },
+  },
+  {
+    id: 'fullenrich',
+    endpoint: '/fullenrich/company/search',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => {
+      // FullEnrich wraps each filter value in { value: x } and uses { min, max } for ranges.
+      const wrap = (vals?: string[]) => (Array.isArray(vals) && vals.length > 0 ? vals.map((v) => ({ value: v })) : undefined)
+      const range = (lo?: number, hi?: number) => {
+        if (lo === undefined && hi === undefined) return undefined
+        return [{
+          ...(typeof lo === 'number' ? { min: lo } : {}),
+          ...(typeof hi === 'number' ? { max: hi } : {}),
+        }]
+      }
+      // FullEnrich headquarters_locations accepts free-text English names — translate ISO codes.
+      const locationVals = [
+        ...((input.locations as string[] | undefined) ?? []),
+        ...((input.countries as string[] | undefined) ?? []).map(isoCountryToName),
+      ]
+      return {
+        body: {
+          keywords: wrap(input.keywords as string[] | undefined),
+          industries: wrap(input.industries as string[] | undefined),
+          headquarters_locations: wrap(locationVals),
+          headcounts: range(input.min_employees as number | undefined, input.max_employees as number | undefined),
+          founded_years: range(input.min_founded_year as number | undefined, input.max_founded_year as number | undefined),
+          limit: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.companies) || isNonEmptyArray(d.data) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'pdl',
+    endpoint: '/pdl/company/search',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => {
+      const must: unknown[] = []
+      if (isNonEmptyArray(input.industries))
+        must.push({ terms: { industry: input.industries } })
+      if (isNonEmptyArray(input.countries))
+        must.push({ terms: { 'location.country': input.countries } })
+      if (input.min_employees || input.max_employees)
+        must.push({
+          range: {
+            employee_count: {
+              ...(input.min_employees ? { gte: input.min_employees } : {}),
+              ...(input.max_employees ? { lte: input.max_employees } : {}),
+            },
+          },
+        })
+      if (input.min_founded_year || input.max_founded_year)
+        must.push({
+          range: {
+            founded: {
+              ...(input.min_founded_year ? { gte: input.min_founded_year } : {}),
+              ...(input.max_founded_year ? { lte: input.max_founded_year } : {}),
+            },
+          },
+        })
+      return {
+        body: {
+          query: must.length > 0 ? { bool: { must } } : undefined,
+          size: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || (typeof d.total === 'number' && d.total > 0)
+    },
+  },
+  {
+    id: 'signalbase',
+    endpoint: '/signalbase/companies',
+    method: 'GET',
+    priority: 6,
+    isApplicable: (input) => {
+      // Skip for filter types SignalBase cannot apply — let specialized providers (TheirStack, Wiza,
+      // LimaData) handle these, and fall further down the waterfall when they fail.
+      if (isNonEmptyArray(input.technologies)) return false
+      if (isNonEmptyArray(input.funding_stages)) return false
+      if (typeof input.min_funding_amount === 'number' || typeof input.max_funding_amount === 'number') return false
+      if (typeof input.min_revenue === 'number' || typeof input.max_revenue === 'number') return false
+      if (input.is_hiring === true) return false
+      return true
+    },
+    mapParams: (input) => {
+      // SignalBase has separate `search` (free-text) and `industry` (exact-match) params —
+      // use each for the right input type to maximise precision.
+      const keywords = (input.keywords as string[] | undefined) ?? []
+      const industries = (input.industries as string[] | undefined) ?? []
+      const queryParams: Record<string, string> = {}
+      if (keywords.length > 0) queryParams.search = keywords.join(' ')
+      if (industries.length > 0) queryParams.industry = industries.join(',')
+      if (isNonEmptyArray(input.countries)) queryParams.countries = (input.countries as string[]).join(',')
+      if (typeof input.min_employees === 'number') queryParams.employee_count_min = String(input.min_employees)
+      if (typeof input.max_employees === 'number') queryParams.employee_count_max = String(input.max_employees)
+      if (typeof input.min_founded_year === 'number') queryParams.founded_year_min = String(input.min_founded_year)
+      if (typeof input.max_founded_year === 'number') queryParams.founded_year_max = String(input.max_founded_year)
+      queryParams.limit = String((input.limit as number) ?? 25)
+      return { queryParams }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'blitzapi',
+    endpoint: '/blitzapi/search/companies',
+    method: 'POST',
+    priority: 7,
+    mapParams: (input) => {
+      // BlitzAPI's industry filter expects LinkedIn's exact taxonomy names — free-text
+      // strings rarely match. We rely on `keywords` (forgiving free-text) instead and
+      // fold our `industries` input into keywords as well.
+      const keywords = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ]
+      const countries = (input.countries as string[] | undefined) ?? []
+      const cityIncludes = (input.locations as string[] | undefined) ?? []
+      const company: Record<string, unknown> = {}
+      if (keywords.length > 0) company.keywords = { include: keywords }
+      if (typeof input.min_employees === 'number' || typeof input.max_employees === 'number') {
+        company.employee_count = {
+          ...(typeof input.min_employees === 'number' ? { min: input.min_employees } : {}),
+          ...(typeof input.max_employees === 'number' ? { max: input.max_employees } : {}),
+        }
+      }
+      if (typeof input.min_founded_year === 'number' || typeof input.max_founded_year === 'number') {
+        company.founded_year = {
+          ...(typeof input.min_founded_year === 'number' ? { min: input.min_founded_year } : {}),
+          ...(typeof input.max_founded_year === 'number' ? { max: input.max_founded_year } : {}),
+        }
+      }
+      if (countries.length > 0 || cityIncludes.length > 0) {
+        const hq: Record<string, unknown> = {}
+        if (countries.length > 0) hq.country_code = countries
+        if (cityIncludes.length > 0) hq.city = { include: cityIncludes }
+        company.hq = hq
+      }
+      return {
+        body: {
+          company,
+          max_results: Math.min((input.limit as number) ?? 10, 50),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.companies) || isNonEmptyArray(d.data) || isNonEmptyArray(d.results)
+    },
+    isApplicable: (input) => {
+      // Skip when advanced filters are set that BlitzAPI cannot apply — specialized providers
+      // (TheirStack, Wiza, LimaData) handle these and must run without BlitzAPI intercepting first.
+      if (isNonEmptyArray(input.technologies)) return false
+      if (isNonEmptyArray(input.funding_stages)) return false
+      if (typeof input.min_funding_amount === 'number' || typeof input.max_funding_amount === 'number') return false
+      if (typeof input.min_revenue === 'number' || typeof input.max_revenue === 'number') return false
+      if (isNonEmptyArray(input.exclude_industries) || isNonEmptyArray(input.exclude_countries)) return false
+      if (input.is_hiring === true) return false
+      // Skip when no narrowing filter at all — an unbounded BlitzAPI search is wasteful.
+      const hasKeywords = isNonEmptyArray(input.keywords) || isNonEmptyArray(input.industries)
+      const hasGeo = isNonEmptyArray(input.countries) || isNonEmptyArray(input.locations)
+      const hasSize = typeof input.min_employees === 'number' || typeof input.max_employees === 'number'
+      return hasKeywords || hasGeo || hasSize
+    },
+    postFilter: (data, input) => {
+      const d = { ...(data as Record<string, unknown>) }
+      const minEmp = input.min_employees as number | undefined
+      const maxEmp = input.max_employees as number | undefined
+      if (minEmp === undefined && maxEmp === undefined) return d
+      for (const key of ['results', 'data', 'companies']) {
+        const arr = d[key] as Array<Record<string, unknown>> | undefined
+        if (!Array.isArray(arr)) continue
+        d[key] = arr.filter((o) => {
+          const emp = o.employees_on_linkedin as number | undefined
+          if (typeof emp !== 'number') return true
+          if (minEmp !== undefined && emp < minEmp) return false
+          if (maxEmp !== undefined && emp > maxEmp) return false
+          return true
+        })
+      }
+      return d
+    },
+  },
+  {
+    id: 'limadata',
+    endpoint: '/coldiq/search/companies',
+    method: 'POST',
+    priority: 9,
+    mapParams: (input) => {
+      const keywords = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ]
+      const sizeBuckets = mapEmployeesToLimaDataHeadcount(
+        input.min_employees as number | undefined,
+        input.max_employees as number | undefined,
+      )
+      return {
+        body: {
+          query: keywords.join(' ') || 'company',
+          ...(sizeBuckets.length > 0 && sizeBuckets.length < 8 ? { company_size: sizeBuckets.join(',') } : {}),
+          ...(input.is_hiring === true ? { has_jobs: true } : {}),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'predictleads',
+    endpoint: '/predictleads/discover/companies',
+    method: 'GET',
+    priority: 10,
+    mapParams: (input) => {
+      // PredictLeads requires BOTH `location` AND `sizes` (Zod-required) per its schema.
+      // isApplicable below ensures we only fire when both are derivable.
+      const sizeRanges: string[] = []
+      const min = input.min_employees as number | undefined
+      const max = input.max_employees as number | undefined
+      const ranges: Array<[string, number, number]> = [
+        ['1', 1, 1],
+        ['2-10', 2, 10],
+        ['11-50', 11, 50],
+        ['51-200', 51, 200],
+        ['201-500', 201, 500],
+        ['501-1000', 501, 1000],
+        ['1001-5000', 1001, 5000],
+        ['5001-10000', 5001, 10000],
+        ['10001+', 10001, Number.MAX_SAFE_INTEGER],
+      ]
+      for (const [label, lo, hi] of ranges) {
+        if (hi >= (min ?? 0) && lo <= (max ?? Number.MAX_SAFE_INTEGER)) sizeRanges.push(label)
+      }
+      const locations = [
+        ...((input.locations as string[] | undefined) ?? []),
+        ...((input.countries as string[] | undefined) ?? []),
+      ]
+      const queryParams: Record<string, string> = {
+        location: locations[0],
+        // Skip `sizes` when the range covers all 9 buckets (effectively no filter)
+        ...(sizeRanges.length < 9 ? { sizes: sizeRanges.join(',') } : {}),
+        limit: String((input.limit as number) ?? 25),
+      }
+      return { queryParams }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+    isApplicable: (input) => {
+      // Backend schema requires `location` AND `sizes`. Need at least a country/location
+      // and an employee range — otherwise the call always fails Zod.
+      const hasLocation = isNonEmptyArray(input.locations) || isNonEmptyArray(input.countries)
+      const hasSize = typeof input.min_employees === 'number' || typeof input.max_employees === 'number'
+      return hasLocation && hasSize
+    },
+  },
+  {
+    id: 'theirstack',
+    endpoint: '/theirstack/companies/search',
+    method: 'POST',
+    priority: 4,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.technologies) ||
+      isNonEmptyArray(input.industries) ||
+      isNonEmptyArray(input.funding_stages) ||
+      typeof input.min_funding_amount === 'number' ||
+      typeof input.max_funding_amount === 'number',
+    mapParams: (input) => ({
+      body: {
+        company_technology_slug_or: isNonEmptyArray(input.technologies) ? input.technologies : undefined,
+        industry_or: input.industries,
+        company_country_code_or: input.countries,
+        min_employee_count: input.min_employees,
+        max_employee_count: input.max_employees,
+        funding_stage_or: isNonEmptyArray(input.funding_stages) ? input.funding_stages : undefined,
+        min_funding_usd: input.min_funding_amount,
+        max_funding_usd: input.max_funding_amount,
+        limit: (input.limit as number) ?? 25,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'sumble',
+    endpoint: '/sumble/organizations/find',
+    method: 'POST',
+    priority: 11,
+    mapParams: (input) => {
+      const keywords = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ]
+      const filtersObj: Record<string, unknown> = {}
+      if (keywords.length > 0) filtersObj.query = keywords.join(' ')
+      if (isNonEmptyArray(input.technologies)) filtersObj.technologies = input.technologies
+      return {
+        body: {
+          filters: filtersObj,
+          limit: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.organizations) || isNonEmptyArray(d.data) || isNonEmptyArray(d.results)
+    },
+    isApplicable: (input) =>
+      isNonEmptyArray(input.keywords) ||
+      isNonEmptyArray(input.industries) ||
+      isNonEmptyArray(input.technologies),
+  },
+  {
+    id: 'wiza',
+    endpoint: '/wiza/prospects/create-prospect-list',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) =>
+      typeof input.min_founded_year === 'number' ||
+      typeof input.max_founded_year === 'number' ||
+      isNonEmptyArray(input.funding_stages) ||
+      typeof input.min_funding_amount === 'number' ||
+      typeof input.max_funding_amount === 'number',
+    mapParams: (input) => {
+      // Wiza filters use [{v: 'value'}] shape. Wiza's prospect endpoints return *people*,
+      // but create-prospect-list also returns the company set indirectly via its filters.
+      // For a search_companies waterfall, we treat a non-empty `stats.people` as proof
+      // that the requested filter set matched at least one company.
+      const wrap = (vals?: string[]) => (Array.isArray(vals) && vals.length > 0 ? vals.map((v) => ({ v })) : undefined)
+      const filters: Record<string, unknown> = {}
+      const industries = [
+        ...((input.industries as string[] | undefined) ?? []),
+        ...((input.keywords as string[] | undefined) ?? []),
+      ]
+      // Wiza company_location accepts free-text English names — translate ISO codes.
+      const locations = [
+        ...((input.locations as string[] | undefined) ?? []),
+        ...((input.countries as string[] | undefined) ?? []).map(isoCountryToName),
+      ]
+      if (industries.length > 0) filters.company_industry = wrap(industries)
+      if (locations.length > 0) filters.company_location = wrap(locations)
+      if (typeof input.min_founded_year === 'number') filters.year_founded_start = wrap([String(input.min_founded_year)])
+      if (typeof input.max_founded_year === 'number') filters.year_founded_end = wrap([String(input.max_founded_year)])
+      if (isNonEmptyArray(input.funding_stages)) filters.funding_stage = wrap(input.funding_stages as string[])
+      if (typeof input.min_funding_amount === 'number') filters.funding_min = wrap([String(input.min_funding_amount)])
+      if (typeof input.max_funding_amount === 'number') filters.funding_max = wrap([String(input.max_funding_amount)])
+      const limit = Math.min((input.limit as number) ?? 25, 500)
+      return {
+        body: {
+          list: { name: 'mcp-search-companies', max_profiles: limit },
+          filters,
+          enrichment_level: 'none',
+        },
+      }
+    },
+    hasResult: (data) => {
+      // Final poll response: { status, type, data: { id, status: 'finished', stats: { people } } }
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      const stats = inner?.stats as Record<string, unknown> | undefined
+      const people = stats?.people as number | undefined
+      return typeof people === 'number' && people > 0
+    },
+    async: {
+      extractId: (response) => {
+        const r = response as Record<string, unknown>
+        const inner = r.data as Record<string, unknown> | undefined
+        const id = inner?.id
+        if (typeof id === 'number') return String(id)
+        if (typeof id === 'string' && id.length > 0) return id
+        throw new Error('Wiza response has no list id')
+      },
+      pollEndpoint: (id) => `/wiza/lists/${id}`,
+      pollIntervalMs: 10_000,
+      timeoutMs: 300_000, // 5 min
+      isComplete: (data) => {
+        // Wiza uses different status strings across endpoints — accept all known terminal
+        // states (`finished` for individual reveals, `completed` for lists, plus failures).
+        const d = data as Record<string, unknown>
+        const inner = d.data as Record<string, unknown> | undefined
+        const status = inner?.status as string | undefined
+        return status === 'finished' || status === 'completed' || status === 'failed'
+      },
+    },
+  },
+  {
+    id: 'limadata-prospect-filter',
+    endpoint: '/coldiq/prospect/companies/filter',
+    method: 'POST',
+    priority: 12,
+    mapParams: (input) => {
+      // LimaData prospect filter uses [{filter_type, values}]. We can only reliably
+      // map company_headcount (size buckets); industries/locations need LinkedIn IDs.
+      const filters: Array<{ filter_type: string; values: string[] }> = []
+      const sizeBuckets = mapEmployeesToLimaDataHeadcount(
+        input.min_employees as number | undefined,
+        input.max_employees as number | undefined,
+      )
+      if (sizeBuckets.length > 0 && sizeBuckets.length < 8) {
+        filters.push({ filter_type: 'company_headcount', values: sizeBuckets })
+      }
+      return { body: { filters } }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+    isApplicable: (input) => {
+      // 25 cr/call, charged on success regardless of result count — only fire when
+      // the employee range maps to a non-empty, narrowing bucket set.
+      const buckets = mapEmployeesToLimaDataHeadcount(
+        input.min_employees as number | undefined,
+        input.max_employees as number | undefined,
+      )
+      return buckets.length > 0 && buckets.length < 8
+    },
+  },
+  {
+    id: 'limadata-prospect-url',
+    endpoint: '/coldiq/prospect/companies/search-url',
+    method: 'POST',
+    priority: 13,
+    mapParams: (input) => ({
+      body: { search_url: input.linkedin_search_url as string },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.companies) || isNonEmptyArray(d.results)
+    },
+    isApplicable: (input) => typeof input.linkedin_search_url === 'string' && input.linkedin_search_url.length > 0,
+  },
+  {
+    id: 'linkupapi-search',
+    endpoint: '/linkupapi/data/search/companies',
+    method: 'POST',
+    priority: 14,
+    mapParams: (input) => {
+      const locations = [
+        ...((input.locations as string[] | undefined) ?? []),
+        ...((input.countries as string[] | undefined) ?? []).map(isoCountryToName),
+      ]
+      const minE = input.min_employees as number | undefined
+      const maxE = input.max_employees as number | undefined
+      const employeeRange =
+        typeof minE === 'number' && typeof maxE === 'number' ? `${minE}-${maxE}` : undefined
+      return {
+        body: {
+          keyword: (input.keywords as string[] | undefined)?.join(' ') || undefined,
+          industry: isNonEmptyArray(input.industries) ? (input.industries as string[]) : undefined,
+          location: locations.length > 0 ? locations : undefined,
+          employee_range: employeeRange,
+          total_results: Math.min((input.limit as number) ?? 25, 25),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      return isNonEmptyArray(inner?.companies)
+    },
+  },
+  {
+    id: 'linkupapi-fundraising',
+    endpoint: '/linkupapi/data/fundraising-companies',
+    method: 'POST',
+    priority: 15,
+    isApplicable: (input) => {
+      const hasFundingFilter =
+        isNonEmptyArray(input.funding_stages) ||
+        typeof input.min_funding_amount === 'number' ||
+        typeof input.min_funding_year === 'number'
+      // Linkup fundraising requires a keyword — fire only when we have text to send
+      const hasText = isNonEmptyArray(input.keywords) || isNonEmptyArray(input.industries)
+      return hasFundingFilter && hasText
+    },
+    mapParams: (input) => {
+      const stages = (input.funding_stages as string[] | undefined) ?? []
+      const mappedStage = stages.length > 0 ? toLinkupFundingStage(stages[0]) : undefined
+      const keyword = [
+        ...((input.keywords as string[] | undefined) ?? []),
+        ...((input.industries as string[] | undefined) ?? []),
+      ].join(' ')
+      const minE = input.min_employees as number | undefined
+      const maxE = input.max_employees as number | undefined
+      const employeeRange =
+        typeof minE === 'number' && typeof maxE === 'number' ? `${minE}-${maxE}` : undefined
+      return {
+        body: {
+          keyword,
+          funding_stage: mappedStage,
+          min_funding_amount: input.min_funding_amount,
+          max_funding_amount: input.max_funding_amount,
+          industry: (input.industries as string[] | undefined)?.[0],
+          location: (input.locations as string[] | undefined)?.[0],
+          employee_range: employeeRange,
+          total_results: Math.min((input.limit as number) ?? 25, 25),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      return isNonEmptyArray(inner?.companies)
+    },
+  },
+  {
+    id: 'linkupapi-hiring',
+    endpoint: '/linkupapi/data/hiring-companies',
+    method: 'POST',
+    priority: 16,
+    isApplicable: (input) => input.is_hiring === true,
+    mapParams: (input) => {
+      const minE = input.min_employees as number | undefined
+      const maxE = input.max_employees as number | undefined
+      const employeeRange =
+        typeof minE === 'number' && typeof maxE === 'number' ? `${minE}-${maxE}` : undefined
+      return {
+        body: {
+          industry: (input.industries as string[] | undefined)?.[0],
+          location:
+            (input.locations as string[] | undefined)?.[0] ??
+            (input.countries as string[] | undefined)?.map(isoCountryToName)[0],
+          employee_range: employeeRange,
+          total_results: Math.min((input.limit as number) ?? 25, 25),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      return isNonEmptyArray(inner?.companies)
+    },
+  },
+  {
+    id: 'prospeo-search-company',
+    endpoint: '/prospeo/search-company',
+    method: 'POST',
+    priority: 17,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.keywords) ||
+      isNonEmptyArray(input.industries) ||
+      isNonEmptyArray(input.countries),
+    mapParams: (input) => ({
+      body: {
+        filters: {
+          ...(isNonEmptyArray(input.keywords) && {
+            company_keywords: { include: input.keywords },
+          }),
+          ...(isNonEmptyArray(input.industries) && {
+            company_industry: { include: input.industries },
+          }),
+          ...(isNonEmptyArray(input.countries) && {
+            company_country: { include: (input.countries as string[]).map(isoCountryToName) },
+          }),
+          ...((input.min_employees !== undefined || input.max_employees !== undefined) && {
+            company_headcount_custom: {
+              min: input.min_employees,
+              max: input.max_employees,
+            },
+          }),
+        },
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data)
+    },
+  },
+  {
+    id: 'ai-ark-companies',
+    endpoint: '/ai-ark/companies',
+    method: 'POST',
+    priority: 18,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.keywords) ||
+      isNonEmptyArray(input.industries) ||
+      isNonEmptyArray(input.countries),
+    mapParams: (input) => ({
+      body: {
+        account: {
+          ...(isNonEmptyArray(input.industries) && {
+            industries: { any: { include: input.industries } },
+          }),
+          ...(isNonEmptyArray(input.countries) && {
+            location: { any: { include: (input.countries as string[]).map(isoCountryToName) } },
+          }),
+          ...((input.min_employees !== undefined || input.max_employees !== undefined) && {
+            employeeSize: {
+              type: 'RANGE',
+              range: [{ start: input.min_employees, end: input.max_employees }],
+            },
+          }),
+          ...(isNonEmptyArray(input.funding_stages) && {
+            funding: { stage: { include: input.funding_stages } },
+          }),
+        },
+        ...(isNonEmptyArray(input.keywords) && {
+          contact: {
+            keywordsInProfile: { any: { include: input.keywords } },
+          },
+        }),
+        size: Math.min((input.limit as number | undefined) ?? 10, 100),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.content)
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// find_people
+// ---------------------------------------------------------------------------
+
+// Level-indicator prefixes sorted longest-first to avoid partial matches.
+const TITLE_LEVEL_PREFIXES = [
+  'executive vice president', 'senior vice president', 'managing director',
+  'vice president', 'president of',
+  'director of the', 'head of the',
+  'director of', 'head of', 'manager of', 'chief of', 'president',
+  'director', 'head', 'manager', 'chief',
+  'vp of', 'sr vp',
+  'vp', 'svp', 'evp', 'avp',
+  'senior', 'sr', 'lead',
+]
+
+// C-suite abbreviations map to a stable domain key so "CEO" and
+// "Chief Executive Officer" collapse into the same persona group.
+const TITLE_C_SUITE_DOMAIN: Record<string, string> = {
+  ceo: '__ceo__', cfo: '__cfo__', cto: '__cto__', cmo: '__cmo__',
+  cro: '__cro__', coo: '__coo__', cpo: '__cpo__', ciso: '__ciso__',
+}
+
+function titleDomainKey(title: string): string {
+  const t = title.toLowerCase().trim()
+  if (TITLE_C_SUITE_DOMAIN[t]) return TITLE_C_SUITE_DOMAIN[t]
+  // "Chief X Officer" → domain is X
+  const chiefMatch = t.match(/^chief\s+(.+?)\s+officer$/)
+  if (chiefMatch) return chiefMatch[1].trim()
+  for (const prefix of TITLE_LEVEL_PREFIXES) {
+    if (t.startsWith(prefix + ' ')) {
+      return t.slice(prefix.length + 1).replace(/^(of|the)\s+/, '').trim()
+    }
+  }
+  return t
+}
+
+const findPeopleProviders: ProviderEntry[] = [
+  {
+    id: 'leadsfactory',
+    endpoint: '/leadsfactory/contact-finder/searches',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => {
+      const rawTitles = (input.job_titles as string[] | undefined) ?? []
+      // Step 1: deduplicate near-identical "of" variants (e.g. "VP Sales" ≡ "VP of Sales")
+      const normalizeOf = (t: string) =>
+        t.toLowerCase().replace(/\s+of\s+/g, ' ').replace(/\s+/g, ' ').trim()
+      const seenNorm = new Set<string>()
+      const deduped = rawTitles
+        .map((t) => t.trim()).filter((t) => t.length > 0)
+        .filter((t) => { const n = normalizeOf(t); if (seenNorm.has(n)) return false; seenNorm.add(n); return true })
+      // Step 2: group by domain — same domain (e.g. "VP Sales" + "Head of Sales" → "sales")
+      // gets one persona with comma-joined titles; different domains get separate personas.
+      const groups = new Map<string, string[]>()
+      for (const title of deduped) {
+        const key = titleDomainKey(title)
+        const g = groups.get(key)
+        if (g) g.push(title)
+        else groups.set(key, [title])
+      }
+      const personas =
+        groups.size > 0
+          ? [...groups.values()].map((titles) => ({ job_title: titles.join(', ') }))
+          : [{ job_title: 'Decision Maker' }]
+      const hasLinkedInUrls = isNonEmptyArray(input.company_linkedin_urls)
+      return {
+        body: {
+          ...(hasLinkedInUrls && { company_linkedin_urls: input.company_linkedin_urls }),
+          // Only pass domains when no LinkedIn URLs — LF uses LinkedIn URLs as the faster
+          // primary identifier; mixing both slows the search. Domains-only path also enables
+          // no_results_domains gap-fill with Apollo.
+          ...(!hasLinkedInUrls && isNonEmptyArray(input.company_domains) && { company_domains: input.company_domains }),
+          search: {
+            max_persona_results: (input.limit as number) ?? 25,
+            personas,
+          },
+        },
+      }
+    },
+    hasResult: (data) => {
+      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)
+      )
+    },
+    async: {
+      pollEndpoint: (id: string) => `/leadsfactory/contact-finder/searches/${id}`,
+      pollIntervalMs: 15000,
+      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'
+      },
+      extractId: (response) => {
+        const d = response as Record<string, unknown>
+        return (d._id as string) ?? (d.search_id as string)
+      },
+    },
+  },
+  {
+    id: 'apollo',
+    endpoint: '/apollo/people/search',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => ({
+      body: {
+        person_titles: input.job_titles,
+        q_organization_domains: input.company_domains,
+        person_seniorities: input.seniorities,
+        person_locations: input.locations,
+        q_keywords: (input.keywords as string[] | undefined)?.join(' ') || undefined,
+        per_page: (input.limit as number) ?? 25,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.people) || isNonEmptyArray(d.contacts)
+    },
+  },
+  {
+    id: 'pdl',
+    endpoint: '/pdl/person/search',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => {
+      const must: unknown[] = []
+      if (isNonEmptyArray(input.job_titles))
+        must.push({ terms: { job_title: input.job_titles } })
+      if (isNonEmptyArray(input.company_domains))
+        must.push({ terms: { job_company_website: input.company_domains } })
+      if (isNonEmptyArray(input.seniorities))
+        must.push({ terms: { job_title_levels: input.seniorities } })
+      if (isNonEmptyArray(input.locations))
+        must.push({ terms: { location_country: input.locations } })
+      return {
+        body: {
+          query: must.length > 0 ? { bool: { must } } : undefined,
+          size: (input.limit as number) ?? 25,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || (typeof d.total === 'number' && d.total > 0)
+    },
+  },
+  {
+    id: 'companyenrich',
+    endpoint: '/companyenrich/people/search',
+    method: 'POST',
+    priority: 4,
+    mapParams: (input) => ({
+      body: {
+        filters: {
+          jobTitles: input.job_titles,
+          countries: input.locations,
+        },
+        pageSize: (input.limit as number) ?? 25,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.results) || isNonEmptyArray(d.people)
+    },
+  },
+  {
+    id: 'linkupapi-search-profiles',
+    endpoint: '/linkupapi/data/search/profiles',
+    method: 'POST',
+    priority: 5,
+    // Linkup search-profiles accepts company names, not domains/LinkedIn URLs.
+    // Skip when the caller has specific company identifiers — earlier providers handle those better.
+    isApplicable: (input) =>
+      !isNonEmptyArray(input.company_linkedin_urls) && !isNonEmptyArray(input.company_domains),
+    mapParams: (input) => ({
+      body: {
+        keyword: (input.keywords as string[] | undefined)?.join(' ') || undefined,
+        job_title: isNonEmptyArray(input.job_titles) ? (input.job_titles as string[]) : undefined,
+        location: isNonEmptyArray(input.locations) ? (input.locations as string[]) : undefined,
+        total_results: Math.min((input.limit as number) ?? 25, 25),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      return isNonEmptyArray(inner?.profiles)
+    },
+  },
+  {
+    id: 'sumble-people-find',
+    endpoint: '/sumble/people/find',
+    method: 'POST',
+    priority: 6,
+    // Requires a company identifier; otherwise Sumble has nothing to scope the search against.
+    isApplicable: (input) =>
+      (isNonEmptyArray(input.company_domains) || isNonEmptyArray(input.company_linkedin_urls)) &&
+      (isNonEmptyArray(input.job_titles) || isNonEmptyArray(input.seniorities)),
+    mapParams: (input) => {
+      const domains = input.company_domains as string[] | undefined
+      const urls = input.company_linkedin_urls as string[] | undefined
+      const org = domains?.[0] ? { domain: domains[0] } : { linkedin_url: urls?.[0] }
+      return {
+        body: {
+          organization: org,
+          filters: {
+            job_functions: isNonEmptyArray(input.job_titles) ? input.job_titles : undefined,
+            job_levels: isNonEmptyArray(input.seniorities) ? input.seniorities : undefined,
+            countries: isNonEmptyArray(input.locations) ? input.locations : undefined,
+            query: isNonEmptyArray(input.keywords)
+              ? (input.keywords as string[]).join(' ')
+              : undefined,
+          },
+          limit: Math.min((input.limit as number | undefined) ?? 10, 100),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.people)
+    },
+  },
+  {
+    id: 'prospeo-search-person',
+    endpoint: '/prospeo/search-person',
+    method: 'POST',
+    priority: 7,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.job_titles) ||
+      isNonEmptyArray(input.company_domains),
+    mapParams: (input) => ({
+      body: {
+        filters: {
+          ...(isNonEmptyArray(input.job_titles) && {
+            job_title: { include: input.job_titles },
+          }),
+          ...(isNonEmptyArray(input.seniorities) && {
+            person_seniority: { include: input.seniorities },
+          }),
+          ...(isNonEmptyArray(input.company_domains) && {
+            company: { websites: { include: input.company_domains } },
+          }),
+          ...(isNonEmptyArray(input.locations) && {
+            person_location: { include: input.locations },
+          }),
+        },
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data)
+    },
+  },
+  {
+    id: 'ai-ark-people',
+    endpoint: '/ai-ark/people',
+    method: 'POST',
+    priority: 8,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.job_titles) ||
+      isNonEmptyArray(input.seniorities) ||
+      isNonEmptyArray(input.keywords),
+    mapParams: (input) => ({
+      body: {
+        contact: {
+          ...(isNonEmptyArray(input.job_titles) && {
+            departmentAndFunction: { any: { include: input.job_titles } },
+          }),
+          ...(isNonEmptyArray(input.seniorities) && {
+            seniority: { any: { include: input.seniorities } },
+          }),
+          ...(isNonEmptyArray(input.locations) && {
+            location: { any: { include: input.locations } },
+          }),
+          ...(isNonEmptyArray(input.keywords) && {
+            keywordsInProfile: { any: { include: input.keywords } },
+          }),
+        },
+        size: Math.min((input.limit as number | undefined) ?? 10, 100),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.content)
+    },
+  },
+  {
+    id: 'fullenrich-people-search',
+    endpoint: '/fullenrich/people/search',
+    method: 'POST',
+    priority: 9,
+    mapParams: (input) => ({
+      body: {
+        current_company_domains: isNonEmptyArray(input.company_domains)
+          ? (input.company_domains as string[]).map((v) => ({ value: v }))
+          : undefined,
+        current_position_titles: isNonEmptyArray(input.job_titles)
+          ? (input.job_titles as string[]).map((v) => ({ value: v }))
+          : undefined,
+        current_position_seniority_level: isNonEmptyArray(input.seniorities)
+          ? (input.seniorities as string[]).map((v) => ({ value: v }))
+          : undefined,
+        person_locations: isNonEmptyArray(input.locations)
+          ? (input.locations as string[]).map((v) => ({ value: v }))
+          : undefined,
+        limit: Math.min((input.limit as number | undefined) ?? 10, 100),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.people)
+    },
+  },
+  {
+    id: 'findymail-search-employees',
+    endpoint: '/findymail/search/employees',
+    method: 'POST',
+    priority: 10,
+    // Findymail employees search requires a domain and at least one job title.
+    isApplicable: (input) =>
+      isNonEmptyArray(input.company_domains) && isNonEmptyArray(input.job_titles),
+    mapParams: (input) => ({
+      body: {
+        website: (input.company_domains as string[])[0],
+        job_titles: input.job_titles,
+        // count is capped at 5 by the Findymail API; don't exceed it
+        count: Math.min((input.limit as number | undefined) ?? 5, 5),
+      },
+    }),
+    hasResult: (data) => {
+      // Findymail returns an array directly or wraps in a contacts/results key
+      if (Array.isArray(data)) return (data as unknown[]).length > 0
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['contacts', 'results', 'people'])
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// find_email (waterfall)
+// ---------------------------------------------------------------------------
+
+const findEmailProviders: ProviderEntry[] = [
+  {
+    id: 'findymail',
+    endpoint: '/findymail/search/name',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => ({
+      body: {
+        name: `${input.first_name} ${input.last_name}`,
+        domain: input.domain,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return typeof d.email === 'string' && d.email.includes('@')
+    },
+  },
+  {
+    id: 'icypeas',
+    endpoint: '/icypeas/email-search',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => ({
+      body: {
+        firstname: input.first_name,
+        lastname: input.last_name,
+        domainOrCompany: input.domain || input.company_name,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return (
+        (typeof d.email === 'string' && d.email.includes('@')) ||
+        isNonEmptyArray(d.emails)
+      )
+    },
+  },
+  {
+    id: 'limadata-work-email',
+    endpoint: '/coldiq/find/work-email',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => {
+      const fullName = [input.first_name, input.last_name].filter(Boolean).join(' ')
+      return {
+        body: {
+          full_name: fullName,
+          company_domain: input.domain,
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      // Upstream is a thin proxy — match common B2B email shapes.
+      if (typeof d.email === 'string' && d.email.includes('@')) return true
+      if (Array.isArray(d.emails) && typeof d.emails[0] === 'string' && (d.emails[0] as string).includes('@')) return true
+      const nested = d.data as Record<string, unknown> | undefined
+      if (nested && typeof nested.email === 'string' && (nested.email as string).includes('@')) return true
+      return false
+    },
+    isApplicable: (input) =>
+      typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
+      typeof input.last_name === 'string' && (input.last_name as string).length > 0 &&
+      typeof input.domain === 'string' && (input.domain as string).length > 0,
+  },
+  {
+    id: 'prospeo',
+    endpoint: '/prospeo/enrich-person',
+    method: 'POST',
+    priority: 4,
+    mapParams: (input) => {
+      if (input.linkedin_url) {
+        return { body: { data: { linkedin_url: input.linkedin_url } } }
+      }
+      return {
+        body: {
+          data: {
+            first_name: input.first_name,
+            last_name: input.last_name,
+            company_name: input.company_name || input.domain,
+          },
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const person = d.person as Record<string, unknown> | undefined
+      const emailObj = person?.email as Record<string, unknown> | undefined
+      return typeof emailObj?.email === 'string' && (emailObj.email as string).includes('@')
+    },
+  },
+  {
+    id: 'blitzapi',
+    endpoint: '/blitzapi/enrichment/find-work-email',
+    method: 'POST',
+    priority: 5,
+    mapParams: (input) => ({
+      body: { person_linkedin_url: input.linkedin_url as string },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return typeof d.email === 'string' && d.email.includes('@')
+    },
+    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0,
+  },
+  {
+    id: 'fullenrich',
+    endpoint: '/fullenrich/contact/enrich/bulk',
+    method: 'POST',
+    priority: 6,
+    mapParams: (input) => ({
+      body: {
+        name: 'mcp-enrich',
+        data: [{
+          first_name: input.first_name,
+          last_name: input.last_name,
+          domain: input.domain,
+          company_name: input.company_name,
+          ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+          enrich_fields: ['contact.emails'],
+        }],
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const items = d.data as Array<Record<string, unknown>> | undefined
+      if (!Array.isArray(items) || items.length === 0) return false
+      const emails = items[0]?.emails as unknown[] | undefined
+      return Array.isArray(emails) && emails.length > 0
+    },
+    async: {
+      extractId: (response) => {
+        const d = response as Record<string, unknown>
+        return d.enrichment_id as string
+      },
+      pollEndpoint: (id) => `/fullenrich/contact/enrich/bulk/${id}`,
+      pollIntervalMs: 5000,
+      timeoutMs: 60_000,
+      isComplete: (data) => {
+        const d = data as Record<string, unknown>
+        const status = d.status as string | undefined
+        return status === 'DONE' || status === 'FAILED'
+      },
+    },
+  },
+  {
+    id: 'limadata-work-email-linkedin',
+    endpoint: '/coldiq/find/work-email-linkedin',
+    method: 'POST',
+    priority: 7,
+    mapParams: (input) => ({
+      body: { linkedin_url: input.linkedin_url as string },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      if (typeof d.email === 'string' && d.email.includes('@')) return true
+      if (Array.isArray(d.emails) && typeof d.emails[0] === 'string' && (d.emails[0] as string).includes('@')) return true
+      const nested = d.data as Record<string, unknown> | undefined
+      if (nested && typeof nested.email === 'string' && (nested.email as string).includes('@')) return true
+      return false
+    },
+    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0,
+  },
+  {
+    id: 'linkupapi',
+    endpoint: '/linkupapi/data/mail/finder',
+    method: 'POST',
+    priority: 8,
+    mapParams: (input) => ({
+      body: {
+        first_name: input.first_name,
+        last_name: input.last_name,
+        company_name: input.company_name || input.domain,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return typeof d.email === 'string' && d.email.includes('@')
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// verify_email
+// ---------------------------------------------------------------------------
+
+const INSTANTLY_TERMINAL_STATUSES = new Set(['valid', 'invalid', 'unknown', 'risky', 'catch_all', 'disposable'])
+
+const verifyEmailProviders: ProviderEntry[] = [
+  {
+    id: 'findymail',
+    endpoint: '/findymail/verify',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      // Findymail verify returns { email, verified: boolean, provider }
+      return d.verified !== undefined || d.status !== undefined || d.result !== undefined || d.valid !== undefined
+    },
+  },
+  {
+    id: 'icypeas',
+    endpoint: '/icypeas/email-verification',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      // IcyPeas verify returns { success: boolean, item: { status } }
+      return d.success !== undefined || d.status !== undefined || d.result !== undefined || d.valid !== undefined
+    },
+  },
+  {
+    id: 'instantly',
+    endpoint: '/instantly/email-verification',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const status = d.status as string | undefined
+      return typeof status === 'string' && INSTANTLY_TERMINAL_STATUSES.has(status)
+    },
+    async: {
+      extractId: (response) => {
+        const r = response as Record<string, unknown>
+        if (typeof r.email === 'string' && r.email.length > 0) return r.email
+        throw new Error('Instantly verification response has no email field')
+      },
+      pollEndpoint: (email) => `/instantly/email-verification/${encodeURIComponent(email)}`,
+      pollIntervalMs: 3000,
+      timeoutMs: 30_000,
+      isComplete: (data) => {
+        const d = data as Record<string, unknown>
+        const status = d.status as string | undefined
+        return typeof status === 'string' && INSTANTLY_TERMINAL_STATUSES.has(status)
+      },
+    },
+  },
+  {
+    id: 'linkupapi-validate',
+    endpoint: '/linkupapi/data/mail/validate',
+    method: 'POST',
+    priority: 4,
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.verified !== undefined || d.status !== undefined || d.result !== undefined || d.valid !== undefined
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// find_phone
+// ---------------------------------------------------------------------------
+
+const findPhoneProviders: ProviderEntry[] = [
+  {
+    id: 'findymail',
+    endpoint: '/findymail/search/phone',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0,
+    mapParams: (input) => ({ body: { linkedin_url: input.linkedin_url } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return typeof d.phone === 'string' || isNonEmptyArray(d.phones)
+    },
+  },
+  {
+    id: 'limadata',
+    endpoint: '/coldiq/find/phone',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => {
+      if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
+      const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
+        typeof input.last_name === 'string' && (input.last_name as string).length > 0
+      const hasCompany = (typeof input.company_domain === 'string' && (input.company_domain as string).length > 0) ||
+        (typeof input.company_name === 'string' && (input.company_name as string).length > 0)
+      return hasName && hasCompany
+    },
+    mapParams: (input) => {
+      const firstName = input.first_name as string | undefined
+      const lastName = input.last_name as string | undefined
+      const fullName = [firstName, lastName].filter(Boolean).join(' ') || undefined
+      return {
+        body: {
+          ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+          ...(fullName ? { name: fullName } : {}),
+          ...(input.company_name ? { company_name: input.company_name } : {}),
+          ...(input.company_domain ? { company_domain: input.company_domain } : {}),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      if (typeof d.phone === 'string' && (d.phone as string).length > 0) return true
+      if (isNonEmptyArray(d.phones)) return true
+      if (isNonEmptyArray(d.phone_numbers)) return true
+      const nested = d.data as Record<string, unknown> | undefined
+      if (nested && typeof nested.phone === 'string' && (nested.phone as string).length > 0) return true
+      if (nested && isNonEmptyArray(nested.phones)) return true
+      if (nested && isNonEmptyArray(nested.phone_numbers)) return true
+      return false
+    },
+  },
+  {
+    id: 'ai-ark',
+    endpoint: '/ai-ark/people/mobile-phone-finder',
+    method: 'POST',
+    priority: 3,
+    isApplicable: (input) => {
+      if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
+      const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
+        typeof input.last_name === 'string' && (input.last_name as string).length > 0
+      const hasDomain = typeof input.company_domain === 'string' && (input.company_domain as string).length > 0
+      return hasName && hasDomain
+    },
+    mapParams: (input) => {
+      const firstName = input.first_name as string | undefined
+      const lastName = input.last_name as string | undefined
+      const fullName = [firstName, lastName].filter(Boolean).join(' ') || undefined
+      return {
+        body: {
+          ...(input.linkedin_url ? { linkedin: input.linkedin_url } : {}),
+          ...(input.company_domain ? { domain: input.company_domain } : {}),
+          ...(fullName ? { name: fullName } : {}),
+        },
+      }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return Array.isArray(d.data) &&
+        (d.data as unknown[]).some(
+          (arr) => Array.isArray(arr) && (arr as unknown[]).length > 0 && typeof (arr as unknown[])[0] === 'string',
+        )
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// enrich_company
+// ---------------------------------------------------------------------------
+
+const enrichCompanyProviders: ProviderEntry[] = [
+  {
+    id: 'companyenrich',
+    endpoint: '/companyenrich/companies/enrich',
+    method: 'GET',
+    priority: 1,
+    isApplicable: (input) => !!input.domain,
+    mapParams: (input) => ({
+      queryParams: { domain: input.domain as string },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain', 'company'])
+    },
+  },
+  {
+    id: 'apollo',
+    endpoint: '/apollo/organizations/enrich',
+    method: 'POST',
+    priority: 3,
+    isApplicable: (input) => !!input.domain,
+    mapParams: (input) => ({ body: { domain: input.domain } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['organization', 'name', 'domain'])
+    },
+  },
+  {
+    id: 'pdl',
+    endpoint: '/pdl/company/enrich',
+    method: 'GET',
+    priority: 2,
+    mapParams: (input) => ({
+      queryParams: {
+        ...(input.domain ? { website: input.domain as string } : {}),
+        ...(input.linkedin_url ? { profile: input.linkedin_url as string } : {}),
+        ...(input.name ? { name: input.name as string } : {}),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'website', 'display_name'])
+    },
+  },
+  {
+    id: 'findymail',
+    endpoint: '/findymail/search/company',
+    method: 'POST',
+    priority: 9,
+    mapParams: (input) => ({
+      body: {
+        ...(input.domain ? { domain: input.domain } : {}),
+        ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+        ...(input.name ? { name: input.name } : {}),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain'])
+    },
+  },
+  {
+    id: 'wiza',
+    endpoint: '/wiza/company-enrichments',
+    method: 'POST',
+    priority: 8,
+    isApplicable: (input) => !!(input.domain || input.name),
+    mapParams: (input) => ({
+      body: {
+        ...(input.domain ? { company_domain: input.domain } : {}),
+        ...(input.name ? { company_name: input.name } : {}),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const inner = d.data as Record<string, unknown> | undefined
+      return !!(inner?.domain || inner?.industry || inner?.description)
+    },
+  },
+  {
+    id: 'limadata',
+    endpoint: '/coldiq/enrich/company',
+    method: 'POST',
+    priority: 4,
+    isApplicable: (input) => !!(input.domain || input.linkedin_url),
+    mapParams: (input) => ({
+      body: {
+        ...(input.domain ? { domain: input.domain } : {}),
+        ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain', 'website', 'data'])
+    },
+  },
+  {
+    id: 'prospeo',
+    endpoint: '/prospeo/enrich-company',
+    method: 'POST',
+    priority: 5,
+    mapParams: (input) => ({
+      body: {
+        data: {
+          ...(input.domain ? { company_website: input.domain } : {}),
+          ...(input.linkedin_url ? { company_linkedin_url: input.linkedin_url } : {}),
+          ...(input.name ? { company_name: input.name } : {}),
+        },
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return !d.error && !!d.response
+    },
+  },
+  {
+    id: 'companyenrich_props',
+    endpoint: '/companyenrich/companies/enrich',
+    method: 'POST',
+    priority: 6,
+    isApplicable: (input) => !!(input.name || input.linkedin_url),
+    mapParams: (input) => ({
+      body: {
+        ...(input.name ? { name: input.name } : {}),
+        ...(input.linkedin_url ? { linkedinUrl: input.linkedin_url } : {}),
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain', 'company'])
+    },
+  },
+  {
+    id: 'blitzapi',
+    endpoint: '/blitzapi/enrichment/company',
+    method: 'POST',
+    priority: 7,
+    isApplicable: (input) => !!input.linkedin_url,
+    mapParams: (input) => ({
+      body: { company_linkedin_url: input.linkedin_url },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain', 'website', 'id'])
+    },
+  },
+  {
+    id: 'icypeas',
+    endpoint: '/icypeas/scrape/company',
+    method: 'POST',
+    priority: 10,
+    isApplicable: (input) => !!input.linkedin_url,
+    mapParams: (input) => ({
+      body: { url: input.linkedin_url },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['name', 'domain', 'website', 'universal_name'])
+    },
+  },
+  {
+    id: 'builtwith',
+    endpoint: '/builtwith/domain',
+    method: 'POST',
+    priority: 11,
+    isApplicable: (input) => !!input.domain,
+    mapParams: (input) => ({ body: { domain: input.domain } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const results = d.Results as Array<Record<string, unknown>> | undefined
+      if (!Array.isArray(results) || results.length === 0) return false
+      const inner = results[0]?.Result as Record<string, unknown> | undefined
+      const paths = inner?.Paths as unknown[] | undefined
+      return Array.isArray(paths) && paths.length > 0
+    },
+  },
+  {
+    id: 'openmart',
+    endpoint: '/openmart/enrich_company',
+    method: 'POST',
+    priority: 12,
+    isApplicable: (input) => !!input.domain,
+    mapParams: (input) => ({ body: { website: input.domain, limit: 1 } }),
+    hasResult: (data) => {
+      if (isNonEmptyArray(data)) return true
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'linkupapi-by-domain',
+    endpoint: '/linkupapi/data/company/info-by-domain',
+    method: 'POST',
+    priority: 13,
+    isApplicable: (input) => !!input.domain,
+    mapParams: (input) => ({ body: { domain: input.domain } }),
+    hasResult: (data) => hasAnyKey(data, ['name', 'domain', 'website', 'company']),
+  },
+  {
+    id: 'linkupapi-by-url',
+    endpoint: '/linkupapi/data/company/info',
+    method: 'POST',
+    priority: 14,
+    isApplicable: (input) => !!input.linkedin_url,
+    mapParams: (input) => ({ body: { company_url: input.linkedin_url } }),
+    hasResult: (data) => hasAnyKey(data, ['name', 'domain', 'website', 'company']),
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_web
+// ---------------------------------------------------------------------------
+
+const searchWebProviders: ProviderEntry[] = [
+  {
+    id: 'serper',
+    endpoint: '/serper/search',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => ({
+      body: {
+        q: input.query,
+        num: input.num_results ?? 10,
+        gl: input.country,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.organic) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'exa',
+    endpoint: '/exa/search',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => ({
+      body: {
+        query: input.query,
+        numResults: input.num_results ?? 10,
+        type: input.search_type === 'neural' ? 'neural' : 'auto',
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'limadata',
+    endpoint: '/coldiq/search/web',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => ({
+      body: { query: input.query },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.organic) || isNonEmptyArray(d.results)
+    },
+  },
+  {
+    id: 'jina',
+    endpoint: '/jina/search',
+    method: 'POST',
+    priority: 4,
+    mapParams: (input) => ({
+      body: {
+        q: input.query,
+        // Jina caps at 20 results per call vs the tool's 100 max
+        count: Math.min((input.num_results as number | undefined) ?? 10, 20),
+        gl: input.country,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.data) || isNonEmptyArray(d.results)
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_jobs
+// ---------------------------------------------------------------------------
+
+// Keys in the MCP schema that only LinkedIn Jobs API can serve.
+// If any of these are set, Career Site Jobs is skipped.
+const _LINKEDIN_ONLY_KEYS = ['seniority_levels', 'industries', 'organization_slugs', 'exclude_organization_slugs', 'min_employees', 'max_employees', 'easy_apply_only', 'exclude_easy_apply']
+
+// Keys in the MCP schema that only Career Site Jobs can serve.
+// If any of these are set, LinkedIn Jobs API is skipped.
+const _CAREER_SITE_ONLY_KEYS = ['ats_slugs', 'exclude_ats_slugs', 'company_domains', 'exclude_company_domains']
+
+function _hasJobFilter(input: Record<string, unknown>, keys: string[]): boolean {
+  return keys.some((k) => {
+    const v = input[k]
+    return !!v && (!Array.isArray(v) || v.length > 0)
+  })
+}
+
+const _jobsSharedAsync = {
+  pollIntervalMs: 5_000,
+  timeoutMs: 300_000,
+  extractId: (data: unknown) => {
+    const jobId = (data as { jobId?: number | string }).jobId
+    if (jobId === undefined || jobId === null || jobId === '') {
+      throw new Error('Jobs response has no jobId')
+    }
+    return String(jobId)
+  },
+  isComplete: (data: unknown) => {
+    const s = (data as { status?: string }).status
+    return s === 'done' || s === 'failed' || s === 'timed_out'
+  },
+}
+
+const searchJobsProviders: ProviderEntry[] = [
+  {
+    id: 'career_site_jobs',
+    endpoint: '/career-site-jobs/search',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => !_hasJobFilter(input, _LINKEDIN_ONLY_KEYS),
+    mapParams: (input) => ({
+      body: {
+        limit: Math.min(Math.max((input.limit as number | undefined) ?? 25, 10), 500),
+        timeRange: input.time_range,
+        titleSearch: input.title_keywords,
+        titleExclusionSearch: input.exclude_title_keywords,
+        locationSearch: input.locations,
+        locationExclusionSearch: input.exclude_locations,
+        descriptionSearch: input.description_keywords,
+        descriptionExclusionSearch: input.exclude_description_keywords,
+        organizationSearch: input.companies,
+        organizationExclusionSearch: input.exclude_companies,
+        domainFilter: input.company_domains,
+        domainExclusionFilter: input.exclude_company_domains,
+        ats: input.ats_slugs,
+        atsExclusionFilter: input.exclude_ats_slugs,
+        descriptionType: input.include_description ? 'text' : undefined,
+        remote: input.remote,
+        removeAgency: input.exclude_agencies,
+        datePostedAfter: input.posted_after,
+        includeAi: true,
+        aiEmploymentTypeFilter: input.employment_types,
+        aiWorkArrangementFilter: input.work_arrangements,
+        aiHasSalary: input.has_salary,
+        aiExperienceLevelFilter: input.experience_levels,
+        aiVisaSponsorshipFilter: input.has_visa_sponsorship,
+        aiTaxonomiesFilter: input.taxonomies,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { jobs?: unknown[] }).jobs),
+    async: {
+      ..._jobsSharedAsync,
+      pollEndpoint: (id) => `/career-site-jobs/search/${id}`,
+    },
+  },
+  {
+    id: 'linkedin_jobs_api',
+    endpoint: '/linkedin-jobs-api/search',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => !_hasJobFilter(input, _CAREER_SITE_ONLY_KEYS),
+    mapParams: (input) => ({
+      body: {
+        limit: Math.min(Math.max((input.limit as number | undefined) ?? 25, 10), 500),
+        timeRange: input.time_range,
+        titleSearch: input.title_keywords,
+        titleExclusionSearch: input.exclude_title_keywords,
+        locationSearch: input.locations,
+        // upstream field is intentionally misspelled — match it verbatim
+        locationExclusionSeach: input.exclude_locations,
+        descriptionSearch: input.description_keywords,
+        descriptionExclusionSearch: input.exclude_description_keywords,
+        organizationSearch: input.companies,
+        organizationExclusionSearch: input.exclude_companies,
+        organizationSlugFilter: input.organization_slugs,
+        organizationSlugExclusionFilter: input.exclude_organization_slugs,
+        industryFilter: input.industries,
+        organizationEmployeesGte: input.min_employees,
+        organizationEmployeesLte: input.max_employees,
+        seniorityFilter: input.seniority_levels,
+        descriptionType: input.include_description ? 'text' : undefined,
+        remote: input.remote,
+        removeAgency: input.exclude_agencies,
+        datePostedAfter: input.posted_after,
+        includeAi: true,
+        // upstream uses PascalCase — match it verbatim
+        EmploymentTypeFilter: input.employment_types,
+        aiWorkArrangementFilter: input.work_arrangements,
+        aiHasSalary: input.has_salary,
+        aiExperienceLevelFilter: input.experience_levels,
+        aiVisaSponsorshipFilter: input.has_visa_sponsorship,
+        aiTaxonomiesFilter: input.taxonomies,
+        directApply: input.easy_apply_only === true ? true : undefined,
+        noDirectApply: input.exclude_easy_apply === true ? true : undefined,
+        excludeATSDuplicate: true,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { jobs?: unknown[] }).jobs),
+    async: {
+      ..._jobsSharedAsync,
+      pollEndpoint: (id) => `/linkedin-jobs-api/search/${id}`,
+    },
+  },
+  {
+    id: 'theirstack-jobs',
+    endpoint: '/theirstack/jobs/search',
+    method: 'POST',
+    priority: 3,
+    isApplicable: (input) =>
+      isNonEmptyArray(input.title_keywords as unknown[]) ||
+      isNonEmptyArray(input.description_keywords as unknown[]) ||
+      isNonEmptyArray(input.companies as unknown[]) ||
+      isNonEmptyArray(input.company_domains as unknown[]),
+    mapParams: (input) => ({
+      body: {
+        job_title_pattern_or: input.title_keywords,
+        job_description_pattern_or: input.description_keywords,
+        company_name_or: input.companies,
+        company_domain_or: input.company_domains,
+        posted_at_gte: input.posted_after,
+        limit: input.limit,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { data?: unknown[] }).data),
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_ads
+// ---------------------------------------------------------------------------
+
+const _adsSharedAsync = {
+  pollIntervalMs: 5_000,
+  timeoutMs: 300_000,
+  extractId: (data: unknown) => {
+    const jobId = (data as { jobId?: number | string }).jobId
+    if (jobId === undefined || jobId === null || jobId === '') {
+      throw new Error('Ads response has no jobId')
+    }
+    return String(jobId)
+  },
+  isComplete: (data: unknown) => {
+    const s = (data as { status?: string }).status
+    return s === 'done' || s === 'failed' || s === 'timed_out'
+  },
+}
+
+function _adPlatformAllows(input: Record<string, unknown>, mine: string): boolean {
+  const p = input.platform
+  return p === undefined || p === null || p === '' || p === mine
+}
+
+const searchAdsProviders: ProviderEntry[] = [
+  {
+    id: 'google_ads',
+    endpoint: '/google-ads/search',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => {
+      if (!_adPlatformAllows(input, 'google')) return false
+      return !!input.query || isNonEmptyArray(input.domains) || isNonEmptyArray(input.advertiser_ids)
+    },
+    mapParams: (input) => ({
+      body: {
+        searchTerms: input.query ? [input.query] : undefined,
+        domains: input.domains,
+        advertiserIds: input.advertiser_ids,
+        region: input.country,
+        maxAds: Math.min(Math.max((input.max_results as number | undefined) ?? 25, 1), 1000),
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { ads?: unknown[] }).ads),
+    async: { ..._adsSharedAsync, pollEndpoint: (id) => `/google-ads/search/${id}` },
+  },
+  {
+    id: 'linkedin_ad_library',
+    endpoint: '/linkedin-ad-library/search',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => {
+      if (!_adPlatformAllows(input, 'linkedin')) return false
+      return isNonEmptyArray(input.search_urls)
+    },
+    mapParams: (input) => ({
+      body: {
+        searchUrls: input.search_urls,
+        maxResults: Math.min(Math.max((input.max_results as number | undefined) ?? 25, 1), 200),
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { ads?: unknown[] }).ads),
+    async: { ..._adsSharedAsync, pollEndpoint: (id) => `/linkedin-ad-library/search/${id}` },
+  },
+  {
+    id: 'meta_ads',
+    endpoint: '/meta-ads/search',
+    method: 'POST',
+    priority: 3,
+    isApplicable: (input) => {
+      if (!_adPlatformAllows(input, 'meta')) return false
+      if (isNonEmptyArray(input.domains)) return false
+      if (isNonEmptyArray(input.advertiser_ids)) return false
+      if (isNonEmptyArray(input.search_urls)) return false
+      return !!input.query
+    },
+    mapParams: (input) => ({
+      body: {
+        search: input.query,
+        country: input.country ?? 'US',
+        adType: input.ad_type ?? 'ALL',
+        maxItems: Math.min(Math.max((input.max_results as number | undefined) ?? 20, 1), 200),
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { ads?: unknown[] }).ads),
+    async: { ..._adsSharedAsync, pollEndpoint: (id) => `/meta-ads/search/${id}` },
+  },
+  {
+    id: 'twitter_ads',
+    endpoint: '/twitter-ads-scraper/search',
+    method: 'POST',
+    priority: 4,
+    isApplicable: (input) => {
+      if (!_adPlatformAllows(input, 'twitter')) return false
+      if (isNonEmptyArray(input.domains)) return false
+      if (isNonEmptyArray(input.advertiser_ids)) return false
+      if (isNonEmptyArray(input.search_urls)) return false
+      return !!input.query
+    },
+    mapParams: (input) => ({
+      body: {
+        searchTerms: [input.query],
+        country: input.country,
+        startDate: input.start_date,
+        endDate: input.end_date,
+        maxItems: Math.min(Math.max((input.max_results as number | undefined) ?? 20, 1), 100),
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { ads?: unknown[] }).ads),
+    async: { ..._adsSharedAsync, pollEndpoint: (id) => `/twitter-ads-scraper/search/${id}` },
+  },
+  {
+    id: 'reddit_ads',
+    endpoint: '/reddit-ads/scrape',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) => {
+      if (!_adPlatformAllows(input, 'reddit')) return false
+      if (isNonEmptyArray(input.domains)) return false
+      if (isNonEmptyArray(input.advertiser_ids)) return false
+      if (isNonEmptyArray(input.search_urls)) return false
+      return true
+    },
+    mapParams: (input) => ({
+      body: {
+        keywords: input.query,
+        industry: input.industry,
+        budgetCategory: input.budget_category,
+        postType: input.post_type,
+        objectiveType: input.objective_type,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { ads?: unknown[] }).ads),
+    async: { ..._adsSharedAsync, pollEndpoint: (id) => `/reddit-ads/scrape/${id}` },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_places
+// ---------------------------------------------------------------------------
+
+const _OPENMART_COUNTRIES = ['US', 'CA', 'AU', 'PR', 'NZ'] as const
+
+const _OPENMART_ONLY_KEYS = [
+  'tags', 'state', 'zip_code', 'lat', 'long', 'geo_radius',
+  'min_overall_rating', 'max_overall_rating', 'min_total_reviews', 'max_total_reviews',
+  'ownership_type', 'has_website', 'has_valid_website', 'has_contact_info',
+  'min_price_tier', 'max_price_tier',
+  'include_keywords', 'exclude_keywords', 'exclude_root_domains',
+] as const
+
+const _GOOGLE_MAPS_ONLY_KEYS = [
+  'start_urls', 'include_opening_hours', 'include_additional_info', 'language',
+] as const
+
+function _placeProviderAllows(input: Record<string, unknown>, mine: string): boolean {
+  const p = input.provider
+  return p === undefined || p === null || p === '' || p === mine
+}
+
+function _hasAny(input: Record<string, unknown>, keys: readonly string[]): boolean {
+  for (const k of keys) {
+    const v = input[k]
+    if (v === undefined || v === null) continue
+    if (typeof v === 'string' && v === '') continue
+    if (Array.isArray(v) && v.length === 0) continue
+    return true
+  }
+  return false
+}
+
+const _placesSharedAsync = {
+  pollIntervalMs: 5_000,
+  timeoutMs: 300_000,
+  extractId: (data: unknown) => {
+    const jobId = (data as { jobId?: number | string }).jobId
+    if (jobId === undefined || jobId === null || jobId === '') {
+      throw new Error('Places response has no jobId')
+    }
+    return String(jobId)
+  },
+  isComplete: (data: unknown) => {
+    const s = (data as { status?: string }).status
+    return s === 'done' || s === 'failed' || s === 'timed_out'
+  },
+}
+
+const searchPlacesProviders: ProviderEntry[] = [
+  {
+    id: 'openmart',
+    endpoint: '/openmart/search',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => {
+      if (!_placeProviderAllows(input, 'openmart')) return false
+      if (_hasAny(input, _GOOGLE_MAPS_ONLY_KEYS)) return false
+      const c = input.country
+      if (typeof c === 'string' && c.length > 0
+          && !(_OPENMART_COUNTRIES as readonly string[]).includes(c.toUpperCase())) {
+        return false
+      }
+      return !!input.query
+        || isNonEmptyArray(input.tags)
+        || _hasAny(input, ['city', 'state', 'zip_code', 'lat', 'long'])
+        || _hasAny(input, _OPENMART_ONLY_KEYS)
+    },
+    mapParams: (input) => {
+      const country = typeof input.country === 'string' && input.country.length > 0
+        ? input.country.toUpperCase() : undefined
+      const hasLocationBits = _hasAny(input, ['city', 'state', 'zip_code', 'lat', 'long', 'geo_radius']) || !!country
+      const location = hasLocationBits ? {
+        city: input.city,
+        state: input.state,
+        zip_code: input.zip_code,
+        country,
+        lat: input.lat,
+        long: input.long,
+        geo_radius: input.geo_radius,
+      } : undefined
+      return {
+        body: {
+          query: input.query,
+          tags: input.tags,
+          location,
+          min_overall_rating: input.min_overall_rating,
+          max_overall_rating: input.max_overall_rating,
+          min_total_reviews: input.min_total_reviews,
+          max_total_reviews: input.max_total_reviews,
+          ownership_type: input.ownership_type,
+          has_website: input.has_website,
+          has_valid_website: input.has_valid_website,
+          has_contact_info: input.has_contact_info,
+          min_price_tier: input.min_price_tier,
+          max_price_tier: input.max_price_tier,
+          include_keywords: input.include_keywords,
+          exclude_keywords: input.exclude_keywords,
+          exclude_root_domains: input.exclude_root_domains,
+          limit: Math.min(Math.max((input.limit as number | undefined) ?? 25, 1), 500),
+        },
+      }
+    },
+    hasResult: (data) => {
+      if (Array.isArray(data)) return data.length > 0
+      const inner = (data as { data?: unknown[] }).data
+      return Array.isArray(inner) && inner.length > 0
+    },
+  },
+  {
+    id: 'google_maps',
+    endpoint: '/google-maps/scraper',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => {
+      if (!_placeProviderAllows(input, 'google_maps')) return false
+      return !!input.query
+        || isNonEmptyArray(input.start_urls)
+        || (typeof input.city === 'string' && input.city.length > 0)
+    },
+    mapParams: (input) => {
+      const startUrls = Array.isArray(input.start_urls)
+        ? (input.start_urls as string[]).map((url) => ({ url }))
+        : undefined
+      const country = typeof input.country === 'string' && input.country.length > 0
+        ? input.country.toLowerCase() : undefined
+      return {
+        body: {
+          searchStringsArray: input.query ? [input.query] : undefined,
+          startUrls,
+          maxCrawledPlacesPerSearch: Math.min(Math.max((input.limit as number | undefined) ?? 25, 1), 200),
+          countryCode: country,
+          city: input.city,
+          language: input.language,
+          includeOpeningHours: input.include_opening_hours,
+          additionalInfo: input.include_additional_info,
+        },
+      }
+    },
+    hasResult: (data) => isNonEmptyArray((data as { places?: unknown[] }).places),
+    async: { ..._placesSharedAsync, pollEndpoint: (id) => `/google-maps/scraper/${id}` },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// find_influencers
+// ---------------------------------------------------------------------------
+
+const findInfluencersProviders: ProviderEntry[] = [
+  {
+    id: 'influencers_similar',
+    endpoint: '/influencers-club/discovery/creators/similar',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => !!input.handle,
+    mapParams: (input) => ({
+      body: {
+        handle: input.handle,
+        platform: input.platform,
+        paging: { limit: (input.limit as number) ?? 25, page: (input.page as number) ?? 1 },
+        filters: {
+          location: input.location,
+          gender: input.gender,
+          type: input.type,
+        },
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as { accounts?: unknown[]; creators?: unknown[] }
+      return isNonEmptyArray(d.accounts) || isNonEmptyArray(d.creators)
+    },
+  },
+  {
+    id: 'influencers_discovery',
+    endpoint: '/influencers-club/discovery',
+    method: 'POST',
+    priority: 2,
+    mapParams: (input) => ({
+      body: {
+        platform: input.platform,
+        paging: { limit: (input.limit as number) ?? 25, page: (input.page as number) ?? 1 },
+        sort: input.sort_by
+          ? { sort_by: input.sort_by, sort_order: (input.sort_order as string) ?? 'desc' }
+          : undefined,
+        filters: {
+          ai_search: input.ai_search,
+          location: input.location,
+          gender: input.gender,
+          type: input.type,
+        },
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as { accounts?: unknown[]; creators?: unknown[] }
+      return isNonEmptyArray(d.accounts) || isNonEmptyArray(d.creators)
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_reddit
+// ---------------------------------------------------------------------------
+
+const _redditSharedAsync = {
+  pollIntervalMs: 5_000,
+  timeoutMs: 300_000,
+  extractId: (data: unknown) => {
+    const jobId = (data as { jobId?: number | string }).jobId
+    if (jobId === undefined || jobId === null || jobId === '') {
+      throw new Error('Reddit response has no jobId')
+    }
+    return String(jobId)
+  },
+  isComplete: (data: unknown) => {
+    const s = (data as { status?: string }).status
+    return s === 'done' || s === 'failed' || s === 'timed_out'
+  },
+}
+
+const searchRedditProviders: ProviderEntry[] = [
+  {
+    id: 'reddit',
+    endpoint: '/reddit/scrape',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => isNonEmptyArray(input.start_urls),
+    mapParams: (input) => ({
+      body: {
+        searchQueries: input.query ? [input.query] : undefined,
+        startUrls: (input.start_urls as string[] | undefined)?.map((url) => ({ url })),
+        type: input.type ?? 'posts',
+        sort: input.sort,
+        time: input.time,
+        maxItems: Math.min(Math.max((input.limit as number | undefined) ?? 10, 1), 200),
+        maxCommentsPerPost: input.max_comments_per_post,
+        includeComments: input.include_comments,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as { items?: unknown[] }).items),
+    async: {
+      ..._redditSharedAsync,
+      pollEndpoint: (id) => `/reddit/scrape/${id}`,
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// search_seo
+// ---------------------------------------------------------------------------
+
+// DataForSEO wraps all responses as { tasks: [{ result: [...] }] }.
+// This helper extracts the first result object to simplify hasResult checks.
+function dfsResult(data: unknown): Record<string, unknown> | null {
+  const d = data as { tasks?: Array<{ result?: unknown[] }> }
+  const result = d?.tasks?.[0]?.result
+  if (!Array.isArray(result) || result.length === 0) return null
+  return result[0] as Record<string, unknown>
+}
+
+const searchSeoProviders: ProviderEntry[] = [
+  {
+    id: 'kw_search_volume',
+    endpoint: '/dataforseo/keywords/google-ads/search-volume',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => input.category === 'keywords' && isNonEmptyArray(input.keywords),
+    mapParams: (input) => ({
+      body: {
+        keywords: input.keywords,
+        location_name: input.location,
+        language_code: input.language,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as { tasks?: Array<{ result?: unknown[] }> }
+      return isNonEmptyArray(d?.tasks?.[0]?.result)
+    },
+  },
+  {
+    id: 'kw_trends',
+    endpoint: '/dataforseo/keywords/google-trends/explore',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => input.category === 'keywords' && isNonEmptyArray(input.keywords),
+    mapParams: (input) => ({
+      body: {
+        keywords: input.keywords,
+        location_name: input.location,
+        language_code: input.language,
+        date_from: input.date_from,
+        date_to: input.date_to,
+        time_range: input.time_range,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'serp_google',
+    endpoint: '/dataforseo/serp/google/organic',
+    method: 'POST',
+    priority: 3,
+    isApplicable: (input) =>
+      input.category === 'serp' && !!input.keyword && input.engine !== 'youtube' && input.engine !== 'bing',
+    mapParams: (input) => ({
+      body: {
+        keyword: input.keyword,
+        location_name: (input.location as string | undefined) ?? 'United States',
+        language_code: (input.language as string | undefined) ?? 'en',
+        depth: input.limit,
+        device: input.device,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'serp_bing',
+    endpoint: '/dataforseo/serp/bing/organic',
+    method: 'POST',
+    priority: 4,
+    isApplicable: (input) => input.category === 'serp' && !!input.keyword && input.engine === 'bing',
+    mapParams: (input) => ({
+      body: {
+        keyword: input.keyword,
+        location_name: (input.location as string | undefined) ?? 'United States',
+        language_code: (input.language as string | undefined) ?? 'en',
+        depth: input.limit,
+        device: input.device,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'serp_youtube',
+    endpoint: '/dataforseo/serp/youtube/organic',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) => input.category === 'serp' && !!input.keyword && input.engine === 'youtube',
+    mapParams: (input) => ({
+      body: {
+        keyword: input.keyword,
+        location_name: (input.location as string | undefined) ?? 'United States',
+        language_code: (input.language as string | undefined) ?? 'en',
+        block_depth: input.limit,
+        device: input.device,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'bl_summary',
+    endpoint: '/dataforseo/backlinks/summary',
+    method: 'POST',
+    priority: 6,
+    isApplicable: (input) => input.category === 'backlinks' && !!input.target,
+    mapParams: (input) => ({ body: { target: input.target } }),
+    hasResult: (data) => {
+      const r = dfsResult(data)
+      return !!(r?.total_count) || !!(r?.rank)
+    },
+  },
+  {
+    id: 'bl_backlinks',
+    endpoint: '/dataforseo/backlinks/backlinks',
+    method: 'POST',
+    priority: 7,
+    isApplicable: (input) => input.category === 'backlinks' && !!input.target,
+    mapParams: (input) => ({
+      body: { target: input.target, limit: input.limit, offset: 0 },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'bl_referring',
+    endpoint: '/dataforseo/backlinks/referring-domains',
+    method: 'POST',
+    priority: 8,
+    isApplicable: (input) => input.category === 'backlinks' && !!input.target,
+    mapParams: (input) => ({
+      body: { target: input.target, limit: input.limit, offset: 0 },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'domain_tech',
+    endpoint: '/dataforseo/domain-analytics/technologies',
+    method: 'POST',
+    priority: 9,
+    isApplicable: (input) =>
+      input.category === 'domain' && !!input.target && input.action !== 'whois',
+    mapParams: (input) => ({ body: { target: input.target } }),
+    hasResult: (data) => {
+      const r = dfsResult(data)
+      return !!r && hasAnyKey(r, ['technologies', 'cms', 'analytics', 'widgets'])
+    },
+  },
+  {
+    id: 'domain_whois',
+    endpoint: '/dataforseo/domain-analytics/whois',
+    method: 'POST',
+    priority: 10,
+    isApplicable: (input) =>
+      input.category === 'domain' && !!input.target && input.action === 'whois',
+    mapParams: (input) => ({
+      body: { limit: input.limit, filters: [['domain', '=', input.target]] },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'labs_rank_overview',
+    endpoint: '/dataforseo/labs/domain-rank-overview',
+    method: 'POST',
+    priority: 11,
+    isApplicable: (input) =>
+      input.category === 'labs' && !!input.target &&
+      (!input.lab_action || input.lab_action === 'rank-overview'),
+    mapParams: (input) => ({
+      body: {
+        target: input.target,
+        location_name: input.location,
+        language_code: input.language,
+      },
+    }),
+    hasResult: (data) => {
+      const r = dfsResult(data)
+      return !!r && hasAnyKey(r, ['metrics', 'rank', 'organic', 'spam_score'])
+    },
+  },
+  {
+    id: 'labs_ranked_kw',
+    endpoint: '/dataforseo/labs/ranked-keywords',
+    method: 'POST',
+    priority: 12,
+    isApplicable: (input) =>
+      input.category === 'labs' && !!input.target && input.lab_action === 'ranked-keywords',
+    mapParams: (input) => ({
+      body: {
+        target: input.target,
+        location_name: input.location,
+        language_code: input.language,
+        limit: input.limit,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'labs_competitors',
+    endpoint: '/dataforseo/labs/competitors-domain',
+    method: 'POST',
+    priority: 13,
+    isApplicable: (input) =>
+      input.category === 'labs' && !!input.target && input.lab_action === 'competitors',
+    mapParams: (input) => ({
+      body: {
+        target: input.target,
+        location_name: input.location,
+        language_code: input.language,
+        limit: input.limit,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'labs_kw_ideas',
+    endpoint: '/dataforseo/labs/keyword-ideas',
+    method: 'POST',
+    priority: 14,
+    isApplicable: (input) =>
+      input.category === 'labs' && isNonEmptyArray(input.keywords) && input.lab_action === 'keyword-ideas',
+    mapParams: (input) => ({
+      body: {
+        keywords: input.keywords,
+        location_name: input.location,
+        language_code: input.language,
+        limit: input.limit,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray(dfsResult(data)?.items),
+  },
+  {
+    id: 'page_lighthouse',
+    endpoint: '/dataforseo/on-page/lighthouse',
+    method: 'POST',
+    priority: 15,
+    isApplicable: (input) =>
+      input.category === 'page' && !!input.url && input.page_action !== 'content',
+    mapParams: (input) => ({
+      body: {
+        url: input.url,
+        enable_javascript: input.enable_javascript,
+        full_data: input.full_data,
+      },
+    }),
+    hasResult: (data) => { const r = dfsResult(data); return !!r && hasAnyKey(r, ['categories', 'audits', 'lighthouse']) },
+  },
+  {
+    id: 'page_content',
+    endpoint: '/dataforseo/on-page/content-parsing',
+    method: 'POST',
+    priority: 16,
+    isApplicable: (input) =>
+      input.category === 'page' && !!input.url && input.page_action === 'content',
+    mapParams: (input) => ({
+      body: {
+        url: input.url,
+        enable_javascript: input.enable_javascript,
+      },
+    }),
+    hasResult: (data) => { const r = dfsResult(data); return !!r && hasAnyKey(r, ['content', 'plain_text', 'title']) },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// enrich_person
+// ---------------------------------------------------------------------------
+
+const enrichPersonProviders: ProviderEntry[] = [
+  {
+    id: 'linkupapi-profile-enrich',
+    endpoint: '/linkupapi/data/profil/enrich',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) =>
+      !!input.first_name && !!input.last_name && !!(input.company_name || input.domain),
+    mapParams: (input) => ({
+      body: {
+        first_name: input.first_name,
+        last_name: input.last_name,
+        company_name: input.company_name ?? input.domain,
+      },
+    }),
+    // Both profile-enrich and email-reverse return { status: 'success', data: {...} }
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.status === 'success' && !!d.data
+    },
+  },
+  {
+    id: 'linkupapi-email-reverse',
+    endpoint: '/linkupapi/data/mail/reverse',
+    method: 'POST',
+    priority: 2,
+    isApplicable: (input) => typeof input.email === 'string' && (input.email as string).includes('@'),
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.status === 'success' && !!d.data
+    },
+  },
+  {
+    id: 'pdl-person-enrich',
+    endpoint: '/pdl/person/enrich',
+    method: 'POST',
+    priority: 3,
+    mapParams: (input) => ({
+      body: {
+        email: input.email,
+        profile: input.linkedin_url,
+        phone: input.phone,
+        first_name: input.first_name,
+        last_name: input.last_name,
+        company: input.company_name ?? input.domain,
+      },
+    }),
+    // PDL route translates 404 (no match) into HTTP 200 with status:404 — check inner status
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.status === 200 && d.data !== null && d.data !== undefined
+    },
+  },
+  {
+    id: 'apollo-people-match',
+    endpoint: '/apollo/people/match',
+    method: 'POST',
+    priority: 4,
+    mapParams: (input) => ({
+      body: {
+        first_name: input.first_name,
+        last_name: input.last_name,
+        email: input.email,
+        organization_name: input.company_name,
+        domain: input.domain,
+        linkedin_url: input.linkedin_url,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return !!d.person && typeof d.person === 'object'
+    },
+  },
+  {
+    id: 'blitzapi-reverse-email',
+    endpoint: '/blitzapi/enrichment/reverse-email-lookup',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) => typeof input.email === 'string' && (input.email as string).includes('@'),
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return hasAnyKey(d, ['person', 'profile', 'name', 'first_name', 'linkedin_url'])
+    },
+  },
+  {
+    id: 'findymail-business-profile',
+    endpoint: '/findymail/search/business-profile',
+    method: 'POST',
+    priority: 6,
+    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).includes('linkedin.com'),
+    mapParams: (input) => ({ body: { linkedin_url: input.linkedin_url } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return !d.error && hasAnyKey(d, ['email', 'name', 'first_name', 'linkedin_url'])
+    },
+  },
+  {
+    id: 'findymail-reverse-email',
+    endpoint: '/findymail/search/reverse-email',
+    method: 'POST',
+    priority: 7,
+    isApplicable: (input) => typeof input.email === 'string' && (input.email as string).includes('@'),
+    mapParams: (input) => ({ body: { email: input.email, with_profile: true } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return !d.error && hasAnyKey(d, ['email', 'name', 'first_name', 'linkedin_url'])
+    },
+  },
+  {
+    id: 'icypeas-scrape-profile',
+    endpoint: '/icypeas/scrape/profile',
+    method: 'POST',
+    priority: 8,
+    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).includes('linkedin.com'),
+    // Icypeas expects the field named 'url'
+    mapParams: (input) => ({ body: { url: input.linkedin_url } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.success === true && !!d.profile
+    },
+  },
+  {
+    id: 'icypeas-url-search-profile',
+    endpoint: '/icypeas/url-search/profile',
+    method: 'POST',
+    priority: 9,
+    isApplicable: (input) =>
+      !!input.first_name && !!input.last_name && !!(input.company_name || input.domain),
+    mapParams: (input) => ({
+      body: {
+        firstname: input.first_name,
+        lastname: input.last_name,
+        companyOrDomain: input.company_name ?? input.domain,
+      },
+    }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return typeof d.profileUrl === 'string' && d.profileUrl.includes('linkedin.com')
+    },
+  },
+  {
+    id: 'ai-ark-reverse-lookup',
+    endpoint: '/ai-ark/people/reverse-lookup',
+    method: 'POST',
+    priority: 10,
+    isApplicable: (input) =>
+      (typeof input.email === 'string' && (input.email as string).includes('@')) ||
+      (typeof input.phone === 'string' && (input.phone as string).length > 5),
+    // AI-Ark accepts a single `search` string (email or phone)
+    mapParams: (input) => ({
+      body: { search: (input.email ?? input.phone) as string },
+    }),
+    hasResult: (data) => {
+      return hasAnyKey(data as Record<string, unknown>, ['name', 'first_name', 'email', 'linkedin_url'])
+    },
+  },
+  {
+    id: 'icypeas-reverse-email-lookup',
+    endpoint: '/icypeas/reverse-email-lookup',
+    method: 'POST',
+    priority: 11,
+    isApplicable: (input) => typeof input.email === 'string' && (input.email as string).includes('@'),
+    mapParams: (input) => ({ body: { email: input.email } }),
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return isNonEmptyArray(d.profiles) || (d.success === true && !!d.data)
+    },
+  },
+  {
+    id: 'pdl-person-identify',
+    endpoint: '/pdl/person/identify',
+    method: 'POST',
+    priority: 12,
+    mapParams: (input) => ({
+      body: {
+        email: input.email,
+        profile: input.linkedin_url,
+        phone: input.phone,
+        first_name: input.first_name,
+        last_name: input.last_name,
+        company: input.company_name ?? input.domain,
+      },
+    }),
+    // PDL identify returns { status: 200, matches: [...], total: N }
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      return d.status === 200 && isNonEmptyArray(d.matches)
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// find_signals
+// ---------------------------------------------------------------------------
+
+const findSignalsProviders: ProviderEntry[] = [
+  {
+    id: 'signalbase-funding',
+    endpoint: '/signalbase/funding-signals',
+    method: 'GET',
+    priority: 1,
+    isApplicable: (input) => input.signal_type === 'funding',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.companies)) qp.company_name = (input.companies as string[])[0]
+      if (typeof input.since === 'string') qp.dateFrom = input.since
+      if (isNonEmptyArray(input.industries)) qp.industry = (input.industries as string[]).join(',')
+      if (isNonEmptyArray(input.countries)) qp.countries = (input.countries as string[]).join(',')
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    // Known Signalbase data quality bugs handled here:
+    // Bug 1: company* fields populated with investor data — fixed via slug-derived name.
+    // Bug 2: stale articles (e.g. 2019) stamped with today's date and surfaced as new signals.
+    //        Signalbase copies occurredAt to all sources[].publishedAt so date comparison is
+    //        useless — we extract years embedded in news article URLs instead.
+    // Bug 3: wrong companyCountry (e.g. UK company tagged as FR) — unfixable without geo lookup.
+    postFilter: (data) => {
+      const d = data as Record<string, unknown>
+      const signals = (d.data as Array<Record<string, unknown>> | undefined) ?? []
+
+      d.data = signals
+        .filter((signal) => {
+          // Bug 2: drop signals where any news article URL embeds a year 5+ years before occurredAt.
+          const oy = new Date(signal.occurredAt as string).getFullYear()
+          if (isNaN(oy)) return true
+          const sources = (signal.sources as Array<{ url?: string; sourceType?: string }> | undefined) ?? []
+          const urlYears = sources
+            .filter((s) => s.sourceType === 'news_article')
+            .flatMap((s) => { const m = (s.url ?? '').match(/\/(20\d{2})[\/\-]/); return m ? [parseInt(m[1])] : [] })
+          return urlYears.length === 0 || Math.min(...urlYears) > oy - 5
+        })
+        .map((signal) => {
+          // Bug 1: fix when companyName matches an investor and companySlug points elsewhere.
+          const companyName = signal.companyName as string | undefined
+          const companySlug = signal.companySlug as string | undefined
+          if (!companyName || !companySlug) return signal
+          const slugName = companySlug.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
+          if (slugName.toLowerCase() === companyName.toLowerCase()) return signal
+          const investors = (signal.investors as Array<{ name?: string }> | undefined) ?? []
+          if (!investors.some((inv) => inv.name?.toLowerCase() === companyName.toLowerCase())) return signal
+          return {
+            ...signal,
+            companyName: slugName,
+            companyWebsite: null,
+            companyLinkedin: null,
+            companyLogo: null,
+            companyDescription: null,
+          }
+        })
+
+      return d
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'signalbase-acquisition',
+    endpoint: '/signalbase/acquisition-signals',
+    method: 'GET',
+    priority: 2,
+    isApplicable: (input) => input.signal_type === 'acquisition',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.companies)) qp.company_name = (input.companies as string[])[0]
+      if (typeof input.since === 'string') qp.dateFrom = input.since
+      if (isNonEmptyArray(input.industries)) qp.industry = (input.industries as string[]).join(',')
+      if (isNonEmptyArray(input.countries)) qp.countries = (input.countries as string[]).join(',')
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'signalbase-hiring',
+    endpoint: '/signalbase/hiring-signals',
+    method: 'GET',
+    priority: 3,
+    isApplicable: (input) => input.signal_type === 'hiring',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.companies)) qp.search = (input.companies as string[])[0]
+      if (typeof input.since === 'string') qp.dateFrom = input.since
+      if (isNonEmptyArray(input.countries)) qp.countries = (input.countries as string[]).join(',')
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'signalbase-job-change',
+    endpoint: '/signalbase/job-change-signals',
+    method: 'GET',
+    priority: 4,
+    isApplicable: (input) => input.signal_type === 'job_change',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.companies)) qp.company_name = (input.companies as string[])[0]
+      if (typeof input.since === 'string') qp.dateFrom = input.since
+      if (isNonEmptyArray(input.countries)) qp.countries = (input.countries as string[]).join(',')
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'theirstack-buying-intents',
+    endpoint: '/theirstack/companies/buying_intents',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) =>
+      input.signal_type === 'intent' &&
+      (isNonEmptyArray(input.companies) || isNonEmptyArray(input.domains)),
+    mapParams: (input) => ({
+      body: {
+        ...(isNonEmptyArray(input.companies) && { company_name_or: input.companies }),
+        ...(isNonEmptyArray(input.domains) && { company_domain: (input.domains as string[])[0] }),
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'predictleads-financing',
+    endpoint: '/predictleads/discover/financing_events',
+    method: 'GET',
+    priority: 6,
+    // Fallback for 'funding' — fewer filters than signalbase-funding but broader coverage
+    isApplicable: (input) => input.signal_type === 'funding',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.countries)) qp.company_location = (input.countries as string[])[0]
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'predictleads-news',
+    endpoint: '/predictleads/discover/news_events',
+    method: 'GET',
+    priority: 7,
+    isApplicable: (input) => input.signal_type === 'news',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (isNonEmptyArray(input.countries)) qp.company_location = (input.countries as string[])[0]
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    id: 'predictleads-startup-posts',
+    endpoint: '/predictleads/discover/startup_platform_posts',
+    method: 'GET',
+    priority: 8,
+    isApplicable: (input) => input.signal_type === 'startup_post',
+    mapParams: (input) => {
+      const qp: Record<string, string> = {}
+      if (typeof input.since === 'string') qp.published_at_from = input.since
+      qp.limit = String(Math.min((input.limit as number | undefined) ?? 25, 100))
+      return { queryParams: qp }
+    },
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+]
+
+// ---------------------------------------------------------------------------
+// fetch_page_content
+// ---------------------------------------------------------------------------
+
+const fetchPageContentProviders: ProviderEntry[] = [
+  {
+    id: 'exa-contents',
+    endpoint: '/exa/contents',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => ({
+      body: {
+        urls: input.urls,
+        text: (input.include_text as boolean | undefined) !== false ? true : undefined,
+        summary: (input.include_summary as boolean | undefined) === true ? {} : undefined,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).results),
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const registry: Record<Capability, ProviderEntry[]> = {
+  search_companies: searchCompaniesProviders,
+  find_people: findPeopleProviders,
+  find_email: findEmailProviders,
+  verify_email: verifyEmailProviders,
+  find_phone: findPhoneProviders,
+  enrich_company: enrichCompanyProviders,
+  enrich_person: enrichPersonProviders,
+  search_web: searchWebProviders,
+  search_jobs: searchJobsProviders,
+  search_ads: searchAdsProviders,
+  search_places: searchPlacesProviders,
+  find_influencers: findInfluencersProviders,
+  search_reddit: searchRedditProviders,
+  search_seo: searchSeoProviders,
+  find_signals: findSignalsProviders,
+  fetch_page_content: fetchPageContentProviders,
+}
+
+/**
+ * Get the ordered provider list for a capability.
+ * Returns a copy sorted by priority (lower = first).
+ */
+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)
+}
+
+/**
+ * Get providers for search_web, reordering for neural search preference.
+ */
+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
+    })
+  }
+  return providers
+}