@coldiq/mcp 0.3.4 → 0.3.5

package/src/utils/selection-insight.ts

@@ -0,0 +1,347 @@
+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',
+  },
+}
+
+// ---------------------------------------------------------------------------
+// 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 () => {

package/tests/utils/provider-display.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { providerDisplayName } from '../../src/utils/provider-display.js'
+
+describe('providerDisplayName', () => {
+  it('maps known vendor ids to branded names', () => {
+    expect(providerDisplayName('fullenrich')).toBe('FullEnrich')
+    expect(providerDisplayName('theirstack')).toBe('TheirStack')
+    expect(providerDisplayName('pdl')).toBe('People Data Labs')
+  })
+
+  it('collapses vendor variants to one brand', () => {
+    expect(providerDisplayName('limadata-work-email')).toBe('LimaData')
+    expect(providerDisplayName('limadata-prospect-url')).toBe('LimaData')
+    expect(providerDisplayName('signalbase-funding')).toBe('SignalBase')
+    expect(providerDisplayName('linkupapi-by-domain')).toBe('LinkupAPI')
+  })
+
+  it('brands Apify-backed scrapers as their data source, never raw slug', () => {
+    expect(providerDisplayName('reddit_ads')).toBe('Reddit Ads')
+    expect(providerDisplayName('linkedin_ad_library')).toBe('LinkedIn Ad Library')
+    expect(providerDisplayName('google_maps')).toBe('Google Maps')
+  })
+
+  it('title-cases unmapped ids as a defensive fallback', () => {
+    expect(providerDisplayName('some-new-vendor')).toBe('Some New Vendor')
+    expect(providerDisplayName('good')).toBe('Good')
+  })
+
+  it('never returns a raw slug or the word "Apify"', () => {
+    const ids = [
+      'limadata-work-email', 'reddit_ads', 'fullenrich', 'ai-ark-people',
+      'linkupapi-validate', 'theirstack-buying-intents', 'completely_unknown_slug',
+    ]
+    for (const id of ids) {
+      const name = providerDisplayName(id)
+      expect(name).not.toContain('_')
+      expect(name.toLowerCase()).not.toContain('apify')
+    }
+  })
+})

package/tests/utils/selection-insight.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest'
+import { buildSelectionInsight } from '../../src/utils/selection-insight.js'
+
+describe('buildSelectionInsight', () => {
+  describe('capability routing (gated-in, not fallback)', () => {
+    it('ties the choice to the distinctive input signal', () => {
+      const r = buildSelectionInsight(
+        'search_companies',
+        'theirstack',
+        { technologies: ['Salesforce'], keywords: ['saas'] },
+        { wasFallback: false, pinnedByUser: false },
+      )
+      expect(r).toBeDefined()
+      expect(r!.insight).toContain('TheirStack')
+      expect(r!.insight).toContain('technographic')
+      // tech-stack is the most distinctive signal → drives the "matched to your …" clause
+      expect(r!.insight).toContain('tech-stack filter')
+      expect(r!.insight.startsWith('Routed to')).toBe(true)
+      expect(r!.signals[0]).toBe('tech-stack filter')
+    })
+
+    it('omits the signal clause when no distinctive input is present', () => {
+      const r = buildSelectionInsight(
+        'enrich_company',
+        'apollo',
+        {},
+        { wasFallback: false, pinnedByUser: false },
+      )
+      expect(r!.insight).toBe('Routed to Apollo for its deep firmographic enrichment.')
+      expect(r!.signals).toEqual([])
+    })
+  })
+
+  describe('fallthrough (softened wording)', () => {
+    it('states coverage without claiming it was the upfront best fit', () => {
+      const r = buildSelectionInsight(
+        'find_email',
+        'fullenrich',
+        { domain: 'coldiq.com', first_name: 'Michel' },
+        { wasFallback: true, pinnedByUser: false },
+      )
+      expect(r!.insight).toContain('FullEnrich')
+      expect(r!.insight).toContain('returned the match here')
+      // never the confident "Routed to" framing on a fallthrough
+      expect(r!.insight.startsWith('Routed to')).toBe(false)
+    })
+  })
+
+  describe('user-pinned providers', () => {
+    it('does not claim ColdIQ chose it', () => {
+      const r = buildSelectionInsight(
+        'search_companies',
+        'theirstack',
+        { technologies: ['Salesforce'] },
+        { wasFallback: false, pinnedByUser: true },
+      )
+      expect(r!.insight).toBe('Used TheirStack as requested.')
+      // signals still surfaced for UI
+      expect(r!.signals).toContain('tech-stack filter')
+    })
+  })
+
+  describe('no curated edge — plain true line, no fabrication', () => {
+    it('emits a generic line for an unmapped provider', () => {
+      const r = buildSelectionInsight(
+        'enrich_company',
+        'good', // synthetic id, not in STRENGTHS
+        { domain: 'coldiq.com' },
+        { wasFallback: false, pinnedByUser: false },
+      )
+      expect(r!.insight).toBe('Good matched your company domain for this company enrichment.')
+      // no invented "deep/strong/broad coverage" claim
+      expect(r!.insight).not.toMatch(/deep|strong|broad|coverage|specializ/)
+    })
+
+    it('falls back to the barest true line with no signals', () => {
+      const r = buildSelectionInsight(
+        'search_reddit',
+        'mystery_provider',
+        {},
+        { wasFallback: false, pinnedByUser: false },
+      )
+      expect(r!.insight).toBe('Mystery Provider matched this Reddit search.')
+    })
+  })
+
+  describe('find_emails batch signals', () => {
+    it('detects LinkedIn URLs and name+domain across people', () => {
+      const r = buildSelectionInsight(
+        'find_emails',
+        'fullenrich',
+        { people: [{ id: '1', first_name: 'Michel', domain: 'coldiq.com', linkedin_url: 'https://linkedin.com/in/x' }] },
+        { wasFallback: true, pinnedByUser: false },
+      )
+      expect(r!.insight).toContain('FullEnrich')
+      expect(r!.signals).toContain('LinkedIn URLs')
+      expect(r!.signals).toContain('name + domain')
+    })
+  })
+
+  describe('honesty — fallthrough never claims an upfront best-fit judgment', () => {
+    it('uses the softened framing and no superiority superlatives', () => {
+      const r = buildSelectionInsight(
+        'find_people',
+        'apollo',
+        { job_titles: ['CEO'] },
+        { wasFallback: true, pinnedByUser: false },
+      )
+      expect(r!.insight).toContain('returned the match here')
+      expect(r!.insight.startsWith('Routed to')).toBe(false)
+      expect(r!.insight.toLowerCase()).not.toMatch(/\bbest\b|deepest|largest/)
+    })
+  })
+})