@coldiq/mcp 0.3.12 → 0.3.13

package/src/tools/find-phone.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findPhoneName = 'find_phone'
 
@@ -16,45 +16,7 @@ export const findPhoneSchema = {
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_phone').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
-const inputSchema = z
-  .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 { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('find_phone', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const validation = inputSchema.safeParse(restInput)
-  if (!validation.success) {
-    const msg = validation.error.issues.map((i) => i.message).join('; ')
-    return {
-      content: [{ type: 'text' as const, text: JSON.stringify({ error: msg }) }],
-      isError: true,
-    }
-  }
-  const result = await executeWithFallback('find_phone', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  // MCP schema predates the verb: `company_domain` → the verb's `domain`.
+  return callVerb('/phone/find', input, { remap: { company_domain: 'domain' } })
 }

package/src/tools/find-signals.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findSignalsName = 'find_signals'
 
@@ -61,90 +61,5 @@ export const findSignalsSchema = {
 }
 
 export async function findSignalsHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const hasCompanies = Array.isArray(restInput.companies) && (restInput.companies as unknown[]).length > 0
-  const hasDomains = Array.isArray(restInput.domains) && (restInput.domains as unknown[]).length > 0
-
-  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: topics (to discover companies by intent topic), or companies/domains (to verify intent on known companies)' }),
-      }],
-      isError: true,
-    }
-  }
-
-  if ((restInput.signal_type === 'news' || restInput.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.',
-        }),
-      }],
-      isError: true,
-    }
-  }
-
-  const resolved = resolvePreferredProviders('find_signals', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-
-  const result = await executeWithFallback('find_signals', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-
-  // buying_intents upstream has no limit param — truncate to requested limit
-  if (restInput.signal_type === 'intent') {
-    const limit = typeof restInput.limit === 'number' ? restInput.limit : 25
-    const typed = result as { data?: { data?: unknown[] } }
-    if (Array.isArray(typed.data?.data)) {
-      typed.data!.data = typed.data!.data.slice(0, limit)
-    }
-  }
-
-  // Signalbase /hiring-signals does not accept an industry filter upstream, so the
-  // `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[]; _industry_filter?: string } }
-      const rows = typed.data?.data
-      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").'
-        }
-      }
-    }
-  }
-
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/signals/find', input)
 }

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

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const getPlaceReviewsName = 'get_place_reviews'
 
@@ -37,14 +37,5 @@ export const getPlaceReviewsSchema = {
 }
 
 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) }] }
+  return callVerb('/places/reviews', input)
 }

package/src/tools/search-ads.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchAdsName = 'search_ads'
 
@@ -38,14 +38,5 @@ export const searchAdsSchema = {
 }
 
 export async function searchAdsHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('search_ads', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_ads', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/ads/search', input)
 }

package/src/tools/search-companies.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
-import { compactCompaniesPayload } from '../utils/compact-companies.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchCompaniesName = 'search_companies'
 
@@ -38,24 +37,5 @@ export const searchCompaniesSchema = {
 }
 
 export async function searchCompaniesHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, fields: rawFields, ...restInput } = input
-  const fields: 'compact' | 'verbose' = rawFields === 'verbose' ? 'verbose' : 'compact'
-  const resolved = resolvePreferredProviders('search_companies', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_companies', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  // Surface the upstream match count (e.g. Apollo's pagination.total_entries) as the
-  // total-addressable-market signal, so clients see "matched N, returned M".
-  const totalEntries = (result.data as { pagination?: { total_entries?: unknown } })?.pagination?.total_entries
-  if (typeof totalEntries === 'number') {
-    ;(result._meta as Record<string, unknown>).total_entries = totalEntries
-  }
-  const payload = fields === 'compact'
-    ? { ...result, data: compactCompaniesPayload(result.data) }
-    : result
-  return { content: [{ type: 'text' as const, text: JSON.stringify(payload) }] }
+  return callVerb('/companies/search', input)
 }

package/src/tools/search-jobs.ts

@@ -1,16 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
-
-const _CAREER_SITE_ONLY = ['ats_slugs', 'exclude_ats_slugs', 'company_domains', 'exclude_company_domains']
-const _LINKEDIN_ONLY = ['seniority_levels', 'industries', 'organization_slugs', 'exclude_organization_slugs', 'min_employees', 'max_employees', 'easy_apply_only', 'exclude_easy_apply']
-
-function _isFilterSet(input: Record<string, unknown>, keys: string[]): boolean {
-  return keys.some((k) => {
-    const v = input[k]
-    return !!v && (!Array.isArray(v) || v.length > 0)
-  })
-}
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchJobsName = 'search_jobs'
 
@@ -59,22 +49,5 @@ export const searchJobsSchema = {
 }
 
 export async function searchJobsHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  if (_isFilterSet(restInput, _CAREER_SITE_ONLY) && _isFilterSet(restInput, _LINKEDIN_ONLY)) {
-    const err = {
-      error:
-        'Contradictory filters: ATS/domain filters (ats_slugs, company_domains) are Career Site only, ' +
-        'while seniority/industry/employee filters are LinkedIn only. Remove one set.',
-    }
-    return { content: [{ type: 'text' as const, text: JSON.stringify(err) }], isError: true }
-  }
-  const resolved = resolvePreferredProviders('search_jobs', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_jobs', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/jobs/search', input)
 }

package/src/tools/search-places.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchPlacesName = 'search_places'
 
@@ -45,75 +45,8 @@ export const searchPlacesSchema = {
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('search_places').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
-function asNumber(v: unknown): number | undefined {
-  return typeof v === 'number' && Number.isFinite(v) ? v : undefined
-}
-
-// Google Maps Scraper does not honor min/max rating or review-count filters
-// upstream, so the params would otherwise be silently dropped. Filter client-side
-// against the `totalScore` (rating) and `reviewsCount` fields on each place.
-// Applied to all routes for consistency; on Openmart this is a no-op since the
-// filters were already enforced upstream and Openmart returns `{ data: [...] }`
-// rather than `{ places: [...] }`.
-// Pure: returns a new object instead of mutating its argument.
-export function applyPlaceFilters(
-  data: unknown,
-  filters: { minRating?: number; maxRating?: number; minReviews?: number; maxReviews?: number },
-): unknown {
-  const { minRating, maxRating, minReviews, maxReviews } = filters
-  if (minRating === undefined && maxRating === undefined && minReviews === undefined && maxReviews === undefined) return data
-  if (!data || typeof data !== 'object') return data
-  const d = data as Record<string, unknown>
-  const places = d.places
-  if (!Array.isArray(places)) return data
-  const filtered = places.filter((place) => {
-    if (!place || typeof place !== 'object') return false
-    const p = place as Record<string, unknown>
-    const rating = asNumber(p.totalScore)
-    const reviews = asNumber(p.reviewsCount)
-    if (minRating !== undefined && (rating === undefined || rating < minRating)) return false
-    if (maxRating !== undefined && (rating === undefined || rating > maxRating)) return false
-    if (minReviews !== undefined && (reviews === undefined || reviews < minReviews)) return false
-    if (maxReviews !== undefined && (reviews === undefined || reviews > maxReviews)) return false
-    return true
-  })
-  return { ...d, places: filtered }
-}
-
 export async function searchPlacesHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('search_places', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_places', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  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
+  // The MCP `provider` (openmart|google_maps) is a place-source pin; the verb has
+  // no such input field, so route it through the envelope's provider list.
+  return callVerb('/places/search', input, { providerFromField: 'provider' })
 }

package/src/tools/search-reddit.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchRedditName = 'search_reddit'
 
@@ -34,14 +34,5 @@ export const searchRedditSchema = {
 }
 
 export async function searchRedditHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('search_reddit', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_reddit', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/reddit/search', input)
 }

package/src/tools/search-seo.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchSeoName = 'search_seo'
 
@@ -53,14 +53,5 @@ export const searchSeoSchema = {
 }
 
 export async function searchSeoHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('search_seo', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_seo', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/seo/search', input)
 }

package/src/tools/search-web.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const searchWebName = 'search_web'
 
@@ -19,14 +19,5 @@ export const searchWebSchema = {
 }
 
 export async function searchWebHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('search_web', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('search_web', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/web/search', input)
 }

package/src/tools/verify-email.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
-import { executeWithFallback, isExecutionError } from '../executor.js'
-import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
+import { callVerb } from '../verb-client.js'
+import { getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const verifyEmailName = 'verify_email'
 
@@ -12,79 +12,6 @@ export const verifyEmailSchema = {
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('verify_email').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
-type NormalizedStatus = 'valid' | 'invalid' | 'catch_all' | 'risky' | 'disposable' | 'unknown'
-
-const STATUS_ALIASES: Record<string, NormalizedStatus> = {
-  valid: 'valid',
-  deliverable: 'valid',
-  ok: 'valid',
-  invalid: 'invalid',
-  undeliverable: 'invalid',
-  bounce: 'invalid',
-  bounced: 'invalid',
-  catch_all: 'catch_all',
-  catchall: 'catch_all',
-  'catch-all': 'catch_all',
-  accept_all: 'catch_all',
-  acceptall: 'catch_all',
-  risky: 'risky',
-  disposable: 'disposable',
-  unknown: 'unknown',
-}
-
-function normalizeStatus(raw: unknown): NormalizedStatus {
-  if (typeof raw !== 'string' || raw.length === 0) return 'unknown'
-  return STATUS_ALIASES[raw.toLowerCase()] ?? 'unknown'
-}
-
-// Provider responses are heterogeneous. We surface a single `status` field on the
-// payload while leaving the raw upstream fields untouched so callers that already
-// depend on them keep working.
-export function addNormalizedStatus(data: unknown, providerId: string): unknown {
-  if (!data || typeof data !== 'object' || Array.isArray(data)) return data
-  const d = { ...(data as Record<string, unknown>) }
-
-  // If the response already carries a status string, normalize it and stop.
-  if (typeof d.status === 'string') {
-    d.status = normalizeStatus(d.status)
-    return d
-  }
-
-  if (providerId === 'findymail') {
-    // Findymail's /api/verify returns { email, verified: boolean, provider } — no
-    // catch_all/unknown distinction. Map the boolean to valid/invalid only.
-    d.status = d.verified === true ? 'valid' : 'invalid'
-    return d
-  }
-
-  if (providerId === 'icypeas') {
-    const item = d.item as Record<string, unknown> | undefined
-    d.status = normalizeStatus(item?.status)
-    return d
-  }
-
-  if (providerId === 'linkupapi-validate') {
-    // LinkupAPI shapes vary; accept any of the common signal fields.
-    const truthy = d.verified === true || d.valid === true || d.result === 'valid'
-    d.status = truthy ? 'valid' : normalizeStatus(d.result ?? d.valid ?? d.verified)
-    return d
-  }
-
-  // Unknown provider — leave the original payload alone and flag the gap.
-  d.status = 'unknown'
-  return d
-}
-
 export async function verifyEmailHandler(input: Record<string, unknown>) {
-  const { use_providers: rawUseProviders, ...restInput } = input
-  const resolved = resolvePreferredProviders('verify_email', restInput, rawUseProviders)
-  if (!resolved.ok) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error) }], isError: true }
-  }
-  const result = await executeWithFallback('verify_email', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
-  if (isExecutionError(result)) {
-    return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], isError: true }
-  }
-  result.data = addNormalizedStatus(result.data, result._meta.provider)
-  return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] }
+  return callVerb('/email/verify', input)
 }

package/src/verb-client.ts

@@ -0,0 +1,93 @@
+import { callApi } from './client.js'
+
+/**
+ * Thin client for the deployed /v1 GTM verb endpoints.
+ *
+ * Each verb takes an envelope `{ input: {...filters}, provider?, fields?, reveal? }`
+ * (or `{ inputs: [...] }` for bulk) and returns `{ data, _meta }` (or `{ results }`
+ * for bulk, or `{ error, providers_tried }` on failure with a 4xx/5xx status).
+ *
+ * The MCP tool schemas expose `use_providers` (the ordered provider list) and the
+ * optional `fields` / `reveal` knobs alongside the verb's filter fields. This helper
+ * splits those out and maps everything else into the verb envelope, so each tool
+ * handler collapses to a single delegating call.
+ *
+ * A few MCP tool schemas predate the verb input schemas and need light mapping:
+ *   - `remap`: rename input keys before building the envelope (e.g. find_phone's
+ *     `company_domain` → the verb's `domain`).
+ *   - `providerFromField`: a tool-specific provider-pin field (e.g. search_places'
+ *     `provider: openmart|google_maps`) → the envelope's provider list.
+ *   - `reattachIdField`: bulk verbs return `results` positionally with no echo of the
+ *     per-item correlation id, so re-attach `input[bulkField][i][id]` onto `results[i]`
+ *     so callers can still match results back.
+ */
+export interface CallVerbOptions {
+  bulkField?: string
+  remap?: Record<string, string>
+  providerFromField?: string
+  reattachIdField?: string
+}
+
+export async function callVerb(
+  verbPath: string,
+  input: Record<string, unknown>,
+  opts?: CallVerbOptions,
+): Promise<{ content: [{ type: 'text'; text: string }]; isError?: boolean }> {
+  // 1. Rename any schema-drift field names before splitting the envelope.
+  let work: Record<string, unknown> = input
+  if (opts?.remap) {
+    work = {}
+    for (const [k, v] of Object.entries(input)) {
+      work[opts.remap[k] ?? k] = v
+    }
+  }
+
+  const { use_providers, fields, reveal, ...rest } = work
+
+  // 2. Resolve the provider pin: explicit use_providers wins; otherwise a
+  //    tool-specific provider field (e.g. search_places `provider`).
+  let providerPin: string[] | undefined =
+    Array.isArray(use_providers) && use_providers.length ? (use_providers as string[]) : undefined
+  if (opts?.providerFromField && rest[opts.providerFromField] !== undefined) {
+    const v = rest[opts.providerFromField]
+    delete rest[opts.providerFromField]
+    if (!providerPin && typeof v === 'string' && v) providerPin = [v]
+  }
+
+  // 3. Build the envelope (single vs bulk).
+  let envelope: Record<string, unknown>
+  let list: Array<Record<string, unknown>> | undefined
+  if (opts?.bulkField) {
+    const { [opts.bulkField]: l, ...siblings } = rest
+    list = Array.isArray(l) ? (l as Array<Record<string, unknown>>) : []
+    envelope = { ...siblings, inputs: list }
+  } else {
+    envelope = { input: rest }
+  }
+  if (providerPin) envelope.provider = providerPin
+  if (fields !== undefined) envelope.fields = fields
+  if (reveal !== undefined) envelope.reveal = reveal
+
+  const res = await callApi('POST', verbPath, envelope)
+
+  // 4. Re-attach the per-item correlation id to bulk results (positional).
+  let data = res.data
+  if (
+    opts?.reattachIdField && opts?.bulkField && list &&
+    data && typeof data === 'object' && Array.isArray((data as { results?: unknown }).results)
+  ) {
+    const idField = opts.reattachIdField
+    const results = (data as { results: unknown[] }).results.map((r, i) => {
+      const id = list?.[i]?.[idField]
+      return id !== undefined && r && typeof r === 'object' && !Array.isArray(r)
+        ? { [idField]: id, ...(r as Record<string, unknown>) }
+        : r
+    })
+    data = { ...(data as Record<string, unknown>), results }
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data) }],
+    isError: !res.ok,
+  }
+}