@coldiq/mcp 0.2.8 → 0.3.0

package/src/registry.ts

@@ -54,6 +54,7 @@ export type Capability =
   | 'search_jobs'
   | 'search_ads'
   | 'search_places'
+  | 'get_place_reviews'
   | 'find_influencers'
   | 'search_reddit'
   | 'search_seo'
@@ -2468,6 +2469,31 @@ const searchPlacesProviders: ProviderEntry[] = [
   },
 ]
 
+// ---------------------------------------------------------------------------
+// get_place_reviews
+// ---------------------------------------------------------------------------
+
+const getPlaceReviewsProviders: ProviderEntry[] = [
+  {
+    id: 'google_maps_reviews',
+    endpoint: '/google-maps/reviews',
+    method: 'POST',
+    priority: 1,
+    mapParams: (input) => ({
+      body: {
+        startUrls: (input.place_urls as string[]).map((url) => ({ url })),
+        maxReviews: input.max_reviews,
+        reviewsSort: input.sort,
+        language: input.language,
+      },
+    }),
+    // A completed job is a valid result even with an empty reviews array (a place
+    // may genuinely have no reviews) — only failed/timed_out should fall through.
+    hasResult: (data) => (data as { status?: string }).status === 'done',
+    async: { ..._placesSharedAsync, pollEndpoint: (id) => `/google-maps/reviews/${id}` },
+  },
+]
+
 // ---------------------------------------------------------------------------
 // find_influencers
 // ---------------------------------------------------------------------------
@@ -2543,6 +2569,22 @@ const _redditSharedAsync = {
   },
 }
 
+// A bare subreddit URL (e.g. https://www.reddit.com/r/sales or .../r/sales/)
+// makes the Apify actor ENUMERATE that subreddit's feed and ignore the search
+// keyword entirely. When the caller also passes a `query`, rewrite bare
+// subreddit URLs into in-subreddit search URLs so the keyword is actually
+// applied. Already-formed search/post URLs are left untouched.
+const _BARE_SUBREDDIT_RE = /^(https?:\/\/(?:www\.)?reddit\.com\/r\/[A-Za-z0-9_]+)\/?$/i
+
+function _toRedditSearchUrl(url: string, query: string, opts: { sort?: unknown; time?: unknown }): string {
+  const m = url.match(_BARE_SUBREDDIT_RE)
+  if (!m) return url
+  const params = new URLSearchParams({ q: query, restrict_sr: '1' })
+  if (typeof opts.sort === 'string' && opts.sort) params.set('sort', opts.sort)
+  if (typeof opts.time === 'string' && opts.time) params.set('t', opts.time)
+  return `${m[1]}/search/?${params.toString()}`
+}
+
 const searchRedditProviders: ProviderEntry[] = [
   {
     id: 'reddit',
@@ -2550,10 +2592,26 @@ const searchRedditProviders: ProviderEntry[] = [
     method: 'POST',
     priority: 1,
     isApplicable: (input) => isNonEmptyArray(input.start_urls) || typeof input.query === 'string',
-    mapParams: (input) => ({
+    mapParams: (input) => {
+      const query = typeof input.query === 'string' && input.query ? input.query : undefined
+      const rawStartUrls = input.start_urls as string[] | undefined
+      let startUrls = rawStartUrls?.map((url) => ({ url }))
+      let searchQueries = query ? [query] : undefined
+      // If a query is provided alongside start_urls, embed it into any bare
+      // subreddit URLs (which would otherwise ignore it). The keyword then lives
+      // in the URL, so drop the top-level searchQueries to avoid a conflicting
+      // global search.
+      if (query && rawStartUrls && rawStartUrls.length > 0) {
+        const rewritten = rawStartUrls.map((u) => _toRedditSearchUrl(u, query, { sort: input.sort, time: input.time }))
+        if (rewritten.some((u, i) => u !== rawStartUrls[i])) {
+          startUrls = rewritten.map((url) => ({ url }))
+          searchQueries = undefined
+        }
+      }
+      return {
       body: {
-        searchQueries: input.query ? [input.query] : undefined,
-        startUrls: (input.start_urls as string[] | undefined)?.map((url) => ({ url })),
+        searchQueries,
+        startUrls,
         searchType: input.search_type ?? 'posts',
         searchCommunityName: input.search_community_name,
         sort: input.sort,
@@ -2564,7 +2622,7 @@ const searchRedditProviders: ProviderEntry[] = [
         postDateLimit: input.post_date_limit,
         commentDateLimit: input.comment_date_limit,
       },
-    }),
+    }},
     hasResult: (data) => isNonEmptyArray((data as { items?: unknown[] }).items),
     async: {
       ..._redditSharedAsync,
@@ -3164,6 +3222,33 @@ const findSignalsProviders: ProviderEntry[] = [
     hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
   },
   {
+    // Topic-based DISCOVERY: "which companies show intent on topic X" with no
+    // company list known in advance. Routes to /theirstack/companies/search,
+    // which returns a list of companies filtered by buying-intent keyword slugs.
+    // This is the GTM-primary use case (find prospects by intent), distinct from
+    // theirstack-buying-intents which verifies intent on companies you already have.
+    id: 'theirstack-intent-discovery',
+    endpoint: '/theirstack/companies/search',
+    method: 'POST',
+    priority: 5,
+    isApplicable: (input) =>
+      input.signal_type === 'intent' &&
+      isNonEmptyArray(input.topics) &&
+      !isNonEmptyArray(input.companies) &&
+      !isNonEmptyArray(input.domains),
+    mapParams: (input) => ({
+      body: {
+        company_keyword_slug_or: input.topics,
+        ...(isNonEmptyArray(input.industries) && { industry_or: input.industries }),
+        ...(isNonEmptyArray(input.countries) && { company_country_code_or: input.countries }),
+        limit: Math.min((input.limit as number | undefined) ?? 25, 100),
+        include_total_results: true,
+      },
+    }),
+    hasResult: (data) => isNonEmptyArray((data as Record<string, unknown>).data),
+  },
+  {
+    // Verify intent on KNOWN companies/domains.
     id: 'theirstack-buying-intents',
     endpoint: '/theirstack/companies/buying_intents',
     method: 'POST',
@@ -3262,6 +3347,7 @@ const registry: Record<Capability, ProviderEntry[]> = {
   search_jobs: searchJobsProviders,
   search_ads: searchAdsProviders,
   search_places: searchPlacesProviders,
+  get_place_reviews: getPlaceReviewsProviders,
   find_influencers: findInfluencersProviders,
   search_reddit: searchRedditProviders,
   search_seo: searchSeoProviders,

package/src/tools/extract-post-engagement.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod'
+import { callApi } from '../client.js'
+
+export const extractPostEngagementName = 'extract_post_engagement'
+
+export const extractPostEngagementDescription =
+  'Extract the people who engaged with a LinkedIn post — commenters and/or reactors — as a deduplicated list of contacts (name, profile URL, headline). ' +
+  'Use this for social-signal prospecting: pull everyone who engaged with a viral post, then chain the results into enrich_person / find_email to get roles and work emails. ' +
+  'Runs an async extraction job (typically ~30–120s) and returns once the people are ready. Costs 10 credits per post.'
+
+export const extractPostEngagementSchema = {
+  post_url: z
+    .string()
+    .url()
+    .describe('LinkedIn post URL to extract engagement from (e.g. "https://www.linkedin.com/feed/update/urn:li:activity:7234567890123456789" or a /posts/ permalink).'),
+  type: z
+    .enum(['comments', 'reactions', 'both'])
+    .default('both')
+    .describe('Which engagement to extract: "comments" (people who commented), "reactions" (people who reacted), or "both" (default — deduplicated across both).'),
+  include_replies: z
+    .boolean()
+    .optional()
+    .describe('When extracting comments, also include people who replied to comments. Defaults to true upstream.'),
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function errorResult(error: string, extra?: Record<string, unknown>) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify({ error, ...extra }) }],
+    isError: true,
+  }
+}
+
+function extractErrorMessage(data: unknown): string | undefined {
+  if (data && typeof data === 'object' && 'error' in data) {
+    const e = (data as Record<string, unknown>).error
+    return typeof e === 'string' ? e : JSON.stringify(e)
+  }
+  return undefined
+}
+
+export async function extractPostEngagementHandler(input: Record<string, unknown>) {
+  const postUrl = input.post_url as string
+  const type = (input.type as 'comments' | 'reactions' | 'both' | undefined) ?? 'both'
+  const includeReplies = input.include_replies as boolean | undefined
+
+  const dataTypes =
+    type === 'comments' ? ['comment'] : type === 'reactions' ? ['reaction'] : ['comment', 'reaction']
+
+  // Step 1 — create the extraction task. Billing (10 credits) happens here.
+  const createRes = await callApi('POST', '/jungler/workbooks', {
+    post_url: postUrl,
+    data_types: dataTypes,
+  })
+  if (!createRes.ok) {
+    return errorResult(extractErrorMessage(createRes.data) ?? `Failed to start extraction (status ${createRes.status})`)
+  }
+  const createData = createRes.data as { task_id?: string }
+  const taskId = createData.task_id
+  if (!taskId) {
+    return errorResult('Extraction job did not return a task id')
+  }
+  // Credit headers are emitted on the create call (the only billed step).
+  const creditsCharged = Number(createRes.headers['x-coldiq-credits-charged'])
+  const creditsRemaining = Number(createRes.headers['x-coldiq-credits-remaining'])
+
+  // Step 2 — poll task status until it resolves. The status endpoint is free, so
+  // polling does not bill; only the create call above charged credits.
+  const pollIntervalMs = parseInt(process.env.COLDIQ_ENGAGEMENT_POLL_MS ?? '2000', 10)
+  const timeoutMs = parseInt(process.env.COLDIQ_ENGAGEMENT_TIMEOUT_MS ?? '180000', 10)
+  const maxPollErrors = 3
+  const deadline = Date.now() + timeoutMs
+
+  let workbookId: string | undefined
+  let consecutivePollErrors = 0
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs)
+    const statusRes = await callApi('GET', `/jungler/tasks/${taskId}/status`)
+    if (!statusRes.ok) {
+      consecutivePollErrors++
+      if (consecutivePollErrors >= maxPollErrors) {
+        return errorResult('Could not read extraction status — please retry', { post_url: postUrl })
+      }
+      continue
+    }
+    consecutivePollErrors = 0
+    const status = (statusRes.data as { status?: string; workbook_id?: string }).status
+    if (status === 'success') {
+      workbookId = (statusRes.data as { workbook_id?: string }).workbook_id
+      break
+    }
+    if (status === 'failure') {
+      return errorResult('Engagement extraction failed upstream — the post may be private, deleted, or have no engagement', { post_url: postUrl })
+    }
+  }
+
+  if (!workbookId) {
+    return errorResult(`Engagement extraction did not complete within ${Math.round(timeoutMs / 1000)}s — try again shortly`, { post_url: postUrl })
+  }
+
+  // Step 3 — fetch the deduplicated people. activity_filter narrows to commenters
+  // or reactors; omitted for "both" so the upstream returns all unique contacts.
+  const queryParams: Record<string, string> = {}
+  if (type === 'comments') queryParams.activity_filter = 'commenters'
+  else if (type === 'reactions') queryParams.activity_filter = 'reactors'
+  if (includeReplies !== undefined) queryParams.include_replies = String(includeReplies)
+
+  const contactsRes = await callApi(
+    'GET',
+    `/jungler/workbooks/${workbookId}/contacts`,
+    undefined,
+    Object.keys(queryParams).length > 0 ? queryParams : undefined,
+  )
+  if (!contactsRes.ok) {
+    return errorResult(extractErrorMessage(contactsRes.data) ?? 'Failed to fetch extracted people', { post_url: postUrl })
+  }
+
+  const meta: Record<string, unknown> = {}
+  if (Number.isFinite(creditsCharged)) meta.credits_charged = creditsCharged
+  if (Number.isFinite(creditsRemaining)) meta.credits_remaining = creditsRemaining
+
+  return {
+    content: [{
+      type: 'text' as const,
+      text: JSON.stringify({
+        data: { post_url: postUrl, type, people: contactsRes.data },
+        _meta: meta,
+      }),
+    }],
+  }
+}

package/src/tools/find-influencers.ts

@@ -5,7 +5,8 @@ import { resolvePreferredProviders, getProvidersForCapability } from '../utils/p
 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.'
+  '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. ' +
+  'LIMITATIONS: LinkedIn is not a supported platform (the underlying creator index has no LinkedIn coverage) — for B2B/LinkedIn prospecting use extract_post_engagement to pull engagers off a specific LinkedIn post instead. There is no follower-count range filter; to bias toward a follower tier, set sort_by="number_of_followers" and filter the returned list client-side.'
 
 export const findInfluencersSchema = {
   platform: z.enum(['instagram', 'youtube', 'tiktok', 'twitch', 'twitter', 'onlyfans'])

package/src/tools/find-signals.ts

@@ -9,7 +9,7 @@ export const findSignalsDescription =
   'Each call targets one signal type. Two modes: ' +
   'Company-targeted (funding | acquisition | hiring | job_change | intent): accepts companies/domains/industries/countries/since filters. ' +
   'funding additionally accepts `round_type` (e.g. ["Series A", "Seed"]). ' +
-  'intent REQUIRES at least one of companies or domains and additionally accepts `topics` (e.g. ["sales-automation"]) to narrow by intent keyword. ' +
+  'intent has two modes: (a) DISCOVERY — pass `topics` (e.g. ["sales-automation"]) with no companies/domains to find companies showing intent on those topics; (b) VERIFY — pass companies/domains to check intent on known companies. Requires topics OR companies/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 individual job postings with company context (title, location, descriptionText, company industries) — for richer job-board queries with description/seniority/easy-apply filters use search_jobs instead.'
 
@@ -19,7 +19,7 @@ export const findSignalsSchema = {
     .describe(
       'Signal type to retrieve. ' +
       'Company-targeted: "funding" (fundraising rounds), "acquisition" (M&A), "hiring" (individual job postings indexed by Signalbase, with company context), ' +
-      '"job_change" (people who recently changed roles), "intent" (companies showing buying intent). ' +
+      '"job_change" (people who recently changed roles), "intent" (companies showing buying intent — discover by `topics` or verify on known companies/domains). ' +
       'Feed-style (country/date filter only — company filter not supported): "news" (company news events), "startup_post" (Product Hunt, Hacker News, etc.)'
     ),
   companies: z
@@ -29,15 +29,15 @@ export const findSignalsSchema = {
   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.'),
+    .describe('Company domains to filter signals for (e.g. ["coldiq.com"]). Only used by company-targeted types. For intent VERIFY mode: pass companies or domains. For intent DISCOVERY mode: omit both and pass topics instead.'),
   since: z
     .string()
     .optional()
-    .describe('Return signals after this date. ISO date format, e.g. "2026-01-01".'),
+    .describe('Return signals after this date. ISO date format, e.g. "2026-01-01". Honored by funding, acquisition, hiring, job_change, and startup_post. NOT supported for intent (TheirStack has no date filter on intent) — passing it has no effect.'),
   industries: z
     .array(z.string())
     .optional()
-    .describe('Industry names to filter by (e.g. ["Software", "SaaS"]). Forwarded to upstream for funding and acquisition. For hiring, filtered client-side against each row\'s `industries` field (case-insensitive substring match). Ignored for job_change, intent, news, startup_post (those signal types have no industry data to filter on).'),
+    .describe('Industry names to filter by (e.g. ["Software", "SaaS"]). Forwarded to upstream for funding and acquisition. For hiring, filtered client-side against each row\'s `industries` field (case-insensitive substring match); Signalbase uses coarse labels (e.g. "Financial Services"), so prefer those over narrow terms like "Fintech" — if nothing matches, rows are returned UNFILTERED with a `_industry_filter` note rather than an empty set. For intent DISCOVERY, forwarded to TheirStack as `industry_or`. Ignored for job_change, news, startup_post.'),
   countries: z
     .array(z.string())
     .optional()
@@ -49,7 +49,7 @@ export const findSignalsSchema = {
   topics: z
     .array(z.string())
     .optional()
-    .describe('Intent topic / keyword slugs (e.g. ["sales-automation", "lead-generation"]). Only honored by signal_type=intent (forwarded to TheirStack as `keyword_slug_or`). Note: topics is supplemental — TheirStack still requires at least one of `companies` or `domains`, so topics narrows an existing company-targeted search rather than enabling pure topic discovery.'),
+    .describe('Intent topic / keyword slugs (e.g. ["sales-automation", "lead-generation"]). Only honored by signal_type=intent. DISCOVERY mode: pass topics WITHOUT companies/domains to find companies showing intent on these topics (forwarded to TheirStack company search as `company_keyword_slug_or`, returns a company list). VERIFY mode: pass topics WITH companies/domains to narrow intent results for those known companies (forwarded as `keyword_slug_or`).'),
   limit: z
     .number()
     .int()
@@ -65,11 +65,13 @@ export async function findSignalsHandler(input: Record<string, unknown>) {
   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 (restInput.signal_type === 'intent' && !hasCompanies && !hasDomains) {
+  const hasTopics = Array.isArray(restInput.topics) && (restInput.topics as unknown[]).length > 0
+
+  if (restInput.signal_type === 'intent' && !hasCompanies && !hasDomains && !hasTopics) {
     return {
       content: [{
         type: 'text' as const,
-        text: JSON.stringify({ error: 'intent signal_type requires at least one of: companies or domains' }),
+        text: JSON.stringify({ error: 'intent signal_type requires at least one of: topics (to discover companies by intent topic), or companies/domains (to verify intent on known companies)' }),
       }],
       isError: true,
     }
@@ -110,21 +112,36 @@ export async function findSignalsHandler(input: Record<string, unknown>) {
   // `industries` param would otherwise be silently dropped. Filter client-side:
   // each hiring row carries an `industries` string (e.g. "Law Practice and Legal
   // Services") which we substring-match against the user-supplied list.
+  //
+  // Non-destructive fallback: Signalbase has no industry facet and tags rows with
+  // coarse labels (e.g. "Financial Services"), so a user term like "Fintech" can
+  // match nothing even when relevant rows exist. Rather than return a misleading
+  // empty set (which reads as "no companies are hiring"), when the filter would
+  // drop every row we keep the unfiltered rows and attach a note explaining that
+  // the industry filter matched nothing.
   if (restInput.signal_type === 'hiring' && Array.isArray(restInput.industries) && restInput.industries.length > 0) {
     const wanted = (restInput.industries as unknown[])
       .map((s) => (typeof s === 'string' ? s.toLowerCase() : ''))
       .filter((s) => s.length > 0)
     if (wanted.length > 0) {
-      const typed = result as { data?: { data?: unknown[] } }
+      const typed = result as { data?: { data?: unknown[]; _industry_filter?: string } }
       const rows = typed.data?.data
-      if (Array.isArray(rows)) {
-        typed.data!.data = rows.filter((row) => {
+      if (Array.isArray(rows) && rows.length > 0) {
+        const filtered = rows.filter((row) => {
           if (!row || typeof row !== 'object') return false
           const industriesField = (row as Record<string, unknown>).industries
           if (typeof industriesField !== 'string' || industriesField.length === 0) return false
           const haystack = industriesField.toLowerCase()
           return wanted.some((needle) => haystack.includes(needle))
         })
+        if (filtered.length > 0) {
+          typed.data!.data = filtered
+        } else {
+          typed.data!._industry_filter =
+            `No hiring rows matched industries [${(restInput.industries as string[]).join(', ')}]. ` +
+            'Signalbase tags hiring rows with coarse industry labels (e.g. "Financial Services"), so a narrow term may match nothing — results are returned UNFILTERED. ' +
+            'Narrow with countries or a broader/more exact industry label (e.g. "Financial Services" instead of "Fintech").'
+        }
       }
     }
   }

package/src/tools/get-place-reviews.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+
+export const getPlaceReviewsName = 'get_place_reviews'
+
+export const getPlaceReviewsDescription =
+  'Fetch Google Maps reviews for one or more places. Pass the Google Maps place URLs (from search_places results, the `url` field) and get back each place\'s reviews — useful for reputation management, local-services prospecting, and surfacing negative-review signals. ' +
+  'search_places returns place listings WITHOUT review text; use this tool to get the actual review content. ' +
+  'Runs an async job (~30–120s). Cost: 1 credit per review returned.'
+
+export const getPlaceReviewsSchema = {
+  place_urls: z
+    .array(z.string().url())
+    .min(1)
+    .max(10)
+    .describe('Google Maps place URLs to scrape reviews from (1–10). Use the `url` field from search_places results, or a maps.google.com place/search URL.'),
+  max_reviews: z
+    .number()
+    .int()
+    .min(1)
+    .max(300)
+    .optional()
+    .describe('Maximum reviews to fetch per place (default 5, max 300). Each returned review costs 1 credit, so keep this tight.'),
+  sort: z
+    .enum(['mostRelevant', 'newest', 'highestRanking', 'lowestRanking'])
+    .optional()
+    .describe('Review sort order. Use "newest" for recent reviews or "lowestRanking" to surface negative reviews first. Default "mostRelevant".'),
+  language: z
+    .string()
+    .optional()
+    .describe('ISO 639-1 language code to filter reviews by language (e.g. "en", "fr").'),
+  use_providers: z
+    .array(z.string())
+    .optional()
+    .describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick — recommended. Available providers: ${getProvidersForCapability('get_place_reviews').join(', ')}. Provider names are matched fuzzily.`),
+}
+
+export async function getPlaceReviewsHandler(input: Record<string, unknown>) {
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('get_place_reviews', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
+  }
+  const result = await executeWithFallback('get_place_reviews', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+}

package/src/tools/search-ads.ts

@@ -5,7 +5,7 @@ import { resolvePreferredProviders, getProvidersForCapability } from '../utils/p
 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).'
+  '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). Credits are fully refunded when a run returns zero ads. NOTE: Google Ads creatives return image URLs + creative IDs, not ad copy text — open the image URLs to read the ad. There is no "currently running only" filter; results can span past campaigns.'
 
 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.'),

package/src/tools/search-places.ts

@@ -5,7 +5,7 @@ import { resolvePreferredProviders, getProvidersForCapability } from '../utils/p
 export const searchPlacesName = 'search_places'
 
 export const searchPlacesDescription =
-  'Search local businesses and places via 2 providers (Openmart Search, Google Maps Scraper) — useful for territory mapping, local-services prospecting, restaurant/retail/vertical research. Routes by input: structured filters or country in {US,CA,AU,PR,NZ} → Openmart (sync, ~1s) first, then Google Maps Scraper (async, ~30–120s) as fallback or for global coverage. Use provider="openmart"|"google_maps" to pin to one. Cost: 1 credit per place returned (both providers).'
+  'Search local businesses and places via 2 providers (Openmart Search, Google Maps Scraper) — useful for territory mapping, local-services prospecting, restaurant/retail/vertical research. Routes by input: structured filters or country in {US,CA,AU,PR,NZ} → Openmart (sync, ~1s) first, then Google Maps Scraper (async, ~30–120s) as fallback or for global coverage. Use provider="openmart"|"google_maps" to pin to one. Cost: 1 credit per place returned (both providers). Results do NOT include review text — to fetch a place\'s reviews, pass its `url` to get_place_reviews.'
 
 export const searchPlacesSchema = {
   query: z.string().optional().describe('Free-text query (e.g. "coffee shops in Brooklyn", "law firm New York"). Used by both providers.'),
@@ -90,11 +90,30 @@ export async function searchPlacesHandler(input: Record<string, unknown>) {
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
   }
-  result.data = applyPlaceFilters(result.data, {
+  const filters = {
     minRating: asNumber(restInput.min_overall_rating),
     maxRating: asNumber(restInput.max_overall_rating),
     minReviews: asNumber(restInput.min_total_reviews),
     maxReviews: asNumber(restInput.max_total_reviews),
-  })
+  }
+  const scraped = placesCount(result.data)
+  result.data = applyPlaceFilters(result.data, filters)
+  const matched = placesCount(result.data)
+  // Google Maps bills per place scraped upstream (what ColdIQ pays the provider),
+  // but rating/review filters are applied here client-side. When the filter trims
+  // the set, make the gap explicit so the credit charge isn't surprising.
+  if (scraped !== undefined && matched !== undefined && matched < scraped) {
+    ;(result._meta as Record<string, unknown>).filtered = {
+      scraped,
+      matched,
+      note: 'Rating/review filters are applied client-side. You are billed per place scraped upstream (scraped), not per matched place.',
+    }
+  }
   return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
 }
+
+function placesCount(data: unknown): number | undefined {
+  if (!data || typeof data !== 'object') return undefined
+  const places = (data as Record<string, unknown>).places
+  return Array.isArray(places) ? places.length : undefined
+}

package/src/tools/search-reddit.ts

@@ -11,7 +11,7 @@ export const searchRedditSchema = {
   start_urls: z.array(z.string().url()).max(25).optional()
     .describe('Reddit URLs to scrape (subreddit, post, user, or search URL). Up to 25. Provide this and/or query. Example: ["https://www.reddit.com/r/sales/"]'),
   query: z.string().optional()
-    .describe('Keyword search query run across Reddit e.g. "best CRM for startups". Provide this and/or start_urls.'),
+    .describe('Keyword search query e.g. "best CRM for startups". Provide this and/or start_urls. When combined with a bare subreddit start_url (e.g. ".../r/sales/"), the query is applied as an in-subreddit search so only matching posts are returned (a bare subreddit URL alone would otherwise return its whole feed, ignoring the keyword).'),
   search_type: z.enum(['posts', 'comments', 'communities', 'users']).default('posts')
     .describe('What the search query returns: posts, comments, communities, or users.'),
   search_community_name: z.string().optional()

package/tests/registry-find-signals.test.ts

@@ -309,6 +309,72 @@ describe('signalbase-job-change', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// theirstack-intent-discovery
+// ---------------------------------------------------------------------------
+
+describe('theirstack-intent-discovery', () => {
+  const p = () => get('theirstack-intent-discovery')
+
+  it('routes to the company search endpoint', () => {
+    expect(p().endpoint).toBe('/theirstack/companies/search')
+    expect(p().method).toBe('POST')
+  })
+
+  it('isApplicable: true for intent with topics and no companies/domains', () => {
+    expect(p().isApplicable!({ signal_type: 'intent', topics: ['sales-automation'] })).toBe(true)
+  })
+
+  it('isApplicable: false when companies present (verify mode handles that)', () => {
+    expect(p().isApplicable!({ signal_type: 'intent', topics: ['sales-automation'], companies: ['ColdIQ'] })).toBe(false)
+  })
+
+  it('isApplicable: false when domains present', () => {
+    expect(p().isApplicable!({ signal_type: 'intent', topics: ['sales-automation'], domains: ['coldiq.com'] })).toBe(false)
+  })
+
+  it('isApplicable: false when no topics', () => {
+    expect(p().isApplicable!({ signal_type: 'intent' })).toBe(false)
+  })
+
+  it('isApplicable: false for other signal types', () => {
+    expect(p().isApplicable!({ signal_type: 'funding', topics: ['x'] })).toBe(false)
+  })
+
+  it('mapParams forwards topics as company_keyword_slug_or', () => {
+    const result = p().mapParams({ signal_type: 'intent', topics: ['sales-automation', 'lead-generation'], limit: 20 })
+    const body = result.body as Record<string, unknown>
+    expect(body.company_keyword_slug_or).toEqual(['sales-automation', 'lead-generation'])
+    expect(body.limit).toBe(20)
+    expect(body.include_total_results).toBe(true)
+  })
+
+  it('mapParams forwards industries and countries when present', () => {
+    const result = p().mapParams({
+      signal_type: 'intent',
+      topics: ['sales-automation'],
+      industries: ['Software'],
+      countries: ['US', 'GB'],
+    })
+    const body = result.body as Record<string, unknown>
+    expect(body.industry_or).toEqual(['Software'])
+    expect(body.company_country_code_or).toEqual(['US', 'GB'])
+  })
+
+  it('mapParams caps limit at 100', () => {
+    const result = p().mapParams({ signal_type: 'intent', topics: ['x'], limit: 999 })
+    expect((result.body as Record<string, unknown>).limit).toBe(100)
+  })
+
+  it('hasResult: true when data non-empty', () => {
+    expect(p().hasResult({ data: [{ name: 'ColdIQ' }] })).toBe(true)
+  })
+
+  it('hasResult: false on empty data', () => {
+    expect(p().hasResult({ data: [] })).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // theirstack-buying-intents
 // ---------------------------------------------------------------------------