@coldiq/mcp 0.1.8 → 0.1.10

package/src/utils/fuzzy.ts

@@ -0,0 +1,57 @@
+export function normalize(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  )
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    }
+  }
+  return dp[m][n]
+}
+
+export type MatchVia = 'exact' | 'normalized' | 'fuzzy'
+
+export interface FuzzyMatchResult {
+  matched: string
+  via: MatchVia
+}
+
+/**
+ * Match a user-supplied string against a list of candidate IDs.
+ * Precedence: exact → normalized (case + punctuation stripped) → Levenshtein ≤ threshold.
+ * Threshold = min(2, floor(len/3)) where len = normalized candidate length.
+ */
+export function fuzzyMatch(input: string, candidates: string[]): FuzzyMatchResult | null {
+  // Exact
+  if (candidates.includes(input)) return { matched: input, via: 'exact' }
+
+  const normInput = normalize(input)
+
+  // Normalized exact
+  for (const c of candidates) {
+    if (normalize(c) === normInput) return { matched: c, via: 'normalized' }
+  }
+
+  // Levenshtein
+  let best: { matched: string; dist: number } | null = null
+  for (const c of candidates) {
+    const normC = normalize(c)
+    const threshold = Math.min(2, Math.floor(normC.length / 3))
+    if (threshold === 0) continue
+    const dist = levenshtein(normInput, normC)
+    if (dist <= threshold && (best === null || dist < best.dist)) {
+      best = { matched: c, dist }
+    }
+  }
+
+  return best ? { matched: best.matched, via: 'fuzzy' } : null
+}

package/src/utils/provider-resolver.ts

@@ -0,0 +1,306 @@
+import { listCapabilityProviderIds, getProviderApplicabilityGuard } from '../registry.js'
+import type { Capability } from '../registry.js'
+import { fuzzyMatch } from './fuzzy.js'
+
+// find_emails uses a custom waterfall — its providers are not in the registry.
+// Exported so find-emails.ts stays in sync without a second hardcoded list.
+export const FIND_EMAILS_PROVIDERS = ['prospeo', 'fullenrich', 'findymail', 'icypeas']
+
+export function getProvidersForCapability(capability: Capability | 'find_emails'): string[] {
+  if (capability === 'find_emails') return FIND_EMAILS_PROVIDERS
+  return listCapabilityProviderIds(capability as Capability)
+}
+
+// ---------------------------------------------------------------------------
+// User-facing error payloads
+// ---------------------------------------------------------------------------
+
+export interface ToolErrorPayload {
+  error: string
+  available_providers: string[]
+}
+
+const TRUST_LINE =
+  'Or just run the tool without specifying providers — ColdIQ will automatically pick the best tool for your needs.'
+
+export function buildUnrecognizedError(
+  input: string,
+  capability: Capability | 'find_emails',
+  available: string[],
+): ToolErrorPayload {
+  return {
+    error: `'${input}' is not a recognized provider for this tool. Available providers: ${available.join(', ')}. ${TRUST_LINE}`,
+    available_providers: available,
+  }
+}
+
+export function buildGatedError(
+  provider: string,
+  gate: GateDesc,
+  capability: Capability | 'find_emails',
+  available: string[],
+  input: Record<string, unknown>,
+): ToolErrorPayload {
+  const others = available.filter((p) => {
+    if (p === provider) return false
+    const guard = getProviderApplicabilityGuard(capability as Capability, p)
+    try {
+      return !guard || guard(input)
+    } catch {
+      return false
+    }
+  })
+  const othersText = others.length > 0
+    ? `Other providers that work with your inputs: ${others.join(', ')}. `
+    : ''
+  const clause = gate.kind === 'incompatible_with'
+    ? `is not compatible with ${gate.fields}`
+    : `requires ${gate.fields}, which wasn't provided`
+  return {
+    error: `'${provider}' ${clause}. ${othersText}${TRUST_LINE}`,
+    available_providers: others,
+  }
+}
+
+export function buildAllFailedError(
+  tried: string[],
+  capability: Capability | 'find_emails',
+  available: string[],
+): ToolErrorPayload {
+  const remaining = available.filter((p) => !tried.includes(p))
+  const remainingText = remaining.length > 0
+    ? `You can retry with one of these instead: ${remaining.join(', ')}. `
+    : ''
+  return {
+    error: `Couldn't fulfill your request with the providers you specified (${tried.join(', ')}). ${remainingText}${TRUST_LINE}`,
+    available_providers: remaining,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+export interface ResolveOk {
+  ok: true
+  providers: string[]
+  matchedFrom?: Record<string, string>
+}
+
+export interface ResolveError {
+  ok: false
+  error: ToolErrorPayload
+}
+
+export type ResolveResult = ResolveOk | ResolveError
+
+/**
+ * Resolve `use_providers` field against the capability's known provider IDs.
+ * - Empty/absent → auto-route (ok: true, providers: [])
+ * - Unknown name → unrecognized error
+ * - isApplicable fails → gated error
+ * - Otherwise → resolved IDs in user order
+ */
+export function resolvePreferredProviders(
+  capability: Capability | 'find_emails',
+  input: Record<string, unknown>,
+  useProviders: unknown,
+): ResolveResult {
+  if (!Array.isArray(useProviders) || useProviders.length === 0) {
+    return { ok: true, providers: [] }
+  }
+
+  const available = getProvidersForCapability(capability)
+  const resolved: string[] = []
+  const matchedFrom: Record<string, string> = {}
+
+  for (const raw of useProviders) {
+    const userInput = typeof raw === 'string' ? raw.trim() : String(raw)
+    const match = fuzzyMatch(userInput, available)
+    if (!match) {
+      return { ok: false, error: buildUnrecognizedError(userInput, capability, available) }
+    }
+    if (match.via !== 'exact') {
+      matchedFrom[userInput] = match.matched
+    }
+    if (!resolved.includes(match.matched)) {
+      resolved.push(match.matched)
+    }
+  }
+
+  // Check isApplicable for each resolved provider (registry-based capabilities only)
+  if (capability !== 'find_emails') {
+    for (const id of resolved) {
+      const guard = getProviderApplicabilityGuard(capability as Capability, id)
+      if (guard) {
+        let applicable: boolean
+        try {
+          applicable = guard(input)
+        } catch {
+          applicable = false
+        }
+        if (!applicable) {
+          const gate = getGateDescription(capability as Capability, id)
+          return {
+            ok: false,
+            error: buildGatedError(id, gate, capability, available, input),
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    providers: resolved,
+    ...(Object.keys(matchedFrom).length > 0 ? { matchedFrom } : {}),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gate descriptions — used to produce accurate user-facing messages.
+//
+// Two kinds:
+//   requires       → provider needs a field that the input does NOT have
+//   incompatible_with → provider is excluded BECAUSE a field IS present
+//
+// The distinction matters: "requires X" tells the user to ADD something;
+// "not compatible with X" tells the user to REMOVE something.
+// ---------------------------------------------------------------------------
+
+interface GateDesc {
+  kind: 'requires' | 'incompatible_with'
+  fields: string
+}
+
+const GENERIC_REQUIRES: GateDesc = { kind: 'requires', fields: 'specific input fields' }
+
+const GATED_DESCRIPTIONS: Partial<Record<Capability, Partial<Record<string, GateDesc>>>> = {
+  // -------------------------------------------------------------------------
+  search_companies: {
+    theirstack:              { kind: 'requires',         fields: 'technologies, industries, or funding stage filters' },
+    signalbase:              { kind: 'incompatible_with', fields: 'technology, funding, revenue, or hiring signal filters' },
+    blitzapi:                { kind: 'incompatible_with', fields: 'advanced filters (tech stack, funding, revenue, exclusion lists, or workforce growth)' },
+    apollo:                  { kind: 'incompatible_with', fields: 'year, tech stack, funding, revenue, exclusion, or workforce growth filters' },
+    predictleads:            { kind: 'requires',         fields: 'both a location filter and an employee size filter' },
+    sumble:                  { kind: 'requires',         fields: 'keywords, industries, or technologies' },
+    'limadata-prospect-filter': { kind: 'requires',      fields: 'specific employee count range filters (min_employees / max_employees)' },
+    'limadata-prospect-url': { kind: 'requires',         fields: 'linkedin_search_url' },
+    'linkupapi-fundraising': { kind: 'requires',         fields: 'funding filters and keywords or industries' },
+    'linkupapi-hiring':      { kind: 'requires',         fields: 'is_hiring: true' },
+    'prospeo-search-company': { kind: 'requires',        fields: 'keywords, industries, or countries' },
+    'ai-ark-companies':      { kind: 'requires',         fields: 'keywords, industries, or countries' },
+  },
+  // -------------------------------------------------------------------------
+  find_people: {
+    'linkupapi-search-profiles': { kind: 'incompatible_with', fields: 'company_linkedin_urls or company_domains (this provider only works without company filters)' },
+    'sumble-people-find':    { kind: 'requires',         fields: 'company_domains or company_linkedin_urls, and job_titles or seniorities' },
+    'prospeo-search-person': { kind: 'requires',         fields: 'job_titles or company_domains' },
+    'ai-ark-people':         { kind: 'requires',         fields: 'job_titles, seniorities, or keywords' },
+    'findymail-search-employees': { kind: 'requires',    fields: 'company_domains and job_titles' },
+  },
+  // -------------------------------------------------------------------------
+  find_email: {
+    findymail:                   { kind: 'requires',    fields: 'first_name and (domain or company_name)' },
+    'limadata-work-email':       { kind: 'requires',    fields: 'first_name, last_name, and domain' },
+    blitzapi:                    { kind: 'requires',    fields: 'linkedin_url' },
+    'limadata-work-email-linkedin': { kind: 'requires', fields: 'linkedin_url' },
+  },
+  // -------------------------------------------------------------------------
+  verify_email: {},
+  // -------------------------------------------------------------------------
+  find_phone: {
+    findymail: { kind: 'requires', fields: 'linkedin_url' },
+    limadata:  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
+    'ai-ark':  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
+  },
+  // -------------------------------------------------------------------------
+  enrich_company: {
+    companyenrich:        { kind: 'requires', fields: 'domain' },
+    apollo:               { kind: 'requires', fields: 'domain' },
+    limadata:             { kind: 'requires', fields: 'domain or linkedin_url' },
+    wiza:                 { kind: 'requires', fields: 'domain or name' },
+    companyenrich_props:  { kind: 'requires', fields: 'name or linkedin_url' },
+    blitzapi:             { kind: 'requires', fields: 'linkedin_url' },
+    icypeas:              { kind: 'requires', fields: 'linkedin_url' },
+    builtwith:            { kind: 'requires', fields: 'domain' },
+    openmart:             { kind: 'requires', fields: 'domain' },
+    'linkupapi-by-domain': { kind: 'requires', fields: 'domain' },
+    'linkupapi-by-url':   { kind: 'requires', fields: 'linkedin_url' },
+  },
+  // -------------------------------------------------------------------------
+  enrich_person: {
+    'linkupapi-profile-enrich':   { kind: 'requires', fields: 'first_name, last_name, and (company_name or domain)' },
+    'linkupapi-email-reverse':    { kind: 'requires', fields: 'email' },
+    'blitzapi-reverse-email':     { kind: 'requires', fields: 'email' },
+    'findymail-business-profile': { kind: 'requires', fields: 'linkedin_url (must be a linkedin.com URL)' },
+    'findymail-reverse-email':    { kind: 'requires', fields: 'email' },
+    'icypeas-scrape-profile':     { kind: 'requires', fields: 'linkedin_url (must be a linkedin.com URL)' },
+    'icypeas-url-search-profile': { kind: 'requires', fields: 'first_name, last_name, and (company_name or domain)' },
+    'ai-ark-reverse-lookup':      { kind: 'requires', fields: 'email or phone' },
+    'icypeas-reverse-email-lookup': { kind: 'requires', fields: 'email' },
+  },
+  // -------------------------------------------------------------------------
+  search_web: {},
+  // -------------------------------------------------------------------------
+  search_jobs: {
+    career_site_jobs:   { kind: 'incompatible_with', fields: 'LinkedIn-only filters (seniority_levels, industries, organization_slugs, min/max_employees, easy_apply_only, exclude_easy_apply)' },
+    linkedin_jobs_api:  { kind: 'incompatible_with', fields: 'Career Site-only filters (ats_slugs, company_domains)' },
+    'theirstack-jobs':  { kind: 'requires',          fields: 'specific job filter conditions' },
+  },
+  // -------------------------------------------------------------------------
+  search_ads: {
+    google_ads:          { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input); use query, domains, or advertiser_ids instead' },
+    linkedin_ad_library: { kind: 'requires',          fields: 'search_urls (pre-built LinkedIn Ad Library URLs)' },
+    meta_ads:            { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+    twitter_ads:         { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+    reddit_ads:          { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+  },
+  // -------------------------------------------------------------------------
+  search_places: {
+    openmart:     { kind: 'requires',         fields: 'country in [US, CA, AU, PR, NZ] or structured Openmart filters' },
+    google_maps:  { kind: 'requires',         fields: 'a query or start_urls' },
+  },
+  // -------------------------------------------------------------------------
+  find_influencers: {
+    influencers_similar: { kind: 'requires', fields: 'handle (a creator handle for lookalike search)' },
+  },
+  // -------------------------------------------------------------------------
+  search_reddit: {},
+  // -------------------------------------------------------------------------
+  search_seo: {
+    kw_search_volume: { kind: 'requires', fields: 'category: "keywords"' },
+    kw_trends:        { kind: 'requires', fields: 'category: "keywords"' },
+    serp_google:      { kind: 'requires', fields: 'category: "serp" and engine: "google"' },
+    serp_bing:        { kind: 'requires', fields: 'category: "serp" and engine: "bing"' },
+    serp_youtube:     { kind: 'requires', fields: 'category: "serp" and engine: "youtube"' },
+    bl_summary:       { kind: 'requires', fields: 'category: "backlinks"' },
+    bl_backlinks:     { kind: 'requires', fields: 'category: "backlinks"' },
+    bl_referring:     { kind: 'requires', fields: 'category: "backlinks"' },
+    domain_tech:      { kind: 'requires', fields: 'category: "domain" and action: "technologies"' },
+    domain_whois:     { kind: 'requires', fields: 'category: "domain" and action: "whois"' },
+    labs_rank_overview: { kind: 'requires', fields: 'category: "labs" and target' },
+    labs_ranked_kw:   { kind: 'requires', fields: 'category: "labs" and target' },
+    labs_competitors: { kind: 'requires', fields: 'category: "labs" and target' },
+    labs_kw_ideas:    { kind: 'requires', fields: 'category: "labs" and keywords[]' },
+    page_lighthouse:  { kind: 'requires', fields: 'category: "page", url, and page_action: "lighthouse"' },
+    page_content:     { kind: 'requires', fields: 'category: "page", url, and page_action: "content"' },
+  },
+  // -------------------------------------------------------------------------
+  find_signals: {
+    'signalbase-funding':        { kind: 'requires', fields: 'signal_type: "funding"' },
+    'signalbase-acquisition':    { kind: 'requires', fields: 'signal_type: "acquisition"' },
+    'signalbase-hiring':         { kind: 'requires', fields: 'signal_type: "hiring"' },
+    'signalbase-job-change':     { kind: 'requires', fields: 'signal_type: "job_change"' },
+    'theirstack-buying-intents': { kind: 'requires', fields: 'signal_type: "intent" and at least one of companies or domains' },
+    'predictleads-financing':    { kind: 'requires', fields: 'signal_type: "funding"' },
+    'predictleads-news':         { kind: 'requires', fields: 'signal_type: "news"' },
+    'predictleads-startup-posts': { kind: 'requires', fields: 'signal_type: "startup_post"' },
+  },
+  // -------------------------------------------------------------------------
+  fetch_page_content: {},
+}
+
+function getGateDescription(capability: Capability, providerId: string): GateDesc {
+  return GATED_DESCRIPTIONS[capability]?.[providerId] ?? GENERIC_REQUIRES
+}

package/tests/executor.test.ts

@@ -324,17 +324,19 @@ describe('executor — 402 propagation', () => {
     vi.restoreAllMocks()
   })
 
-  it('surfaces billingUrl + insufficientCredits when every provider returns 402', async () => {
+  it('surfaces billingUrl + insufficientCredits when every provider returns 402 (balance > 0)', async () => {
+    // User has some credits but every provider's cost exceeds it — waterfall
+    // tries each, all return 402, no early bail (balance > 0).
     stubProviders([
       makeProvider({ id: 'p1', hasResult: () => false }),
       makeProvider({ id: 'p2', hasResult: () => false }),
     ])
 
     const body = {
-      error: "You don't have enough credits to run this request — it costs 5 credits and your balance is 0. Top up your account at https://coldiq.com/marketplace/billing to continue.",
+      error: "You don't have enough credits to run this request — it costs 50 credits and your balance is 2. Top up your account at https://coldiq.com/marketplace/billing to continue.",
       billingUrl: 'https://coldiq.com/marketplace/billing',
-      needed: 5,
-      balance: 0,
+      needed: 50,
+      balance: 2,
     }
     globalThis.fetch = vi.fn(async () =>
       new Response(JSON.stringify(body), { status: 402 })
@@ -381,6 +383,72 @@ describe('executor — 402 propagation', () => {
     }
   })
 
+  it('short-circuits the waterfall when first 402 reports balance: 0', async () => {
+    stubProviders([
+      makeProvider({ id: 'p1', hasResult: () => false }),
+      makeProvider({ id: 'p2', hasResult: () => false }),
+      makeProvider({ id: 'p3', hasResult: () => false }),
+    ])
+
+    const fetchMock = vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          error: 'no credits',
+          billingUrl: 'https://coldiq.com/marketplace/billing',
+          needed: 1,
+          balance: 0,
+        }),
+        { status: 402 }
+      )
+    ) as typeof fetch
+    globalThis.fetch = fetchMock
+
+    const result = await executeWithFallback('search_companies', { keywords: ['SaaS'] })
+
+    // Only the first provider was tried — p2 and p3 were skipped
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      expect(result.insufficientCredits).toBe(true)
+      expect(result.billingUrl).toBe('https://coldiq.com/marketplace/billing')
+      expect(result.providers_tried).toHaveLength(1)
+      expect(result.error).toContain('balance is 0')
+    }
+  })
+
+  it('does NOT short-circuit when first 402 reports a non-zero balance', async () => {
+    stubProviders([
+      makeProvider({ id: 'p1', hasResult: () => false }),
+      makeProvider({ id: 'p2', hasResult: () => false }),
+    ])
+
+    let call = 0
+    const fetchMock = vi.fn(async () => {
+      call++
+      // p1 returns 402 (cost too high) but balance > 0 → keep trying
+      if (call === 1) {
+        return new Response(
+          JSON.stringify({
+            error: 'cost too high',
+            billingUrl: 'https://coldiq.com/marketplace/billing',
+            needed: 5,
+            balance: 2,
+          }),
+          { status: 402 }
+        )
+      }
+      // p2 succeeds with the user's 2 remaining credits
+      return new Response(JSON.stringify({ ok: true, data: ['result'] }), { status: 200 })
+    }) as typeof fetch
+    globalThis.fetch = fetchMock
+
+    await executeWithFallback('search_companies', { keywords: ['SaaS'] })
+
+    // Both providers were tried — non-zero balance means a cheaper provider might fit
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
   it('preserves the full 402 message in providers_tried (not truncated mid-URL)', async () => {
     stubProviders([makeProvider({ id: 'p1', hasResult: () => false })])
 
@@ -475,5 +543,117 @@ describe('executor async polling intervals', () => {
 
 })
 
+// ---------------------------------------------------------------------------
+// options.providers — pinned provider routing
+// ---------------------------------------------------------------------------
+
+describe('executeWithFallback with options.providers', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key-123')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('only calls the pinned provider, skips others', async () => {
+    const callOrder: string[] = []
+    stubProviders([
+      makeProvider({ id: 'first', priority: 1, hasResult: () => false }),
+      makeProvider({ id: 'second', priority: 2, hasResult: () => true }),
+      makeProvider({ id: 'third', priority: 3, hasResult: () => false }),
+    ])
+
+    globalThis.fetch = vi.fn(async (url: unknown) => {
+      const path = (url as string).replace('http://test-api.local', '')
+      callOrder.push(path)
+      return new Response(JSON.stringify({ ok: true }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await executeWithFallback('enrich_company', { domain: 'coldiq.com' }, { providers: ['second'] })
+
+    expect(callOrder).toHaveLength(1)
+    expect('data' in result).toBe(true)
+    if ('data' in result) expect(result._meta.provider).toBe('second')
+  })
+
+  it('respects user-specified order when multiple providers given', async () => {
+    let callCount = 0
+    stubProviders([
+      makeProvider({ id: 'alpha', priority: 1, hasResult: () => false }),
+      makeProvider({ id: 'beta', priority: 2, hasResult: (d) => callCount >= 2 && (d as Record<string, unknown>).ok === true }),
+    ])
+
+    globalThis.fetch = vi.fn(async () => {
+      callCount++
+      return new Response(JSON.stringify({ ok: true }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await executeWithFallback('enrich_company', { domain: 'coldiq.com' }, { providers: ['alpha', 'beta'] })
+
+    expect(callCount).toBe(2)
+    expect('data' in result).toBe(true)
+    if ('data' in result) expect(result._meta.provider).toBe('beta')
+  })
+
+  it('on total failure with pinned providers, returns non-anonymized provider IDs', async () => {
+    stubProviders([
+      makeProvider({ id: 'specific-provider', priority: 1, hasResult: () => false }),
+    ])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ error: 'down' }), { status: 500 })
+    ) as typeof fetch
+
+    const result = await executeWithFallback('enrich_company', { domain: 'coldiq.com' }, { providers: ['specific-provider'] })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      expect(result.providers_tried[0].provider).toBe('specific-provider')
+    }
+  })
+
+  it('on total failure without pinned providers, still anonymizes provider IDs', async () => {
+    stubProviders([
+      makeProvider({ id: 'secret-provider', priority: 1, hasResult: () => false }),
+    ])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ error: 'down' }), { status: 500 })
+    ) as typeof fetch
+
+    const result = await executeWithFallback('enrich_company', { domain: 'coldiq.com' })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      expect(result.providers_tried[0].provider).toBe('provider_1')
+    }
+  })
+
+  it('surfaces matchedFrom in success _meta when provided', async () => {
+    stubProviders([
+      makeProvider({ id: 'prospeo', priority: 1, hasResult: () => true }),
+    ])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await executeWithFallback(
+      'enrich_company',
+      { domain: 'coldiq.com' },
+      { providers: ['prospeo'], matchedFrom: { prospec: 'prospeo' } },
+    )
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.matchedFrom).toEqual({ prospec: 'prospeo' })
+    }
+  })
+})
+
 // Note: the LeadsFactory backoff *schedule* itself is asserted against the live
 // provider entry in tests/registry.test.ts to avoid drift between test and source.

package/tests/registry.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { getProviders, getSearchWebProviders, isoCountryToName } from '../src/registry.js'
+import { getProviders, getSearchWebProviders, isoCountryToName, listCapabilityProviderIds } from '../src/registry.js'
 import type { Capability } from '../src/registry.js'
 
 const ALL_CAPABILITIES: Capability[] = [
@@ -2149,3 +2149,24 @@ describe('registry', () => {
     })
   })
 })
+
+describe('listCapabilityProviderIds', () => {
+  it('returns at least one provider ID for every capability', () => {
+    const caps: 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',
+    ]
+    for (const cap of caps) {
+      const ids = listCapabilityProviderIds(cap)
+      expect(ids.length, `${cap} should have at least 1 provider`).toBeGreaterThan(0)
+    }
+  })
+
+  it('returns string IDs that match getProviders output order', () => {
+    const ids = listCapabilityProviderIds('find_email')
+    const providers = getProviders('find_email')
+    expect(ids).toEqual(providers.map((p) => p.id))
+  })
+})

package/tests/tools/find-email.test.ts

@@ -91,4 +91,47 @@ describe('find_email handler (waterfall)', () => {
     // No linkedin_url → blitzapi and limadata-work-email-linkedin are skipped via isApplicable
     expect(parsed.providers_tried.length).toBe(6) // findymail, icypeas, limadata-work-email, prospeo, fullenrich, linkupapi
   })
+
+  describe('use_providers', () => {
+    it('Scenario A — pinned provider succeeds', async () => {
+      globalThis.fetch = vi.fn(async () =>
+        new Response(JSON.stringify({ email: 'michel@coldiq.com' }), { status: 200 })
+      ) as typeof fetch
+
+      const result = await findEmailHandler({
+        first_name: 'Michel',
+        domain: 'coldiq.com',
+        use_providers: ['findymail'],
+      })
+
+      expect(result.isError).toBeUndefined()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('findymail')
+    })
+
+    it('Scenario C — gated provider without required input returns helpful error', async () => {
+      const result = await findEmailHandler({
+        first_name: 'Michel',
+        domain: 'coldiq.com',
+        use_providers: ['blitzapi'],
+      })
+
+      expect(result.isError).toBe(true)
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed.error).toContain("'blitzapi' requires")
+      expect(parsed.error).toContain('ColdIQ will automatically pick the best tool')
+    })
+
+    it('Scenario E — unrecognized provider returns isError', async () => {
+      const result = await findEmailHandler({
+        first_name: 'Michel',
+        domain: 'coldiq.com',
+        use_providers: ['apollo'],
+      })
+
+      expect(result.isError).toBe(true)
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed.error).toContain("'apollo' is not a recognized provider")
+    })
+  })
 })