@coldiq/mcp 0.3.4 → 0.3.6

package/src/utils/provider-display.ts

@@ -0,0 +1,150 @@
+// ---------------------------------------------------------------------------
+// Provider display names
+// ---------------------------------------------------------------------------
+//
+// Internal provider IDs (registry.ts + the find_emails waterfall) are a mix of
+// clean vendor names ("apollo"), already-branded slugs ("reddit_ads"), and ugly
+// internal slugs ("limadata-work-email"). User-facing surfaces — the selection
+// insight and `_meta.provider_name` — must show a clean branded label instead.
+//
+// Naming the real data product (FullEnrich, TheirStack, …) is intentional: it IS
+// the ColdIQ "we picked the best tool" intelligence on display. The ONLY thing
+// that must never surface is the Apify backend — and since no ID contains the
+// word "Apify", that constraint is satisfied by mapping the Apify-backed scrapers
+// to their branded data-source name (e.g. "Reddit Ads").
+// ---------------------------------------------------------------------------
+
+const DISPLAY_NAMES: Record<string, string> = {
+  // --- B2B data vendors (shared across capabilities) -----------------------
+  companyenrich: 'CompanyEnrich',
+  companyenrich_props: 'CompanyEnrich',
+  apollo: 'Apollo',
+  'apollo-people-match': 'Apollo',
+  fullenrich: 'FullEnrich',
+  'fullenrich-people-search': 'FullEnrich',
+  pdl: 'People Data Labs',
+  'pdl-person-enrich': 'People Data Labs',
+  'pdl-person-identify': 'People Data Labs',
+  signalbase: 'SignalBase',
+  'signalbase-funding': 'SignalBase',
+  'signalbase-acquisition': 'SignalBase',
+  'signalbase-hiring': 'SignalBase',
+  'signalbase-job-change': 'SignalBase',
+  blitzapi: 'BlitzAPI',
+  'blitzapi-reverse-email': 'BlitzAPI',
+  limadata: 'LimaData',
+  'limadata-prospect-filter': 'LimaData',
+  'limadata-prospect-url': 'LimaData',
+  'limadata-work-email': 'LimaData',
+  'limadata-work-email-linkedin': 'LimaData',
+  predictleads: 'PredictLeads',
+  'predictleads-financing': 'PredictLeads',
+  'predictleads-news': 'PredictLeads',
+  'predictleads-startup-posts': 'PredictLeads',
+  theirstack: 'TheirStack',
+  'theirstack-jobs': 'TheirStack',
+  'theirstack-hiring': 'TheirStack',
+  'theirstack-intent-discovery': 'TheirStack',
+  'theirstack-buying-intents': 'TheirStack',
+  sumble: 'Sumble',
+  'sumble-people-find': 'Sumble',
+  prospeo: 'Prospeo',
+  'prospeo-search-company': 'Prospeo',
+  'prospeo-search-person': 'Prospeo',
+  'ai-ark': 'AI-ARK',
+  'ai-ark-companies': 'AI-ARK',
+  'ai-ark-people': 'AI-ARK',
+  'ai-ark-reverse-lookup': 'AI-ARK',
+  leadsfactory: 'LeadsFactory',
+  findymail: 'Findymail',
+  'findymail-search-employees': 'Findymail',
+  'findymail-business-profile': 'Findymail',
+  'findymail-reverse-email': 'Findymail',
+  icypeas: 'Icypeas',
+  'icypeas-scrape-profile': 'Icypeas',
+  'icypeas-url-search-profile': 'Icypeas',
+  'icypeas-reverse-email-lookup': 'Icypeas',
+  wiza: 'Wiza',
+  builtwith: 'BuiltWith',
+  openmart: 'Openmart',
+  instantly: 'Instantly',
+
+  // --- LinkupAPI (LinkedIn data) -------------------------------------------
+  linkupapi: 'LinkupAPI',
+  'linkupapi-search': 'LinkupAPI',
+  'linkupapi-fundraising': 'LinkupAPI',
+  'linkupapi-hiring': 'LinkupAPI',
+  'linkupapi-search-profiles': 'LinkupAPI',
+  'linkupapi-by-domain': 'LinkupAPI',
+  'linkupapi-by-url': 'LinkupAPI',
+  'linkupapi-profile-enrich': 'LinkupAPI',
+  'linkupapi-email-reverse': 'LinkupAPI',
+  'linkupapi-validate': 'LinkupAPI',
+
+  // --- search_web ----------------------------------------------------------
+  serper: 'Serper',
+  exa: 'Exa',
+  'exa-contents': 'Exa',
+  jina: 'Jina',
+
+  // --- search_jobs ---------------------------------------------------------
+  career_site_jobs: 'Career Site Jobs',
+  linkedin_jobs_api: 'LinkedIn Jobs',
+
+  // --- search_ads ----------------------------------------------------------
+  google_ads: 'Google Ads',
+  linkedin_ad_library: 'LinkedIn Ad Library',
+  meta_ads: 'Meta Ads',
+  twitter_ads: 'X Ads',
+  reddit_ads: 'Reddit Ads',
+
+  // --- search_places / reviews ---------------------------------------------
+  google_maps: 'Google Maps',
+  google_maps_reviews: 'Google Maps',
+
+  // --- find_influencers ----------------------------------------------------
+  influencers_similar: 'Influencer Discovery',
+  influencers_discovery: 'Influencer Discovery',
+
+  // --- search_reddit -------------------------------------------------------
+  reddit: 'Reddit',
+
+  // --- search_seo (functional sub-actions) ---------------------------------
+  kw_search_volume: 'Keyword Search Volume',
+  kw_trends: 'Keyword Trends',
+  serp_google: 'Google SERP',
+  serp_bing: 'Bing SERP',
+  serp_youtube: 'YouTube SERP',
+  bl_summary: 'Backlink Summary',
+  bl_backlinks: 'Backlinks',
+  bl_referring: 'Referring Domains',
+  domain_tech: 'Domain Technologies',
+  domain_whois: 'Domain WHOIS',
+  labs_rank_overview: 'Rank Overview',
+  labs_ranked_kw: 'Ranked Keywords',
+  labs_competitors: 'Competitor Domains',
+  labs_kw_ideas: 'Keyword Ideas',
+  page_lighthouse: 'Lighthouse Audit',
+  page_content: 'Page Content',
+}
+
+/**
+ * Title-case an unmapped provider ID as a defensive fallback so a newly added
+ * provider still renders acceptably (and never leaks a raw slug). E.g.
+ * "some-new-vendor" → "Some New Vendor".
+ */
+function titleCaseId(id: string): string {
+  return id
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Map an internal provider ID to a clean, branded display name. Falls back to a
+ * title-cased form of the ID when unmapped. Never returns "Apify".
+ */
+export function providerDisplayName(id: string): string {
+  return DISPLAY_NAMES[id] ?? titleCaseId(id)
+}

package/src/utils/selection-insight.ts

@@ -0,0 +1,359 @@
+import type { Capability } from '../registry.js'
+import { providerDisplayName } from './provider-display.js'
+
+// ---------------------------------------------------------------------------
+// Selection insight — a short, human-readable, DATA-QUALITY-framed reason for
+// why ColdIQ routed a request to a given provider. Surfaced in `_meta` so the
+// chat layer can show the "we picked the best tool" intelligence.
+//
+// Rules baked in here (see CLAUDE.md + the plan):
+//   • Data-quality reasons ONLY — coverage / specialization / freshness / region.
+//     NEVER price, never "tried first", never waterfall position.
+//   • Honest about the two ways a provider wins:
+//       - capability routing (others gated out) → confident "Routed to X for …"
+//       - fallthrough (others returned nothing)  → softened "X returned the match …"
+//   • Never fabricate a strength: when a provider has no curated edge we emit a
+//     plain, true line ("X matched this …") instead of inventing specialization.
+//   • Display names only (no raw slugs, no "Apify") — via providerDisplayName.
+// ---------------------------------------------------------------------------
+
+export type InsightCapability = Capability | 'find_emails'
+
+export interface SelectionInsight {
+  insight: string
+  signals: string[]
+}
+
+export interface InsightContext {
+  /** True when the chosen provider won only because higher-ranked providers
+   *  returned no rows (not because it was the best-suited for the inputs). */
+  wasFallback: boolean
+  /** True when the caller pinned this provider via `use_providers`. */
+  pinnedByUser: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Curated data-quality strengths, keyed by capability → providerId.
+// Each value is a noun phrase that slots into "… for its <strength>". Phrasing
+// is descriptive (deep / strong / broad / specialized), NOT superlative, so it
+// stays defensible on the fallthrough path too.
+// ---------------------------------------------------------------------------
+
+const STRENGTHS: Partial<Record<InsightCapability, Record<string, string>>> = {
+  search_companies: {
+    companyenrich: 'broad firmographic coverage with full-text company matching',
+    apollo: 'an extensive global company database',
+    fullenrich: 'rich firmographic data with strong international coverage',
+    pdl: 'a large, structured global company dataset',
+    signalbase: 'fast firmographic search across keywords and industries',
+    blitzapi: 'LinkedIn-sourced company data',
+    limadata: 'LinkedIn-based company discovery',
+    predictleads: 'discovery scoped tightly by location and company size',
+    theirstack: 'deep technographic and buying-intent coverage',
+    sumble: 'technology- and keyword-driven company discovery',
+    'limadata-prospect-filter': 'LinkedIn headcount-bucketed prospecting',
+    'limadata-prospect-url': 'discovery straight from a LinkedIn Sales Navigator search',
+    'linkupapi-search': 'live LinkedIn company search',
+    'linkupapi-fundraising': 'a dedicated index of recently-funded companies',
+    'linkupapi-hiring': 'a dedicated index of actively-hiring companies',
+    'prospeo-search-company': 'keyword, industry and geo company search',
+    'ai-ark-companies': 'multi-filter company discovery',
+  },
+  find_people: {
+    leadsfactory: 'company-scoped contact discovery by persona',
+    apollo: 'an extensive global contact database',
+    pdl: 'a large, structured global people dataset',
+    companyenrich: 'domain-scoped employee lookups',
+    'linkupapi-search-profiles': 'live LinkedIn profile search',
+    'sumble-people-find': 'org-scoped people search by job function',
+    'prospeo-search-person': 'title- and company-based people search',
+    'ai-ark-people': 'multi-filter people discovery',
+    'fullenrich-people-search': 'domain-scoped people search',
+    'findymail-search-employees': 'domain-scoped employee discovery',
+  },
+  find_email: {
+    prospeo: 'strong work-email coverage',
+    fullenrich: 'strong international email coverage, especially across Europe',
+    findymail: 'high-accuracy verified work emails',
+    icypeas: 'broad email-finding coverage',
+    'limadata-work-email': 'name-and-domain work-email lookup',
+    blitzapi: 'LinkedIn-URL–based email finding',
+    'limadata-work-email-linkedin': 'LinkedIn-URL–based work-email lookup',
+    linkupapi: 'LinkedIn-sourced email finding',
+  },
+  find_emails: {
+    prospeo: 'strong work-email coverage',
+    fullenrich: 'strong international email coverage, especially across Europe',
+    findymail: 'high-accuracy verified work emails',
+    icypeas: 'broad email-finding coverage',
+    'limadata-work-email': 'name-and-domain work-email lookup',
+    blitzapi: 'LinkedIn-URL–based email finding',
+    'limadata-work-email-linkedin': 'LinkedIn-URL–based work-email lookup',
+    linkupapi: 'LinkedIn-sourced email finding',
+  },
+  verify_email: {
+    findymail: 'reliable deliverability verification',
+    icypeas: 'broad email verification',
+    instantly: 'deliverability-focused verification',
+    'linkupapi-validate': 'LinkedIn-aware email validation',
+  },
+  find_phone: {
+    findymail: 'verified mobile-number coverage',
+    limadata: 'phone lookup by LinkedIn URL or name + company',
+    'ai-ark': 'phone lookup across multiple identifiers',
+  },
+  enrich_company: {
+    companyenrich: 'broad firmographic enrichment from a domain',
+    apollo: 'deep firmographic enrichment',
+    pdl: 'structured firmographic data',
+    findymail: 'domain-based company enrichment',
+    wiza: 'company enrichment from name or domain',
+    limadata: 'LinkedIn-based company enrichment',
+    prospeo: 'company enrichment',
+    companyenrich_props: 'company enrichment from name or LinkedIn',
+    blitzapi: 'LinkedIn-URL company enrichment',
+    icypeas: 'LinkedIn-URL company enrichment',
+    builtwith: 'technology-stack detection for a domain',
+    openmart: 'local-business firmographics',
+    'linkupapi-by-domain': 'live LinkedIn company data',
+    'linkupapi-by-url': 'live LinkedIn company data',
+  },
+  enrich_person: {
+    'linkupapi-profile-enrich': 'live LinkedIn profile enrichment',
+    'linkupapi-email-reverse': 'reverse-email lookup from LinkedIn data',
+    'pdl-person-enrich': 'structured person enrichment',
+    'apollo-people-match': 'deep person enrichment',
+    'blitzapi-reverse-email': 'reverse-email profile lookup',
+    'findymail-business-profile': 'LinkedIn profile enrichment',
+    'findymail-reverse-email': 'reverse-email lookup',
+    'icypeas-scrape-profile': 'LinkedIn profile scraping',
+    'icypeas-url-search-profile': 'profile lookup by name and company',
+    'ai-ark-reverse-lookup': 'reverse lookup from email or phone',
+    'icypeas-reverse-email-lookup': 'reverse-email lookup',
+    'pdl-person-identify': 'person identity resolution',
+  },
+  search_web: {
+    serper: 'fast Google search results',
+    exa: 'neural, meaning-based web search',
+    limadata: 'general web search',
+    jina: 'web search and page reading',
+  },
+  search_jobs: {
+    career_site_jobs: 'jobs sourced directly from company career sites',
+    linkedin_jobs_api: 'LinkedIn job listings',
+    'theirstack-jobs': 'jobs enriched with company and tech-stack data',
+  },
+  search_ads: {
+    google_ads: 'Google ad-transparency data',
+    linkedin_ad_library: 'LinkedIn Ad Library coverage',
+    meta_ads: 'Meta (Facebook/Instagram) ad-library coverage',
+    twitter_ads: 'X ad coverage',
+    reddit_ads: 'Reddit ad coverage',
+  },
+  search_places: {
+    openmart: 'rich local-business data across the US, CA, AU, PR and NZ',
+    google_maps: 'broad global places coverage from Google Maps',
+  },
+  get_place_reviews: {
+    google_maps_reviews: 'Google Maps review data',
+  },
+  find_influencers: {
+    influencers_similar: 'lookalike creator discovery from a seed handle',
+    influencers_discovery: 'creator discovery by topic and audience',
+  },
+  search_reddit: {
+    reddit: 'Reddit post and comment search',
+  },
+  find_signals: {
+    'signalbase-funding': 'real-time funding-round signals',
+    'signalbase-acquisition': 'acquisition signals',
+    'signalbase-hiring': 'hiring signals',
+    'signalbase-job-change': 'job-change signals',
+    'theirstack-hiring': 'hiring signals from job-posting data',
+    'theirstack-intent-discovery': 'buying-intent discovery',
+    'theirstack-buying-intents': 'buying-intent signals from tech and job data',
+    'predictleads-financing': 'financing-event signals',
+    'predictleads-news': 'company-news signals',
+    'predictleads-startup-posts': 'startup-announcement signals',
+  },
+  fetch_page_content: {
+    'exa-contents': 'clean page-content extraction',
+  },
+}
+
+/**
+ * Read the curated data-quality strength for a provider within a capability,
+ * if one exists. Exposed for the `list_data_sources` catalog so the strengths
+ * stay defined in one place.
+ */
+export function getProviderStrength(
+  capability: InsightCapability,
+  providerId: string,
+): string | undefined {
+  return STRENGTHS[capability]?.[providerId]
+}
+
+// ---------------------------------------------------------------------------
+// Per-capability noun used in the plain fallback line ("X matched this <noun>").
+// ---------------------------------------------------------------------------
+
+const CAPABILITY_NOUN: Record<InsightCapability, string> = {
+  search_companies: 'company search',
+  find_people: 'people search',
+  find_email: 'email lookup',
+  find_emails: 'email lookup',
+  verify_email: 'email verification',
+  find_phone: 'phone lookup',
+  enrich_company: 'company enrichment',
+  enrich_person: 'person enrichment',
+  search_web: 'web search',
+  search_jobs: 'job search',
+  search_ads: 'ad search',
+  search_places: 'places search',
+  get_place_reviews: 'reviews lookup',
+  find_influencers: 'influencer search',
+  search_reddit: 'Reddit search',
+  search_seo: 'SEO lookup',
+  find_signals: 'signal search',
+  fetch_page_content: 'page fetch',
+}
+
+// ---------------------------------------------------------------------------
+// Signal detection — which input dimensions drove routing, in human terms.
+// Ordered most-distinctive-first so signals[0] is the routing-relevant one.
+// ---------------------------------------------------------------------------
+
+function arr(v: unknown): boolean {
+  return Array.isArray(v) && v.length > 0
+}
+function num(v: unknown): boolean {
+  return typeof v === 'number'
+}
+function str(v: unknown): boolean {
+  return typeof v === 'string' && v.length > 0
+}
+
+function detectSignals(capability: InsightCapability, input: Record<string, unknown>): string[] {
+  const out: string[] = []
+  const push = (cond: boolean, label: string) => {
+    if (cond && !out.includes(label)) out.push(label)
+  }
+
+  switch (capability) {
+    case 'search_companies':
+      push(arr(input.technologies), 'tech-stack filter')
+      push(
+        arr(input.funding_stages) ||
+          num(input.min_funding_amount) || num(input.max_funding_amount) ||
+          num(input.min_funding_year) || num(input.max_funding_year),
+        'funding filter',
+      )
+      push(num(input.min_revenue) || num(input.max_revenue), 'revenue filter')
+      push(arr(input.exclude_domains) || arr(input.exclude_industries) || arr(input.exclude_countries), 'exclusion list')
+      push(num(input.min_workforce_growth_pct), 'workforce-growth filter')
+      push(input.is_hiring === true, 'hiring signal')
+      push(num(input.min_founded_year) || num(input.max_founded_year), 'founding-year filter')
+      push(num(input.min_employees) || num(input.max_employees), 'company-size filter')
+      push(str(input.linkedin_search_url), 'LinkedIn Sales Navigator URL')
+      push(arr(input.industries), 'industry filter')
+      push(arr(input.keywords), 'keyword search')
+      push(arr(input.countries) || arr(input.locations), 'geo filter')
+      break
+    case 'find_people':
+      push(arr(input.company_domains), 'company-domain filter')
+      push(arr(input.company_linkedin_urls), 'company LinkedIn filter')
+      push(arr(input.job_titles), 'job-title filter')
+      push(arr(input.seniorities), 'seniority filter')
+      push(arr(input.keywords), 'keyword search')
+      push(arr(input.locations), 'geo filter')
+      break
+    case 'find_email':
+      push(str(input.linkedin_url), 'LinkedIn URL')
+      push(str(input.domain) || str(input.company_name), 'name + company')
+      break
+    case 'find_emails': {
+      const people = (input.people as Array<Record<string, unknown>> | undefined) ?? []
+      push(people.some((p) => str(p.linkedin_url)), 'LinkedIn URLs')
+      push(people.some((p) => str(p.domain)), 'name + domain')
+      break
+    }
+    case 'enrich_company':
+      push(str(input.domain), 'company domain')
+      push(str(input.linkedin_url), 'LinkedIn URL')
+      push(str(input.name), 'company name')
+      break
+    case 'enrich_person':
+      push(str(input.email), 'email')
+      push(str(input.linkedin_url), 'LinkedIn URL')
+      push(str(input.first_name) && str(input.last_name), 'name + company')
+      break
+    case 'find_signals':
+      if (str(input.signal_type)) out.push(`${String(input.signal_type)} signals`)
+      push(arr(input.companies) || arr(input.domains), 'company filter')
+      break
+    case 'search_jobs':
+      push(arr(input.technologies), 'tech-stack filter')
+      push(arr(input.company_domains), 'company-domain filter')
+      push(arr(input.job_titles) || arr(input.keywords), 'role filter')
+      push(arr(input.locations), 'geo filter')
+      break
+    case 'search_ads':
+      push(arr(input.search_urls), 'LinkedIn Ad Library URL')
+      push(arr(input.domains) || arr(input.advertiser_ids), 'advertiser filter')
+      push(str(input.query), 'keyword search')
+      break
+    default:
+      // Other capabilities: no curated signal vocabulary — routing is single-source
+      // or non-discriminating, so leave signals empty and rely on the base strength.
+      break
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a data-quality-framed reason for why `providerId` was selected for
+ * `capability` given `input`. Returns undefined only when there is genuinely
+ * nothing safe to say.
+ */
+export function buildSelectionInsight(
+  capability: InsightCapability,
+  providerId: string,
+  input: Record<string, unknown>,
+  ctx: InsightContext,
+): SelectionInsight | undefined {
+  const name = providerDisplayName(providerId)
+  const signals = detectSignals(capability, input)
+
+  // User pinned this provider — it wasn't our choice, so don't claim it was.
+  if (ctx.pinnedByUser) {
+    return { insight: `Used ${name} as requested.`, signals }
+  }
+
+  const strength = STRENGTHS[capability]?.[providerId]
+  const noun = CAPABILITY_NOUN[capability] ?? 'request'
+  const primary = signals[0]
+
+  // No curated edge for this provider — emit a plain, true line, never invent one.
+  if (!strength) {
+    const insight = primary
+      ? `${name} matched your ${primary} for this ${noun}.`
+      : `${name} matched this ${noun}.`
+    return { insight, signals }
+  }
+
+  // Fallthrough: higher-ranked providers returned nothing. Soften — state the
+  // coverage fact without implying we judged it the single best fit upfront.
+  if (ctx.wasFallback) {
+    return { insight: `${name} returned the match here, with ${strength}.`, signals }
+  }
+
+  // Capability routing: chosen because it is best-suited to these inputs.
+  const insight = primary
+    ? `Routed to ${name} for its ${strength}, matched to your ${primary}.`
+    : `Routed to ${name} for its ${strength}.`
+  return { insight, signals }
+}

package/tests/executor.test.ts

@@ -954,3 +954,80 @@ describe('executor upstream_error propagation', () => {
     }
   })
 })
+
+// ---------------------------------------------------------------------------
+// Selection insight + branded provider name in _meta
+// ---------------------------------------------------------------------------
+
+describe('executor selection insight _meta', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key-123')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('attaches branded provider_name + confident insight when first applicable provider wins', async () => {
+    stubProviders([
+      makeProvider({ id: 'theirstack', hasResult: (d) => (d as Record<string, unknown>).ok === true }),
+    ])
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    ) as typeof fetch
+
+    const result = await executeWithFallback('search_companies', { technologies: ['Salesforce'] })
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.provider).toBe('theirstack')
+      expect(result._meta.provider_name).toBe('TheirStack')
+      expect(result._meta.selection_insight).toContain('Routed to TheirStack')
+      expect(result._meta.selection_insight).toContain('tech-stack filter')
+      expect(result._meta.selection_signals).toContain('tech-stack filter')
+    }
+  })
+
+  it('softens the insight when the winner is reached only after a provider fails', async () => {
+    stubProviders([
+      makeProvider({ id: 'companyenrich', hasResult: () => false }),
+      makeProvider({ id: 'fullenrich', hasResult: (d) => (d as Record<string, unknown>).ok === true }),
+    ])
+    let n = 0
+    globalThis.fetch = vi.fn(async () => {
+      n++
+      return new Response(JSON.stringify({ ok: n > 1 }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await executeWithFallback('search_companies', { keywords: ['fintech'] })
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.provider_name).toBe('FullEnrich')
+      expect(result._meta.selection_insight).toContain('returned the match here')
+      expect(result._meta.selection_insight!.startsWith('Routed to')).toBe(false)
+    }
+  })
+
+  it('says "as requested" when the provider was pinned by the caller', async () => {
+    stubProviders([
+      makeProvider({ id: 'theirstack', hasResult: (d) => (d as Record<string, unknown>).ok === true }),
+    ])
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    ) as typeof fetch
+
+    const result = await executeWithFallback(
+      'search_companies',
+      { technologies: ['Salesforce'] },
+      { providers: ['theirstack'] },
+    )
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.selection_insight).toBe('Used TheirStack as requested.')
+    }
+  })
+})

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

@@ -43,8 +43,8 @@ describe('find_emails handler (bulk)', () => {
     expect(parsed.data.found).toBe(2)
     expect(parsed.data.total).toBe(2)
     expect(parsed.data.results).toEqual([
-      { id: 'p1', email: 'alice@example.com', provider: 'prospeo' },
-      { id: 'p2', email: 'bob@example.com', provider: 'prospeo' },
+      { id: 'p1', email: 'alice@example.com', provider: 'prospeo', provider_name: 'Prospeo' },
+      { id: 'p2', email: 'bob@example.com', provider: 'prospeo', provider_name: 'Prospeo' },
     ])
   })
 
@@ -77,7 +77,7 @@ describe('find_emails handler (bulk)', () => {
 
     expect(fmCalled).toBe(true)
     const parsed = JSON.parse(result.content[0].text)
-    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'findymail' })
+    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'findymail', provider_name: 'Findymail' })
   })
 
   it('falls back to IcyPeas when FindyMail also misses', async () => {
@@ -103,7 +103,7 @@ describe('find_emails handler (bulk)', () => {
     })
 
     const parsed = JSON.parse(result.content[0].text)
-    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'icypeas' })
+    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'icypeas', provider_name: 'Icypeas' })
   })
 
   it('returns email:null when all providers miss for a person', async () => {
@@ -117,7 +117,7 @@ describe('find_emails handler (bulk)', () => {
 
     const parsed = JSON.parse(result.content[0].text)
     expect(parsed.data.found).toBe(0)
-    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: null, provider: null })
+    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: null, provider: null, provider_name: null })
   })
 
   it('handles mixed results: some from prospeo, some from fallback, some missed', async () => {
@@ -241,7 +241,7 @@ describe('find_emails handler (bulk)', () => {
     const body = feCreateBody as { data: Array<Record<string, unknown>> }
     expect(body.data[0].custom_id).toBe('p1')
     const parsed = JSON.parse(result.content[0].text)
-    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'fullenrich' })
+    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'alice@example.com', provider: 'fullenrich', provider_name: 'FullEnrich' })
   })
 
   it('parallel branches: faster FindyMail wins, slower FullEnrich does not overwrite', async () => {
@@ -284,7 +284,7 @@ describe('find_emails handler (bulk)', () => {
 
     const parsed = JSON.parse(result.content[0].text)
     // FindyMail won the race — its email + provider must persist
-    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'fm@example.com', provider: 'findymail' })
+    expect(parsed.data.results[0]).toEqual({ id: 'p1', email: 'fm@example.com', provider: 'findymail', provider_name: 'Findymail' })
   })
 
   it('gracefully handles prospeo bulk failure and still tries fallbacks', async () => {