@coldiq/mcp 0.1.0

package/src/tools/enrich-company.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const enrichCompanyName = 'enrich_company'
+
+export const enrichCompanyDescription =
+  'Get detailed information about a company. Provide at least one of: domain, linkedin_url, or name. Returns company size, industry, funding, technologies, social profiles, and more. Use this to research a specific company before outreach or to fill in missing company data.'
+
+export const enrichCompanySchema = {
+  domain: z.string().optional().describe('Company domain (e.g. "stripe.com")'),
+  linkedin_url: z.string().url().optional().describe('Company LinkedIn URL (e.g. "https://www.linkedin.com/company/stripe")'),
+  name: z.string().optional().describe('Company name (e.g. "Stripe")'),
+}
+
+export async function enrichCompanyHandler(input: Record<string, unknown>) {
+  if (!input.domain && !input.linkedin_url && !input.name) {
+    const err = { error: 'At least one of domain, linkedin_url, or name is required', providers_tried: [] }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('enrich_company', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/enrich-person.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const enrichPersonName = 'enrich_person'
+
+export const enrichPersonDescription =
+  "Look up a person's LinkedIn profile and professional details. " +
+  'Accepts either an email address (reverse lookup) or name + company (profile enrichment). ' +
+  'Returns LinkedIn URL, headline, location, current role, and profile data.'
+
+export const enrichPersonSchema = {
+  email: z.string().email().optional().describe('Email address for reverse lookup — identify the person behind the email'),
+  first_name: z.string().optional().describe("Person's first name (use with last_name + company_name or domain)"),
+  last_name: z.string().optional().describe("Person's last name"),
+  company_name: z.string().optional().describe("Current company name (e.g. \"ColdIQ\")"),
+  domain: z.string().optional().describe('Company domain — alternative to company_name (e.g. "coldiq.com")'),
+  linkedin_url: z.string().url().optional().describe('LinkedIn profile URL for direct profile lookup (e.g. "https://www.linkedin.com/in/michel-lieben")'),
+  phone: z.string().optional().describe('Phone number for reverse phone lookup'),
+}
+
+export async function enrichPersonHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('enrich_person', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/fetch-page-content.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const fetchPageContentName = 'fetch_page_content'
+
+export const fetchPageContentDescription =
+  'Fetch the full text content of one or more web pages given their URLs. ' +
+  'Returns extracted page text suitable for RAG, summarisation, or fact extraction. ' +
+  'Use search_web first to discover URLs, then use this tool to fetch their full text. ' +
+  'Costs 1 credit per URL submitted.'
+
+export const fetchPageContentSchema = {
+  urls: z
+    .array(z.string().url())
+    .min(1)
+    .max(10)
+    .describe('URLs to fetch content from (1–10 URLs per call).'),
+  include_text: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('Extract and return full page text (default: true).'),
+  include_summary: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('Generate a summary for each page in addition to the text (default: false).'),
+}
+
+export async function fetchPageContentHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('fetch_page_content', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/find-email.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+import { executeWaterfall, isExecutionError } from '../executor.js'
+
+export const findEmailName = 'find_email'
+
+export const findEmailDescription =
+  "Find a person's professional email given their name and company. Tries multiple providers in sequence until an email is found (waterfall). Returns the email and which provider found it."
+
+export const findEmailSchema = {
+  first_name: z.string().optional().describe('First name of the person'),
+  last_name: z.string().optional().describe('Last name of the person'),
+  domain: z.string().optional().describe('Company domain (e.g. "stripe.com")'),
+  company_name: z.string().optional().describe('Company name — alternative to domain'),
+  linkedin_url: z.string().optional().describe('LinkedIn profile URL — alternative to name+domain'),
+}
+
+export async function findEmailHandler(input: Record<string, unknown>) {
+  const result = await executeWaterfall('find_email', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/find-emails.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod'
+import { callApi } from '../client.js'
+
+export const findEmailsName = 'find_emails'
+
+export const findEmailsDescription =
+  'Find professional emails for multiple people in one batch. ' +
+  'Uses bulk enrichment first, then a secondary provider for misses, then ' +
+  'two additional providers in parallel for any remaining misses. ' +
+  '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.'
+
+export const findEmailsSchema = {
+  people: z
+    .array(
+      z.object({
+        id: z.string().describe("Unique identifier to match results back (e.g. person's name or a slug)"),
+        first_name: z.string().optional().describe('First name'),
+        last_name: z.string().optional().describe('Last name'),
+        domain: z.string().optional().describe('Company domain (e.g. "stripe.com")'),
+        linkedin_url: z.string().optional().describe('LinkedIn profile URL — pass when available but always include name+domain too'),
+      }),
+    )
+    .min(1)
+    .max(50)
+    .describe('People to find emails for (max 50)'),
+}
+
+interface PersonInput {
+  id: string
+  first_name?: string
+  last_name?: string
+  domain?: string
+  linkedin_url?: string
+}
+
+interface EmailResult {
+  id: string
+  email: string | null
+  provider: string | null
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function missesOf(people: PersonInput[], results: EmailResult[]): PersonInput[] {
+  return people.filter((p) => !results.find((r) => r.id === p.id)?.email)
+}
+
+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 }))
+
+  // 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 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'
+        }
+      }
+    }
+  }
+
+  // Step 2: FullEnrich batch for Prospeo misses (async, better European coverage)
+  const afterProspeo = missesOf(people, results)
+
+  if (afterProspeo.length > 0) {
+    const feBody = {
+      name: 'mcp-enrich-batch',
+      data: afterProspeo.map((p) => ({
+        first_name: p.first_name,
+        last_name: p.last_name,
+        domain: p.domain,
+        ...(p.linkedin_url ? { linkedin_url: p.linkedin_url } : {}),
+        enrich_fields: ['contact.emails'],
+      })),
+    }
+
+    const feCreateRes = await callApi('POST', '/fullenrich/contact/enrich/bulk', feBody)
+
+    if (feCreateRes.ok) {
+      const enrichmentId = (feCreateRes.data as Record<string, unknown>).enrichment_id as string | undefined
+
+      if (enrichmentId) {
+        const deadline = Date.now() + 90_000
+        while (Date.now() < deadline) {
+          await sleep(5000)
+          const pollRes = await callApi('GET', `/fullenrich/contact/enrich/bulk/${enrichmentId}`)
+          if (!pollRes.ok) continue
+
+          const pd = pollRes.data as Record<string, unknown>
+          const status = pd.status as string | undefined
+          if (status === 'DONE' || status === 'FAILED') {
+            if (status === 'DONE') {
+              const feItems = pd.data as Array<Record<string, unknown>> | undefined
+              if (Array.isArray(feItems)) {
+                feItems.forEach((item, idx) => {
+                  const person = afterProspeo[idx]
+                  const hit = results.find((r) => r.id === person?.id)
+                  if (!hit || hit.email) return
+                  const emails = item.emails as string[] | undefined
+                  if (Array.isArray(emails) && emails.length > 0 && typeof emails[0] === 'string' && emails[0].includes('@')) {
+                    hit.email = emails[0]
+                    hit.provider = 'fullenrich'
+                  }
+                })
+              }
+            }
+            break
+          }
+        }
+      }
+    }
+  }
+
+  // Step 3: parallel fallback for remaining misses — FindyMail then IcyPeas per person
+  const afterFullEnrich = missesOf(people, results)
+
+  await Promise.all(
+    afterFullEnrich.map(async (person) => {
+      const hit = results.find((r) => r.id === person.id)!
+      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 (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
+        }
+      }
+
+      const icyRes = await callApi('POST', '/icypeas/email-search', {
+        firstname: person.first_name,
+        lastname: person.last_name,
+        domainOrCompany: person.domain,
+      })
+      if (icyRes.ok) {
+        const d = icyRes.data as Record<string, unknown>
+        const email =
+          typeof d.email === 'string' && d.email.includes('@')
+            ? d.email
+            : Array.isArray(d.emails) && typeof d.emails[0] === 'string' && d.emails[0].includes('@')
+              ? (d.emails[0] as string)
+              : null
+        if (email) {
+          hit.email = email
+          hit.provider = 'icypeas'
+        }
+      }
+    }),
+  )
+
+  const found = results.filter((r) => r.email !== null).length
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ data: { results, found, total: people.length } }, null, 2),
+      },
+    ],
+  }
+}

package/src/tools/find-influencers.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const findInfluencersName = 'find_influencers'
+
+export const findInfluencersDescription =
+  'Discover and find influencers/creators on Instagram, YouTube, TikTok, Twitch, Twitter, and OnlyFans via 2 providers (Influencers Club Similar, Influencers Club Discovery). Routes by input: handle set → lookalike search (influencers_similar) runs first; no handle → keyword/filter discovery. Filters: location, gender, type (creator/business), AI natural language search, sort. Cost: 1 credit per result returned.'
+
+export const findInfluencersSchema = {
+  platform: z.enum(['instagram', 'youtube', 'tiktok', 'twitch', 'twitter', 'onlyfans'])
+    .describe('Target platform.'),
+  limit: z.number().int().min(1).max(100).default(25)
+    .describe('Max creators to return (1–100). 1 credit per result.'),
+  page: z.number().int().min(1).default(1).optional()
+    .describe('Page number for pagination.'),
+  sort_by: z.enum(['relevancy', 'number_of_followers', 'engagement_rate']).optional(),
+  sort_order: z.enum(['asc', 'desc']).optional(),
+  ai_search: z.string().optional()
+    .describe('Natural language query e.g. "fitness influencers in NYC who post about nutrition".'),
+  location: z.array(z.string()).optional()
+    .describe('Country or city names e.g. ["United States", "New York"].'),
+  gender: z.enum(['male', 'female']).optional(),
+  type: z.enum(['creator', 'business']).optional(),
+  handle: z.string().optional()
+    .describe('Find creators similar to this handle. Routes to lookalike search. No @ prefix.'),
+}
+
+export async function findInfluencersHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('find_influencers', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/find-people.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+import { callApi } from '../client.js'
+import { getProviders } from '../registry.js'
+
+export const findPeopleName = 'find_people'
+
+export const findPeopleDescription =
+  'Find people at specific companies by job title. ' +
+  'Use this — never search_web — to find contacts, executives, or LinkedIn profiles at known companies. ' +
+  'Do not fall back to search_web when results look uncertain or LinkedIn URLs seem wrong — trust what this tool returns. ' +
+  'ALWAYS pass all companies in a single call — never loop and call once per company. ' +
+  'Set limit = (desired results per company) × (number of companies). ' +
+  'Prefer company_linkedin_urls when available — they make the search faster. Only pass company_domains when you have no LinkedIn URLs. ' +
+  'Pass job_titles EXACTLY as stated — never expand or generate variants (e.g. do NOT turn "CEO" into ["CEO", "Chief Executive Officer", "Founder"]). LeadsFactory handles fuzzy title matching internally; adding variants wastes personas and degrades results. ' +
+  'Do NOT pass seniorities unless explicitly asked — job titles alone produce better results. ' +
+  'Returns names, titles, LinkedIn URLs. Default limit: 25.'
+
+export const findPeopleSchema = {
+  company_linkedin_urls: z.array(z.string()).optional().describe('Company LinkedIn URLs (preferred over domains when available, e.g. ["https://linkedin.com/company/microsoft"])'),
+  company_domains: z.array(z.string()).optional().describe('Company domains to search (e.g. ["microsoft.com", "google.com"]). Use only when LinkedIn URLs are not available.'),
+  job_titles: z.array(z.string()).optional().describe('Target job titles (e.g. ["CEO", "VP of Sales"])'),
+  seniorities: z.array(z.string()).optional().describe('Seniority levels (e.g. ["c_suite", "vp", "director"])'),
+  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.'),
+}
+
+export async function findPeopleHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('find_people', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+
+  // 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 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 payload = apollo.mapParams(gapInput)
+        const apolloRes = await callApi(apollo.method, apollo.endpoint, payload.body, payload.queryParams)
+
+        if (apolloRes.ok && apollo.hasResult(apolloRes.data)) {
+          const merged = {
+            ...data,
+            gap_fill: {
+              provider: 'apollo',
+              domains: missedDomains,
+              ...(apolloRes.data as Record<string, unknown>),
+            },
+          }
+          return {
+            content: [{ type: 'text' as const, text: JSON.stringify({ ...result, data: merged }, null, 2) }],
+          }
+        }
+      }
+    }
+  }
+
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/find-phone.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const findPhoneName = 'find_phone'
+
+export const findPhoneDescription =
+  'Find a direct phone number for a person. Accepts a LinkedIn URL, or first+last name with company domain/name. Phone lookups are expensive (10+ credits) — use only when specifically needed.'
+
+export const findPhoneSchema = {
+  linkedin_url: z.string().url().optional().describe('LinkedIn profile URL'),
+  first_name: z.string().optional().describe('First name (required when no LinkedIn URL)'),
+  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)'),
+}
+
+const inputSchema = z
+  .object({
+    linkedin_url: z.string().url().optional(),
+    first_name: z.string().optional(),
+    last_name: z.string().optional(),
+    company_domain: z.string().optional(),
+    company_name: z.string().optional(),
+  })
+  .superRefine((val, ctx) => {
+    const hasLinkedIn = typeof val.linkedin_url === 'string' && val.linkedin_url.length > 0
+    const hasName = typeof val.first_name === 'string' && val.first_name.length > 0 &&
+      typeof val.last_name === 'string' && val.last_name.length > 0
+    const hasCompany = (typeof val.company_domain === 'string' && val.company_domain.length > 0) ||
+      (typeof val.company_name === 'string' && val.company_name.length > 0)
+    if (!hasLinkedIn && !(hasName && hasCompany)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Provide either linkedin_url or both first_name+last_name and company_domain/company_name',
+      })
+    }
+  })
+
+export async function findPhoneHandler(input: Record<string, unknown>) {
+  const validation = inputSchema.safeParse(input)
+  if (!validation.success) {
+    const msg = validation.error.issues.map((i) => i.message).join('; ')
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify({ error: msg }, null, 2) }],
+      isError: true,
+    }
+  }
+  const result = await executeWithFallback('find_phone', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/find-signals.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const findSignalsName = 'find_signals'
+
+export const findSignalsDescription =
+  'Retrieve sales intelligence signals — funding rounds, acquisitions, hiring activity, job changes, buying intent, news, and startup posts. ' +
+  'Each call targets one signal type. Two modes: ' +
+  'Company-targeted (funding | acquisition | hiring | job_change | intent): accepts companies/domains/industries/countries/since filters. ' +
+  'intent REQUIRES at least one of companies or domains. ' +
+  'Feed-style (news | startup_post): country and since only — does NOT filter by company. Passing companies/domains for these types is rejected. ' +
+  'hiring returns aggregated company-level hiring activity (e.g. "X is rapidly expanding") — for individual job postings use search_jobs instead.'
+
+export const findSignalsSchema = {
+  signal_type: z
+    .enum(['funding', 'acquisition', 'hiring', 'job_change', 'news', 'intent', 'startup_post'])
+    .describe(
+      'Signal type to retrieve. ' +
+      'Company-targeted: "funding" (fundraising rounds), "acquisition" (M&A), "hiring" (company hiring surge — not individual postings), ' +
+      '"job_change" (people who recently changed roles), "intent" (companies showing buying intent). ' +
+      'Feed-style (country/date filter only — company filter not supported): "news" (company news events), "startup_post" (Product Hunt, Hacker News, etc.)'
+    ),
+  companies: z
+    .array(z.string())
+    .optional()
+    .describe('Company names to filter signals for (e.g. ["ColdIQ", "HubSpot"]). Only used by company-targeted signal types: funding, acquisition, hiring, job_change, intent. Rejected for news and startup_post.'),
+  domains: z
+    .array(z.string())
+    .optional()
+    .describe('Company domains to filter signals for (e.g. ["coldiq.com"]). Only used by company-targeted types. Required for intent when companies is absent.'),
+  since: z
+    .string()
+    .optional()
+    .describe('Return signals after this date. ISO date format, e.g. "2026-01-01".'),
+  industries: z
+    .array(z.string())
+    .optional()
+    .describe('Industry names to filter by (e.g. ["Software", "SaaS"]). Only used by company-targeted signal types.'),
+  countries: z
+    .array(z.string())
+    .optional()
+    .describe('ISO country codes or names to filter by (e.g. ["US", "GB"]). Works for all signal types.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(25)
+    .describe('Maximum number of signals to return (1–100).'),
+}
+
+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
+
+  if (input.signal_type === 'intent' && !hasCompanies && !hasDomains) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({ error: 'intent signal_type requires at least one of: companies or domains' }, null, 2),
+      }],
+      isError: true,
+    }
+  }
+
+  if ((input.signal_type === 'news' || input.signal_type === 'startup_post') && (hasCompanies || hasDomains)) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          error: 'news and startup_post are feed-style signal types that only filter by country and since date — they do not support company filtering. Remove companies/domains, or use signal_type=intent for company-targeted intent signals.',
+        }, null, 2),
+      }],
+      isError: true,
+    }
+  }
+
+  const result = await executeWithFallback('find_signals', input)
+  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
+    const typed = result as { data?: { data?: unknown[] } }
+    if (Array.isArray(typed.data?.data)) {
+      typed.data!.data = typed.data!.data.slice(0, limit)
+    }
+  }
+
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-ads.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const searchAdsName = 'search_ads'
+
+export const searchAdsDescription =
+  'Search live ad creatives across 5 ad libraries (Google Ads Transparency, LinkedIn Ad Library, Meta Ads Library, Twitter/X Ads, Reddit Ads) — a high-signal GTM input for competitive intelligence, ICP refinement, and pitch personalization. Routes by input: domains/advertiser_ids → Google only; search_urls → LinkedIn only; bare query → Google → Meta → Twitter → Reddit waterfall. Use platform="google"|"linkedin"|"meta"|"twitter"|"reddit" to pin to one platform. All providers are async (~10–60s). Cost: ~5 credits per call (Twitter charges 1 credit per ad returned; Meta does not refund on failure).'
+
+export const searchAdsSchema = {
+  query: z.string().optional().describe('Advertiser/company name or keyword. Routes to Google→Meta→Twitter→Reddit when no platform-specific input is set.'),
+
+  domains: z.array(z.string()).optional().describe('Company domains (e.g. ["salesforce.com"]). Routes to Google Ads only.'),
+  advertiser_ids: z.array(z.string()).optional().describe('Google Ads Transparency advertiser IDs (e.g. ["AR16735076323512287233"]). Routes to Google Ads only.'),
+
+  search_urls: z.array(z.string()).optional().describe('Pre-built LinkedIn Ad Library URLs from linkedin.com/ad-library. Routes to LinkedIn only. Build at linkedin.com/ad-library/search using accountOwner/countries/dateOption filters.'),
+
+  country: z.string().optional().describe('ISO country code (2-letter for Meta/Twitter; longer accepted by Google as region). Ignored by Reddit.'),
+  max_results: z.number().int().min(1).max(200).default(25).describe('Max ads per provider call (1–200). Per-provider caps: Google 1000, LinkedIn 200, Meta 200, Twitter 100. Twitter charges 1 credit per ad returned.'),
+
+  ad_type: z.enum(['ALL', 'POLITICAL_AND_ISSUE_ADS']).optional().describe('Meta only. Defaults to ALL.'),
+
+  start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Twitter only. Date range start, YYYY-MM-DD.'),
+  end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Twitter only. Date range end, YYYY-MM-DD.'),
+
+  industry: z.enum([
+    'TECH_B2C', 'TECH_B2B', 'EDUCATION', 'ENTERTAINMENT', 'HEALTH_AND_BEAUTY',
+    'GAMING', 'EMPLOYMENT', 'RETAIL_AND_ECOMMERCE', 'AUTO', 'FINANCIAL_SERVICES',
+    'TRAVEL', 'REAL_ESTATE', 'GAMBLING_AND_FANTASY_SPORTS', 'POLITICS_AND_GOVERNMENT',
+    'CONSUMER_PACKAGED_GOODS', 'OTHER',
+  ]).optional().describe('Reddit only. Filter by industry category.'),
+  budget_category: z.enum(['LOW', 'MEDIUM', 'HIGH']).optional().describe('Reddit only.'),
+  post_type: z.enum(['IMAGE', 'VIDEO', 'TEXT']).optional().describe('Reddit only.'),
+  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.'),
+}
+
+export async function searchAdsHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_ads', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-companies.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.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.'
+
+export const searchCompaniesSchema = {
+  keywords: z.array(z.string()).optional().describe('Industry keywords or topics (e.g. ["SaaS", "fintech"])'),
+  countries: z.array(z.string()).optional().describe('2-letter ISO country codes (e.g. ["FR", "US"])'),
+  locations: z.array(z.string()).optional().describe('City/region filters as free-text strings (e.g. ["Paris, France", "San Francisco, California"]). Narrows results beyond country-level.'),
+  industries: z.array(z.string()).optional().describe('Industry names (e.g. ["Technology", "Healthcare"])'),
+  technologies: z.array(z.string()).optional().describe('Tech stack filters — routes to tech-aware providers. Pass technology names or slugs e.g. ["Salesforce", "HubSpot"].'),
+  min_employees: z.number().optional().describe('Minimum employee count'),
+  max_employees: z.number().optional().describe('Maximum employee count'),
+  min_founded_year: z.number().optional().describe('Earliest founding year'),
+  max_founded_year: z.number().optional().describe('Latest founding year'),
+  funding_stages: z.array(z.string()).optional().describe('Funding stage filters e.g. ["seed", "series_a", "series_b"]. Exact stage IDs vary by provider.'),
+  min_funding_amount: z.number().optional().describe('Minimum total funding raised (USD)'),
+  max_funding_amount: z.number().optional().describe('Maximum total funding raised (USD)'),
+  min_funding_year: z.number().optional().describe('Earliest year of last funding round'),
+  max_funding_year: z.number().optional().describe('Latest year of last funding round'),
+  min_revenue: z.number().optional().describe('Minimum estimated annual revenue (USD)'),
+  max_revenue: z.number().optional().describe('Maximum estimated annual revenue (USD)'),
+  exclude_domains: z.array(z.string()).optional().describe('Company domains to exclude from results'),
+  exclude_industries: z.array(z.string()).optional().describe('Industry names to exclude from results'),
+  exclude_countries: z.array(z.string()).optional().describe('2-letter ISO country codes to exclude from results'),
+  is_hiring: z.boolean().optional().describe('Filter to companies currently posting jobs'),
+  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)'),
+}
+
+export async function searchCompaniesHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_companies', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}