@coldiq/mcp 0.1.8 → 0.1.10

package/src/tools/find-emails.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { callApi } from '../client.js'
+import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS } from '../utils/provider-resolver.js'
 
 export const findEmailsName = 'find_emails'
 
@@ -10,7 +11,8 @@ export const findEmailsDescription =
   'Much faster than calling find_email one-by-one. Max 50 people per call. ' +
   'Each person needs a unique id to match results back. ' +
   'Always pass first_name, last_name, and domain — they are the primary enrichment signal. ' +
-  'Also pass linkedin_url when available, but never rely on it alone as some providers cannot resolve vanity URLs.'
+  'Also pass linkedin_url when available, but never rely on it alone as some providers cannot resolve vanity URLs. ' +
+  'ColdIQ automatically picks the best waterfall — pass use_providers only if you need specific tools.'
 
 export const findEmailsSchema = {
   people: z
@@ -26,6 +28,7 @@ export const findEmailsSchema = {
     .min(1)
     .max(50)
     .describe('People to find emails for (max 50)'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically run the best waterfall — recommended for most use cases. Available providers: ${FIND_EMAILS_PROVIDERS.join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 interface PersonInput {
@@ -100,7 +103,10 @@ async function fullEnrichStep(misses: PersonInput[], results: EmailResult[]): Pr
   }
 }
 
-async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[]): Promise<void> {
+async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[], allowedProviders?: string[]): Promise<void> {
+  const useFindymail = !allowedProviders || allowedProviders.includes('findymail')
+  const useIcypeas = !allowedProviders || allowedProviders.includes('icypeas')
+
   await Promise.all(
     misses.map(async (person) => {
       const hit = results.find((r) => r.id === person.id)
@@ -109,22 +115,24 @@ async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[
       // Skip if the parallel FullEnrich branch already filled this person.
       if (hit.email) return
 
-      const fullName = [person.first_name, person.last_name].filter(Boolean).join(' ')
-
-      const fmRes = await callApi('POST', '/findymail/search/name', {
-        name: fullName,
-        domain: person.domain,
-      })
-      if (!hit.email && fmRes.ok) {
-        const d = fmRes.data as Record<string, unknown>
-        if (typeof d.email === 'string' && d.email.includes('@')) {
-          hit.email = d.email
-          hit.provider = 'findymail'
-          return
+      if (useFindymail) {
+        const fullName = [person.first_name, person.last_name].filter(Boolean).join(' ')
+
+        const fmRes = await callApi('POST', '/findymail/search/name', {
+          name: fullName,
+          domain: person.domain,
+        })
+        if (!hit.email && fmRes.ok) {
+          const d = fmRes.data as Record<string, unknown>
+          if (typeof d.email === 'string' && d.email.includes('@')) {
+            hit.email = d.email
+            hit.provider = 'findymail'
+            return
+          }
         }
       }
 
-      if (hit.email) return
+      if (hit.email || !useIcypeas) return
 
       const icyRes = await callApi('POST', '/icypeas/email-search', {
         firstname: person.first_name,
@@ -149,40 +157,52 @@ async function findymailIcypeasStep(misses: PersonInput[], results: EmailResult[
 }
 
 export async function findEmailsHandler(input: Record<string, unknown>) {
-  const people = input.people as PersonInput[]
-  const results: EmailResult[] = people.map((p) => ({ id: p.id, email: null, provider: null }))
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const people = restInput.people as PersonInput[]
 
-  // Step 1: Prospeo bulk — 1 call for all people
-  const bulkBody = {
-    data: people.map((p) =>
-      p.linkedin_url
-        ? { identifier: p.id, linkedin_url: p.linkedin_url }
-        : { identifier: p.id, first_name: p.first_name, last_name: p.last_name, company_name: p.domain },
-    ),
+  const resolved = resolvePreferredProviders('find_emails', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
   }
 
-  const bulkRes = await callApi('POST', '/prospeo/bulk-enrich-person', bulkBody)
+  const allowedProviders = resolved.providers
+  const isConstrained = allowedProviders.length > 0
+
+  const results: EmailResult[] = people.map((p) => ({ id: p.id, email: null, provider: null }))
 
-  if (bulkRes.ok) {
-    const data = bulkRes.data as {
-      results?: Array<{
-        identifier: string
-        person?: { email?: { email?: string } }
-      }>
+  // Step 1: Prospeo bulk — 1 call for all people
+  if (!isConstrained || allowedProviders.includes('prospeo')) {
+    const bulkBody = {
+      data: people.map((p) =>
+        p.linkedin_url
+          ? { identifier: p.id, linkedin_url: p.linkedin_url }
+          : { identifier: p.id, first_name: p.first_name, last_name: p.last_name, company_name: p.domain },
+      ),
     }
-    for (const item of data.results ?? []) {
-      const email = item.person?.email?.email
-      if (typeof email === 'string' && email.includes('@')) {
-        const hit = results.find((r) => r.id === item.identifier)
-        if (hit) {
-          hit.email = email
-          hit.provider = 'prospeo'
+
+    const bulkRes = await callApi('POST', '/prospeo/bulk-enrich-person', bulkBody)
+
+    if (bulkRes.ok) {
+      const data = bulkRes.data as {
+        results?: Array<{
+          identifier: string
+          person?: { email?: { email?: string } }
+        }>
+      }
+      for (const item of data.results ?? []) {
+        const email = item.person?.email?.email
+        if (typeof email === 'string' && email.includes('@')) {
+          const hit = results.find((r) => r.id === item.identifier)
+          if (hit) {
+            hit.email = email
+            hit.provider = 'prospeo'
+          }
         }
       }
     }
   }
 
-  // Steps 2 & 3 run concurrently for Prospeo misses.
+  // Steps 2 & 3 run concurrently for misses.
   //   Step 2: FullEnrich bulk async (slow tail, better European coverage)
   //   Step 3: per-person FindyMail → IcyPeas waterfall
   // Both branches write to the shared `results` array; every write site checks
@@ -191,15 +211,32 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
   const misses = missesOf(people, results)
 
   if (misses.length > 0) {
-    await Promise.all([fullEnrichStep(misses, results), findymailIcypeasStep(misses, results)])
+    const steps: Promise<void>[] = []
+    if (!isConstrained || allowedProviders.includes('fullenrich')) {
+      steps.push(fullEnrichStep(misses, results))
+    }
+    if (!isConstrained || allowedProviders.includes('findymail') || allowedProviders.includes('icypeas')) {
+      steps.push(findymailIcypeasStep(misses, results, isConstrained ? allowedProviders : undefined))
+    }
+    if (steps.length > 0) await Promise.all(steps)
   }
 
   const found = results.filter((r) => r.email !== null).length
+
+  if (isConstrained && found === 0) {
+    const err = buildAllFailedError(allowedProviders, 'find_emails', FIND_EMAILS_PROVIDERS)
+    return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
+  }
+
+  const meta = resolved.matchedFrom && Object.keys(resolved.matchedFrom).length > 0
+    ? { matchedFrom: resolved.matchedFrom }
+    : undefined
+
   return {
     content: [
       {
         type: 'text' as const,
-        text: JSON.stringify({ data: { results, found, total: people.length } }, null, 2),
+        text: JSON.stringify({ data: { results, found, total: people.length }, ...(meta ? { _meta: meta } : {}) }, null, 2),
       },
     ],
   }

package/src/tools/find-influencers.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findInfluencersName = 'find_influencers'
 
@@ -23,10 +24,16 @@ export const findInfluencersSchema = {
   type: z.enum(['creator', 'business']).optional(),
   handle: z.string().optional()
     .describe('Find creators similar to this handle. Routes to lookalike search. No @ prefix.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_influencers').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function findInfluencersHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('find_influencers', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('find_influencers', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('find_influencers', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/find-people.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
 import { callApi } from '../client.js'
 import { getProviders } from '../registry.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findPeopleName = 'find_people'
 
@@ -24,10 +25,16 @@ export const findPeopleSchema = {
   locations: z.array(z.string()).optional().describe('Person or company locations'),
   keywords: z.array(z.string()).optional().describe('Free-text keyword search terms (e.g. ["growth", "AI"])'),
   limit: z.number().min(1).max(500).default(25).describe('Max results across all companies combined (default: 25, max: 500). For multiple companies multiply: e.g. 10 companies × 5 each = 50.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_people').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function findPeopleHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('find_people', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('find_people', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('find_people', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }
@@ -35,16 +42,16 @@ export async function findPeopleHandler(input: Record<string, unknown>) {
   // Gap-fill: if LeadsFactory missed some domains, try Apollo for those.
   // Only runs when domains were the input — if we sent LinkedIn URLs, no_results_domains
   // is unreliable (LF may resolve arbitrary domains from URLs, e.g. linkedin.com itself).
-  const inputHadDomains = Array.isArray(input.company_domains) && (input.company_domains as unknown[]).length > 0
-  const inputHadLinkedInUrls = Array.isArray(input.company_linkedin_urls) && (input.company_linkedin_urls as unknown[]).length > 0
-  if (result._meta.provider === 'leadsfactory' && inputHadDomains && !inputHadLinkedInUrls) {
+  const inputHadDomains = Array.isArray(restInput.company_domains) && (restInput.company_domains as unknown[]).length > 0
+  const inputHadLinkedInUrls = Array.isArray(restInput.company_linkedin_urls) && (restInput.company_linkedin_urls as unknown[]).length > 0
+  if (resolved.providers.length === 0 && result._meta.provider === 'leadsfactory' && inputHadDomains && !inputHadLinkedInUrls) {
     const data = result.data as Record<string, unknown>
     const missedDomains = (data.no_results_domains as string[] | undefined) ?? []
 
     if (missedDomains.length > 0) {
       const apollo = getProviders('find_people').find((p) => p.id === 'apollo')
       if (apollo) {
-        const gapInput = { ...input, company_domains: missedDomains, company_linkedin_urls: undefined }
+        const gapInput = { ...restInput, company_domains: missedDomains, company_linkedin_urls: undefined }
         const payload = apollo.mapParams(gapInput)
         const apolloRes = await callApi(apollo.method, apollo.endpoint, payload.body, payload.queryParams)
 

package/src/tools/find-phone.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findPhoneName = 'find_phone'
 
@@ -12,6 +13,7 @@ export const findPhoneSchema = {
   last_name: z.string().optional().describe('Last name (required when no LinkedIn URL)'),
   company_domain: z.string().optional().describe('Company domain, e.g. coldiq.com'),
   company_name: z.string().optional().describe('Company name (alternative to company_domain)'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_phone').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 const inputSchema = z
@@ -37,7 +39,12 @@ const inputSchema = z
   })
 
 export async function findPhoneHandler(input: Record<string, unknown>) {
-  const validation = inputSchema.safeParse(input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('find_phone', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const validation = inputSchema.safeParse(restInput)
   if (!validation.success) {
     const msg = validation.error.issues.map((i) => i.message).join('; ')
     return {
@@ -45,7 +52,7 @@ export async function findPhoneHandler(input: Record<string, unknown>) {
       isError: true,
     }
   }
-  const result = await executeWithFallback('find_phone', input)
+  const result = await executeWithFallback('find_phone', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/find-signals.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findSignalsName = 'find_signals'
 
@@ -47,13 +48,15 @@ export const findSignalsSchema = {
     .max(100)
     .default(25)
     .describe('Maximum number of signals to return (1–100).'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_signals').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function findSignalsHandler(input: Record<string, unknown>) {
-  const hasCompanies = Array.isArray(input.companies) && (input.companies as unknown[]).length > 0
-  const hasDomains = Array.isArray(input.domains) && (input.domains as unknown[]).length > 0
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const hasCompanies = Array.isArray(restInput.companies) && (restInput.companies as unknown[]).length > 0
+  const hasDomains = Array.isArray(restInput.domains) && (restInput.domains as unknown[]).length > 0
 
-  if (input.signal_type === 'intent' && !hasCompanies && !hasDomains) {
+  if (restInput.signal_type === 'intent' && !hasCompanies && !hasDomains) {
     return {
       content: [{
         type: 'text' as const,
@@ -63,7 +66,7 @@ export async function findSignalsHandler(input: Record<string, unknown>) {
     }
   }
 
-  if ((input.signal_type === 'news' || input.signal_type === 'startup_post') && (hasCompanies || hasDomains)) {
+  if ((restInput.signal_type === 'news' || restInput.signal_type === 'startup_post') && (hasCompanies || hasDomains)) {
     return {
       content: [{
         type: 'text' as const,
@@ -75,14 +78,19 @@ export async function findSignalsHandler(input: Record<string, unknown>) {
     }
   }
 
-  const result = await executeWithFallback('find_signals', input)
+  const resolved = resolvePreferredProviders('find_signals', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+
+  const result = await executeWithFallback('find_signals', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }
 
   // buying_intents upstream has no limit param — truncate to requested limit
-  if (input.signal_type === 'intent') {
-    const limit = typeof input.limit === 'number' ? input.limit : 25
+  if (restInput.signal_type === 'intent') {
+    const limit = typeof restInput.limit === 'number' ? restInput.limit : 25
     const typed = result as { data?: { data?: unknown[] } }
     if (Array.isArray(typed.data?.data)) {
       typed.data!.data = typed.data!.data.slice(0, limit)

package/src/tools/search-ads.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchAdsName = 'search_ads'
 
@@ -33,10 +34,16 @@ export const searchAdsSchema = {
   objective_type: z.enum(['AWARENESS', 'CONVERSIONS', 'APP_INSTALLS', 'TRAFFIC', 'VIDEO_VIEWABLE_IMPRESSIONS']).optional().describe('Reddit only.'),
 
   platform: z.enum(['google', 'linkedin', 'meta', 'twitter', 'reddit']).optional().describe('Pin to one platform; skips all others. Useful for cross-platform comparison via separate calls.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_ads').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchAdsHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_ads', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_ads', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_ads', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-companies.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchCompaniesName = 'search_companies'
 
 export const searchCompaniesDescription =
-  'Search B2B companies by industry, size, geography, founding year, tech stack, funding, revenue, exclusion lists, and hiring signals. Routing is automatic: strict firmographic filters (revenue, employee bands, exclusion lists) get high-precision providers first; tech-stack and funding-stage filters route to specialized providers; loose keyword/geo searches fall back to broad providers; a LinkedIn Sales Navigator search URL enables URL-based discovery as a final fallback. Default limit: 25.'
+  'Search B2B companies by industry, size, geography, founding year, tech stack, funding, revenue, exclusion lists, and hiring signals. Routing is automatic: strict firmographic filters (revenue, employee bands, exclusion lists) get high-precision providers first; tech-stack and funding-stage filters route to specialized providers; loose keyword/geo searches fall back to broad providers; a LinkedIn Sales Navigator search URL enables URL-based discovery as a final fallback. ColdIQ automatically picks the best provider — pass use_providers only if you need a specific tool. Default limit: 25.'
 
 export const searchCompaniesSchema = {
   keywords: z.array(z.string()).optional().describe('Industry keywords or topics (e.g. ["SaaS", "fintech"])'),
@@ -30,10 +31,16 @@ export const searchCompaniesSchema = {
   min_workforce_growth_pct: z.number().optional().describe('Minimum workforce growth % over the past 12 months (e.g. 10 for 10%)'),
   linkedin_search_url: z.string().optional().describe('LinkedIn Sales Navigator company search URL — when provided, enables URL-based prospect discovery as a final fallback. Most users should leave this unset.'),
   limit: z.number().min(1).max(100).default(25).describe('Max results to return (default: 25, max: 100)'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_companies').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchCompaniesHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_companies', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_companies', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_companies', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-jobs.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 const _CAREER_SITE_ONLY = ['ats_slugs', 'exclude_ats_slugs', 'company_domains', 'exclude_company_domains']
 const _LINKEDIN_ONLY = ['seniority_levels', 'industries', 'organization_slugs', 'exclude_organization_slugs', 'min_employees', 'max_employees', 'easy_apply_only', 'exclude_easy_apply']
@@ -54,10 +55,12 @@ export const searchJobsSchema = {
   max_employees: z.number().int().min(1).optional(),
   easy_apply_only: z.boolean().optional().describe('Only LinkedIn Easy Apply jobs. Routes to LinkedIn source.'),
   exclude_easy_apply: z.boolean().optional().describe('Exclude LinkedIn Easy Apply jobs. Routes to LinkedIn source.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_jobs').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchJobsHandler(input: Record<string, unknown>) {
-  if (_isFilterSet(input, _CAREER_SITE_ONLY) && _isFilterSet(input, _LINKEDIN_ONLY)) {
+  const { use_providers: rawUseProviders, ...restInput } = input
+  if (_isFilterSet(restInput, _CAREER_SITE_ONLY) && _isFilterSet(restInput, _LINKEDIN_ONLY)) {
     const err = {
       error:
         'Contradictory filters: ATS/domain filters (ats_slugs, company_domains) are Career Site only, ' +
@@ -65,7 +68,11 @@ export async function searchJobsHandler(input: Record<string, unknown>) {
     }
     return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
   }
-  const result = await executeWithFallback('search_jobs', input)
+  const resolved = resolvePreferredProviders('search_jobs', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_jobs', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-places.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchPlacesName = 'search_places'
 
@@ -41,10 +42,16 @@ export const searchPlacesSchema = {
   include_opening_hours: z.boolean().optional().describe('Google Maps only. Routes to Google Maps only when set.'),
   include_additional_info: z.boolean().optional().describe('Google Maps only. Adds amenities/accessibility fields. Routes to Google Maps only when set.'),
   language: z.string().optional().describe('Google Maps only. ISO 639-1 (e.g. "en", "fr"). Routes to Google Maps only when set.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_places').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchPlacesHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_places', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_places', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_places', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-reddit.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchRedditName = 'search_reddit'
 
@@ -23,10 +24,16 @@ export const searchRedditSchema = {
     .describe('Max comments per post when type=comments.'),
   include_comments: z.boolean().optional()
     .describe('Include comments alongside posts.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_reddit').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchRedditHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_reddit', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_reddit', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_reddit', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-seo.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchSeoName = 'search_seo'
 
@@ -48,10 +49,16 @@ export const searchSeoSchema = {
     .describe('page: "lighthouse" (Core Web Vitals audit) or "content" (parse page text).'),
   enable_javascript: z.boolean().optional(),
   full_data: z.boolean().optional().describe('Lighthouse only: include full audit data.'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_seo').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchSeoHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_seo', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_seo', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_seo', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/search-web.ts

@@ -1,22 +1,30 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchWebName = 'search_web'
 
 export const searchWebDescription =
   'Search the web for market research, company news, or general lookups. Supports Google search (default) and neural/semantic search via Exa. ' +
   'NEVER use this to find, verify, or look up people, contacts, LinkedIn profiles, or executives — even as a fallback when find_people returns uncertain results. ' +
-  'find_people is the only tool for people lookups; do not supplement or replace it with web search.'
+  'find_people is the only tool for people lookups; do not supplement or replace it with web search. ' +
+  'ColdIQ automatically picks the best provider — pass use_providers only if you need a specific tool.'
 
 export const searchWebSchema = {
   query: z.string().describe('Search query'),
   num_results: z.number().min(1).max(100).default(10).describe('Number of results (default: 10, max: 100)'),
   country: z.string().optional().describe('Country code for geo-targeting (e.g. "us", "fr")'),
   search_type: z.enum(['general', 'neural']).default('general').describe('"general" for Google search (default), "neural" for semantic search via Exa'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_web').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function searchWebHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('search_web', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('search_web', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_web', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/verify-email.ts

@@ -1,17 +1,24 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const verifyEmailName = 'verify_email'
 
 export const verifyEmailDescription =
-  'Check whether an email address is valid and deliverable. Returns verification status (valid, invalid, catch-all, unknown). Use before cold outreach to protect sender reputation.'
+  'Check whether an email address is valid and deliverable. Returns verification status (valid, invalid, catch-all, unknown). Use before cold outreach to protect sender reputation. ColdIQ automatically picks the best provider — pass use_providers only if you need a specific tool.'
 
 export const verifyEmailSchema = {
   email: z.string().email().describe('Email address to verify'),
+  use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('verify_email').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function verifyEmailHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('verify_email', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('verify_email', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('verify_email', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }