@coldiq/mcp 0.1.8 → 0.1.10

package/dist/utils/fuzzy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzy.d.ts","sourceRoot":"","sources":["../../src/utils/fuzzy.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAkBD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,CAAA;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,QAAQ,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,gBAAgB,GAAG,IAAI,CAwBvF"}

package/dist/utils/fuzzy.js

@@ -0,0 +1,46 @@
+export function normalize(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Match a user-supplied string against a list of candidate IDs.
+ * Precedence: exact → normalized (case + punctuation stripped) → Levenshtein ≤ threshold.
+ * Threshold = min(2, floor(len/3)) where len = normalized candidate length.
+ */
+export function fuzzyMatch(input, candidates) {
+    // Exact
+    if (candidates.includes(input))
+        return { matched: input, via: 'exact' };
+    const normInput = normalize(input);
+    // Normalized exact
+    for (const c of candidates) {
+        if (normalize(c) === normInput)
+            return { matched: c, via: 'normalized' };
+    }
+    // Levenshtein
+    let best = null;
+    for (const c of candidates) {
+        const normC = normalize(c);
+        const threshold = Math.min(2, Math.floor(normC.length / 3));
+        if (threshold === 0)
+            continue;
+        const dist = levenshtein(normInput, normC);
+        if (dist <= threshold && (best === null || dist < best.dist)) {
+            best = { matched: c, dist };
+        }
+    }
+    return best ? { matched: best.matched, via: 'fuzzy' } : null;
+}
+//# sourceMappingURL=fuzzy.js.map

package/dist/utils/fuzzy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzy.js","sourceRoot":"","sources":["../../src/utils/fuzzy.ts"],"names":[],"mappings":"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"}

package/dist/utils/provider-resolver.d.ts

@@ -0,0 +1,34 @@
+import type { Capability } from '../registry.js';
+export declare const FIND_EMAILS_PROVIDERS: string[];
+export declare function getProvidersForCapability(capability: Capability | 'find_emails'): string[];
+export interface ToolErrorPayload {
+    error: string;
+    available_providers: string[];
+}
+export declare function buildUnrecognizedError(input: string, capability: Capability | 'find_emails', available: string[]): ToolErrorPayload;
+export declare function buildGatedError(provider: string, gate: GateDesc, capability: Capability | 'find_emails', available: string[], input: Record<string, unknown>): ToolErrorPayload;
+export declare function buildAllFailedError(tried: string[], capability: Capability | 'find_emails', available: string[]): ToolErrorPayload;
+export interface ResolveOk {
+    ok: true;
+    providers: string[];
+    matchedFrom?: Record<string, string>;
+}
+export interface ResolveError {
+    ok: false;
+    error: ToolErrorPayload;
+}
+export type ResolveResult = ResolveOk | ResolveError;
+/**
+ * Resolve `use_providers` field against the capability's known provider IDs.
+ * - Empty/absent → auto-route (ok: true, providers: [])
+ * - Unknown name → unrecognized error
+ * - isApplicable fails → gated error
+ * - Otherwise → resolved IDs in user order
+ */
+export declare function resolvePreferredProviders(capability: Capability | 'find_emails', input: Record<string, unknown>, useProviders: unknown): ResolveResult;
+interface GateDesc {
+    kind: 'requires' | 'incompatible_with';
+    fields: string;
+}
+export {};
+//# sourceMappingURL=provider-resolver.d.ts.map

package/dist/utils/provider-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/provider-resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAKhD,eAAO,MAAM,qBAAqB,UAAoD,CAAA;AAEtF,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,GAAG,MAAM,EAAE,CAG1F;AAMD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB,EAAE,MAAM,EAAE,CAAA;CAC9B;AAKD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,UAAU,GAAG,aAAa,EACtC,SAAS,EAAE,MAAM,EAAE,GAClB,gBAAgB,CAKlB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,UAAU,GAAG,aAAa,EACtC,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,gBAAgB,CAoBlB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,UAAU,GAAG,aAAa,EACtC,SAAS,EAAE,MAAM,EAAE,GAClB,gBAAgB,CASlB;AAMD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,IAAI,CAAA;IACR,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE,gBAAgB,CAAA;CACxB;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,YAAY,CAAA;AAEpD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,GAAG,aAAa,EACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,YAAY,EAAE,OAAO,GACpB,aAAa,CAkDf;AAaD,UAAU,QAAQ;IAChB,IAAI,EAAE,UAAU,GAAG,mBAAmB,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;CACf"}

package/dist/utils/provider-resolver.js

@@ -0,0 +1,235 @@
+import { listCapabilityProviderIds, getProviderApplicabilityGuard } from '../registry.js';
+import { fuzzyMatch } from './fuzzy.js';
+// find_emails uses a custom waterfall — its providers are not in the registry.
+// Exported so find-emails.ts stays in sync without a second hardcoded list.
+export const FIND_EMAILS_PROVIDERS = ['prospeo', 'fullenrich', 'findymail', 'icypeas'];
+export function getProvidersForCapability(capability) {
+    if (capability === 'find_emails')
+        return FIND_EMAILS_PROVIDERS;
+    return listCapabilityProviderIds(capability);
+}
+const TRUST_LINE = 'Or just run the tool without specifying providers — ColdIQ will automatically pick the best tool for your needs.';
+export function buildUnrecognizedError(input, capability, available) {
+    return {
+        error: `'${input}' is not a recognized provider for this tool. Available providers: ${available.join(', ')}. ${TRUST_LINE}`,
+        available_providers: available,
+    };
+}
+export function buildGatedError(provider, gate, capability, available, input) {
+    const others = available.filter((p) => {
+        if (p === provider)
+            return false;
+        const guard = getProviderApplicabilityGuard(capability, p);
+        try {
+            return !guard || guard(input);
+        }
+        catch {
+            return false;
+        }
+    });
+    const othersText = others.length > 0
+        ? `Other providers that work with your inputs: ${others.join(', ')}. `
+        : '';
+    const clause = gate.kind === 'incompatible_with'
+        ? `is not compatible with ${gate.fields}`
+        : `requires ${gate.fields}, which wasn't provided`;
+    return {
+        error: `'${provider}' ${clause}. ${othersText}${TRUST_LINE}`,
+        available_providers: others,
+    };
+}
+export function buildAllFailedError(tried, capability, available) {
+    const remaining = available.filter((p) => !tried.includes(p));
+    const remainingText = remaining.length > 0
+        ? `You can retry with one of these instead: ${remaining.join(', ')}. `
+        : '';
+    return {
+        error: `Couldn't fulfill your request with the providers you specified (${tried.join(', ')}). ${remainingText}${TRUST_LINE}`,
+        available_providers: remaining,
+    };
+}
+/**
+ * Resolve `use_providers` field against the capability's known provider IDs.
+ * - Empty/absent → auto-route (ok: true, providers: [])
+ * - Unknown name → unrecognized error
+ * - isApplicable fails → gated error
+ * - Otherwise → resolved IDs in user order
+ */
+export function resolvePreferredProviders(capability, input, useProviders) {
+    if (!Array.isArray(useProviders) || useProviders.length === 0) {
+        return { ok: true, providers: [] };
+    }
+    const available = getProvidersForCapability(capability);
+    const resolved = [];
+    const matchedFrom = {};
+    for (const raw of useProviders) {
+        const userInput = typeof raw === 'string' ? raw.trim() : String(raw);
+        const match = fuzzyMatch(userInput, available);
+        if (!match) {
+            return { ok: false, error: buildUnrecognizedError(userInput, capability, available) };
+        }
+        if (match.via !== 'exact') {
+            matchedFrom[userInput] = match.matched;
+        }
+        if (!resolved.includes(match.matched)) {
+            resolved.push(match.matched);
+        }
+    }
+    // Check isApplicable for each resolved provider (registry-based capabilities only)
+    if (capability !== 'find_emails') {
+        for (const id of resolved) {
+            const guard = getProviderApplicabilityGuard(capability, id);
+            if (guard) {
+                let applicable;
+                try {
+                    applicable = guard(input);
+                }
+                catch {
+                    applicable = false;
+                }
+                if (!applicable) {
+                    const gate = getGateDescription(capability, id);
+                    return {
+                        ok: false,
+                        error: buildGatedError(id, gate, capability, available, input),
+                    };
+                }
+            }
+        }
+    }
+    return {
+        ok: true,
+        providers: resolved,
+        ...(Object.keys(matchedFrom).length > 0 ? { matchedFrom } : {}),
+    };
+}
+const GENERIC_REQUIRES = { kind: 'requires', fields: 'specific input fields' };
+const GATED_DESCRIPTIONS = {
+    // -------------------------------------------------------------------------
+    search_companies: {
+        theirstack: { kind: 'requires', fields: 'technologies, industries, or funding stage filters' },
+        signalbase: { kind: 'incompatible_with', fields: 'technology, funding, revenue, or hiring signal filters' },
+        blitzapi: { kind: 'incompatible_with', fields: 'advanced filters (tech stack, funding, revenue, exclusion lists, or workforce growth)' },
+        apollo: { kind: 'incompatible_with', fields: 'year, tech stack, funding, revenue, exclusion, or workforce growth filters' },
+        predictleads: { kind: 'requires', fields: 'both a location filter and an employee size filter' },
+        sumble: { kind: 'requires', fields: 'keywords, industries, or technologies' },
+        'limadata-prospect-filter': { kind: 'requires', fields: 'specific employee count range filters (min_employees / max_employees)' },
+        'limadata-prospect-url': { kind: 'requires', fields: 'linkedin_search_url' },
+        'linkupapi-fundraising': { kind: 'requires', fields: 'funding filters and keywords or industries' },
+        'linkupapi-hiring': { kind: 'requires', fields: 'is_hiring: true' },
+        'prospeo-search-company': { kind: 'requires', fields: 'keywords, industries, or countries' },
+        'ai-ark-companies': { kind: 'requires', fields: 'keywords, industries, or countries' },
+    },
+    // -------------------------------------------------------------------------
+    find_people: {
+        'linkupapi-search-profiles': { kind: 'incompatible_with', fields: 'company_linkedin_urls or company_domains (this provider only works without company filters)' },
+        'sumble-people-find': { kind: 'requires', fields: 'company_domains or company_linkedin_urls, and job_titles or seniorities' },
+        'prospeo-search-person': { kind: 'requires', fields: 'job_titles or company_domains' },
+        'ai-ark-people': { kind: 'requires', fields: 'job_titles, seniorities, or keywords' },
+        'findymail-search-employees': { kind: 'requires', fields: 'company_domains and job_titles' },
+    },
+    // -------------------------------------------------------------------------
+    find_email: {
+        findymail: { kind: 'requires', fields: 'first_name and (domain or company_name)' },
+        'limadata-work-email': { kind: 'requires', fields: 'first_name, last_name, and domain' },
+        blitzapi: { kind: 'requires', fields: 'linkedin_url' },
+        'limadata-work-email-linkedin': { kind: 'requires', fields: 'linkedin_url' },
+    },
+    // -------------------------------------------------------------------------
+    verify_email: {},
+    // -------------------------------------------------------------------------
+    find_phone: {
+        findymail: { kind: 'requires', fields: 'linkedin_url' },
+        limadata: { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
+        'ai-ark': { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
+    },
+    // -------------------------------------------------------------------------
+    enrich_company: {
+        companyenrich: { kind: 'requires', fields: 'domain' },
+        apollo: { kind: 'requires', fields: 'domain' },
+        limadata: { kind: 'requires', fields: 'domain or linkedin_url' },
+        wiza: { kind: 'requires', fields: 'domain or name' },
+        companyenrich_props: { kind: 'requires', fields: 'name or linkedin_url' },
+        blitzapi: { kind: 'requires', fields: 'linkedin_url' },
+        icypeas: { kind: 'requires', fields: 'linkedin_url' },
+        builtwith: { kind: 'requires', fields: 'domain' },
+        openmart: { kind: 'requires', fields: 'domain' },
+        'linkupapi-by-domain': { kind: 'requires', fields: 'domain' },
+        'linkupapi-by-url': { kind: 'requires', fields: 'linkedin_url' },
+    },
+    // -------------------------------------------------------------------------
+    enrich_person: {
+        'linkupapi-profile-enrich': { kind: 'requires', fields: 'first_name, last_name, and (company_name or domain)' },
+        'linkupapi-email-reverse': { kind: 'requires', fields: 'email' },
+        'blitzapi-reverse-email': { kind: 'requires', fields: 'email' },
+        'findymail-business-profile': { kind: 'requires', fields: 'linkedin_url (must be a linkedin.com URL)' },
+        'findymail-reverse-email': { kind: 'requires', fields: 'email' },
+        'icypeas-scrape-profile': { kind: 'requires', fields: 'linkedin_url (must be a linkedin.com URL)' },
+        'icypeas-url-search-profile': { kind: 'requires', fields: 'first_name, last_name, and (company_name or domain)' },
+        'ai-ark-reverse-lookup': { kind: 'requires', fields: 'email or phone' },
+        'icypeas-reverse-email-lookup': { kind: 'requires', fields: 'email' },
+    },
+    // -------------------------------------------------------------------------
+    search_web: {},
+    // -------------------------------------------------------------------------
+    search_jobs: {
+        career_site_jobs: { kind: 'incompatible_with', fields: 'LinkedIn-only filters (seniority_levels, industries, organization_slugs, min/max_employees, easy_apply_only, exclude_easy_apply)' },
+        linkedin_jobs_api: { kind: 'incompatible_with', fields: 'Career Site-only filters (ats_slugs, company_domains)' },
+        'theirstack-jobs': { kind: 'requires', fields: 'specific job filter conditions' },
+    },
+    // -------------------------------------------------------------------------
+    search_ads: {
+        google_ads: { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input); use query, domains, or advertiser_ids instead' },
+        linkedin_ad_library: { kind: 'requires', fields: 'search_urls (pre-built LinkedIn Ad Library URLs)' },
+        meta_ads: { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+        twitter_ads: { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+        reddit_ads: { kind: 'incompatible_with', fields: 'search_urls (LinkedIn-specific input)' },
+    },
+    // -------------------------------------------------------------------------
+    search_places: {
+        openmart: { kind: 'requires', fields: 'country in [US, CA, AU, PR, NZ] or structured Openmart filters' },
+        google_maps: { kind: 'requires', fields: 'a query or start_urls' },
+    },
+    // -------------------------------------------------------------------------
+    find_influencers: {
+        influencers_similar: { kind: 'requires', fields: 'handle (a creator handle for lookalike search)' },
+    },
+    // -------------------------------------------------------------------------
+    search_reddit: {},
+    // -------------------------------------------------------------------------
+    search_seo: {
+        kw_search_volume: { kind: 'requires', fields: 'category: "keywords"' },
+        kw_trends: { kind: 'requires', fields: 'category: "keywords"' },
+        serp_google: { kind: 'requires', fields: 'category: "serp" and engine: "google"' },
+        serp_bing: { kind: 'requires', fields: 'category: "serp" and engine: "bing"' },
+        serp_youtube: { kind: 'requires', fields: 'category: "serp" and engine: "youtube"' },
+        bl_summary: { kind: 'requires', fields: 'category: "backlinks"' },
+        bl_backlinks: { kind: 'requires', fields: 'category: "backlinks"' },
+        bl_referring: { kind: 'requires', fields: 'category: "backlinks"' },
+        domain_tech: { kind: 'requires', fields: 'category: "domain" and action: "technologies"' },
+        domain_whois: { kind: 'requires', fields: 'category: "domain" and action: "whois"' },
+        labs_rank_overview: { kind: 'requires', fields: 'category: "labs" and target' },
+        labs_ranked_kw: { kind: 'requires', fields: 'category: "labs" and target' },
+        labs_competitors: { kind: 'requires', fields: 'category: "labs" and target' },
+        labs_kw_ideas: { kind: 'requires', fields: 'category: "labs" and keywords[]' },
+        page_lighthouse: { kind: 'requires', fields: 'category: "page", url, and page_action: "lighthouse"' },
+        page_content: { kind: 'requires', fields: 'category: "page", url, and page_action: "content"' },
+    },
+    // -------------------------------------------------------------------------
+    find_signals: {
+        'signalbase-funding': { kind: 'requires', fields: 'signal_type: "funding"' },
+        'signalbase-acquisition': { kind: 'requires', fields: 'signal_type: "acquisition"' },
+        'signalbase-hiring': { kind: 'requires', fields: 'signal_type: "hiring"' },
+        'signalbase-job-change': { kind: 'requires', fields: 'signal_type: "job_change"' },
+        'theirstack-buying-intents': { kind: 'requires', fields: 'signal_type: "intent" and at least one of companies or domains' },
+        'predictleads-financing': { kind: 'requires', fields: 'signal_type: "funding"' },
+        'predictleads-news': { kind: 'requires', fields: 'signal_type: "news"' },
+        'predictleads-startup-posts': { kind: 'requires', fields: 'signal_type: "startup_post"' },
+    },
+    // -------------------------------------------------------------------------
+    fetch_page_content: {},
+};
+function getGateDescription(capability, providerId) {
+    return GATED_DESCRIPTIONS[capability]?.[providerId] ?? GENERIC_REQUIRES;
+}
+//# sourceMappingURL=provider-resolver.js.map

package/dist/utils/provider-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-resolver.js","sourceRoot":"","sources":["../../src/utils/provider-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAA;AAEzF,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvC,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,CAAC,CAAA;AAEtF,MAAM,UAAU,yBAAyB,CAAC,UAAsC;IAC9E,IAAI,UAAU,KAAK,aAAa;QAAE,OAAO,qBAAqB,CAAA;IAC9D,OAAO,yBAAyB,CAAC,UAAwB,CAAC,CAAA;AAC5D,CAAC;AAWD,MAAM,UAAU,GACd,kHAAkH,CAAA;AAEpH,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,UAAsC,EACtC,SAAmB;IAEnB,OAAO;QACL,KAAK,EAAE,IAAI,KAAK,sEAAsE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE;QAC3H,mBAAmB,EAAE,SAAS;KAC/B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,IAAc,EACd,UAAsC,EACtC,SAAmB,EACnB,KAA8B;IAE9B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACpC,IAAI,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QAChC,MAAM,KAAK,GAAG,6BAA6B,CAAC,UAAwB,EAAE,CAAC,CAAC,CAAA;QACxE,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,CAAA;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAC,CAAA;IACF,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC;QAClC,CAAC,CAAC,+CAA+C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACtE,CAAC,CAAC,EAAE,CAAA;IACN,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,KAAK,mBAAmB;QAC9C,CAAC,CAAC,0BAA0B,IAAI,CAAC,MAAM,EAAE;QACzC,CAAC,CAAC,YAAY,IAAI,CAAC,MAAM,yBAAyB,CAAA;IACpD,OAAO;QACL,KAAK,EAAE,IAAI,QAAQ,KAAK,MAAM,KAAK,UAAU,GAAG,UAAU,EAAE;QAC5D,mBAAmB,EAAE,MAAM;KAC5B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAAe,EACf,UAAsC,EACtC,SAAmB;IAEnB,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7D,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC;QACxC,CAAC,CAAC,4CAA4C,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACtE,CAAC,CAAC,EAAE,CAAA;IACN,OAAO;QACL,KAAK,EAAE,mEAAmE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,aAAa,GAAG,UAAU,EAAE;QAC5H,mBAAmB,EAAE,SAAS;KAC/B,CAAA;AACH,CAAC;AAmBD;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAsC,EACtC,KAA8B,EAC9B,YAAqB;IAErB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IACpC,CAAC;IAED,MAAM,SAAS,GAAG,yBAAyB,CAAC,UAAU,CAAC,CAAA;IACvD,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,WAAW,GAA2B,EAAE,CAAA;IAE9C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACpE,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;QAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,CAAA;QACvF,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;YAC1B,WAAW,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,OAAO,CAAA;QACxC,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;IAED,mFAAmF;IACnF,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QACjC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,6BAA6B,CAAC,UAAwB,EAAE,EAAE,CAAC,CAAA;YACzE,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,UAAmB,CAAA;gBACvB,IAAI,CAAC;oBACH,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;gBAC3B,CAAC;gBAAC,MAAM,CAAC;oBACP,UAAU,GAAG,KAAK,CAAA;gBACpB,CAAC;gBACD,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,MAAM,IAAI,GAAG,kBAAkB,CAAC,UAAwB,EAAE,EAAE,CAAC,CAAA;oBAC7D,OAAO;wBACL,EAAE,EAAE,KAAK;wBACT,KAAK,EAAE,eAAe,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC;qBAC/D,CAAA;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,SAAS,EAAE,QAAQ;QACnB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAA;AACH,CAAC;AAkBD,MAAM,gBAAgB,GAAa,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAA;AAExF,MAAM,kBAAkB,GAAmE;IACzF,4EAA4E;IAC5E,gBAAgB,EAAE;QAChB,UAAU,EAAe,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,oDAAoD,EAAE;QACnH,UAAU,EAAe,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,wDAAwD,EAAE;QACxH,QAAQ,EAAiB,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,uFAAuF,EAAE;QACvJ,MAAM,EAAmB,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,4EAA4E,EAAE;QAC5I,YAAY,EAAa,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,oDAAoD,EAAE;QACnH,MAAM,EAAmB,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,uCAAuC,EAAE;QACtG,0BAA0B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAO,MAAM,EAAE,uEAAuE,EAAE;QACtI,uBAAuB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,qBAAqB,EAAE;QACpF,uBAAuB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,4CAA4C,EAAE;QAC3G,kBAAkB,EAAO,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,iBAAiB,EAAE;QAChF,wBAAwB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAS,MAAM,EAAE,oCAAoC,EAAE;QACnG,kBAAkB,EAAO,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,oCAAoC,EAAE;KACpG;IACD,4EAA4E;IAC5E,WAAW,EAAE;QACX,2BAA2B,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,6FAA6F,EAAE;QACjK,oBAAoB,EAAK,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,yEAAyE,EAAE;QACxI,uBAAuB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,+BAA+B,EAAE;QAC9F,eAAe,EAAU,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,sCAAsC,EAAE;QACrG,4BAA4B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAK,MAAM,EAAE,gCAAgC,EAAE;KAChG;IACD,4EAA4E;IAC5E,UAAU,EAAE;QACV,SAAS,EAAoB,EAAE,IAAI,EAAE,UAAU,EAAK,MAAM,EAAE,yCAAyC,EAAE;QACvG,qBAAqB,EAAQ,EAAE,IAAI,EAAE,UAAU,EAAK,MAAM,EAAE,mCAAmC,EAAE;QACjG,QAAQ,EAAqB,EAAE,IAAI,EAAE,UAAU,EAAK,MAAM,EAAE,cAAc,EAAE;QAC5E,8BAA8B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE;KAC7E;IACD,4EAA4E;IAC5E,YAAY,EAAE,EAAE;IAChB,4EAA4E;IAC5E,UAAU,EAAE;QACV,SAAS,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE;QACvD,QAAQ,EAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6DAA6D,EAAE;QACtG,QAAQ,EAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6DAA6D,EAAE;KACvG;IACD,4EAA4E;IAC5E,cAAc,EAAE;QACd,aAAa,EAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC5D,MAAM,EAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC5D,QAAQ,EAAc,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,EAAE;QAC5E,IAAI,EAAkB,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE;QACpE,mBAAmB,EAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE;QAC1E,QAAQ,EAAc,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE;QAClE,OAAO,EAAe,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE;QAClE,SAAS,EAAa,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC5D,QAAQ,EAAc,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC5D,qBAAqB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC7D,kBAAkB,EAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE;KACnE;IACD,4EAA4E;IAC5E,aAAa,EAAE;QACb,0BAA0B,EAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,qDAAqD,EAAE;QACjH,yBAAyB,EAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;QACnE,wBAAwB,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;QACnE,4BAA4B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,2CAA2C,EAAE;QACvG,yBAAyB,EAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;QACnE,wBAAwB,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,2CAA2C,EAAE;QACvG,4BAA4B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,qDAAqD,EAAE;QACjH,uBAAuB,EAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE;QAC5E,8BAA8B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;KACtE;IACD,4EAA4E;IAC5E,UAAU,EAAE,EAAE;IACd,4EAA4E;IAC5E,WAAW,EAAE;QACX,gBAAgB,EAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,kIAAkI,EAAE;QAC7L,iBAAiB,EAAG,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,uDAAuD,EAAE;QAClH,iBAAiB,EAAG,EAAE,IAAI,EAAE,UAAU,EAAW,MAAM,EAAE,gCAAgC,EAAE;KAC5F;IACD,4EAA4E;IAC5E,UAAU,EAAE;QACV,UAAU,EAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,sFAAsF,EAAE;QAClJ,mBAAmB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAW,MAAM,EAAE,kDAAkD,EAAE;QAC9G,QAAQ,EAAa,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,uCAAuC,EAAE;QACnG,WAAW,EAAU,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,uCAAuC,EAAE;QACnG,UAAU,EAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,uCAAuC,EAAE;KACpG;IACD,4EAA4E;IAC5E,aAAa,EAAE;QACb,QAAQ,EAAM,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,gEAAgE,EAAE;QACpH,WAAW,EAAG,EAAE,IAAI,EAAE,UAAU,EAAU,MAAM,EAAE,uBAAuB,EAAE;KAC5E;IACD,4EAA4E;IAC5E,gBAAgB,EAAE;QAChB,mBAAmB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,gDAAgD,EAAE;KACpG;IACD,4EAA4E;IAC5E,aAAa,EAAE,EAAE;IACjB,4EAA4E;IAC5E,UAAU,EAAE;QACV,gBAAgB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE;QACtE,SAAS,EAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE;QACtE,WAAW,EAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uCAAuC,EAAE;QACvF,SAAS,EAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,qCAAqC,EAAE;QACrF,YAAY,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wCAAwC,EAAE;QACxF,UAAU,EAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE;QACvE,YAAY,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE;QACvE,YAAY,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE;QACvE,WAAW,EAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,+CAA+C,EAAE;QAC/F,YAAY,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wCAAwC,EAAE;QACxF,kBAAkB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6BAA6B,EAAE;QAC/E,cAAc,EAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6BAA6B,EAAE;QAC7E,gBAAgB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6BAA6B,EAAE;QAC7E,aAAa,EAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,iCAAiC,EAAE;QACjF,eAAe,EAAG,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sDAAsD,EAAE;QACtG,YAAY,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mDAAmD,EAAE;KACpG;IACD,4EAA4E;IAC5E,YAAY,EAAE;QACZ,oBAAoB,EAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,EAAE;QACnF,wBAAwB,EAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,EAAE;QACvF,mBAAmB,EAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE;QAClF,uBAAuB,EAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,2BAA2B,EAAE;QACtF,2BAA2B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,gEAAgE,EAAE;QAC3H,wBAAwB,EAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,EAAE;QACnF,mBAAmB,EAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,qBAAqB,EAAE;QAChF,4BAA4B,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,6BAA6B,EAAE;KAC1F;IACD,4EAA4E;IAC5E,kBAAkB,EAAE,EAAE;CACvB,CAAA;AAED,SAAS,kBAAkB,CAAC,UAAsB,EAAE,UAAkB;IACpE,OAAO,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,gBAAgB,CAAA;AACzE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/executor.ts

@@ -7,6 +7,7 @@ export interface ExecutionResult {
   _meta: {
     provider: string
     latencyMs: number
+    matchedFrom?: Record<string, string>
   }
 }
 
@@ -138,19 +139,41 @@ async function executeSingle(
 // Fallback execution — try providers in order, return first success
 // ---------------------------------------------------------------------------
 
+export interface ExecuteOptions {
+  /** When set, only these provider IDs are tried (in this order). No fallback to others. */
+  providers?: string[]
+  /** Fuzzy-match aliases to surface in success _meta */
+  matchedFrom?: Record<string, string>
+}
+
 export async function executeWithFallback(
   capability: Capability,
   input: Record<string, unknown>,
+  options?: ExecuteOptions,
 ): Promise<ExecutionResult | ExecutionError> {
-  const providers =
+  const preferredIds = options?.providers ?? []
+  const isConstrained = preferredIds.length > 0
+
+  let allProviders =
     capability === 'search_web'
       ? getSearchWebProviders(input.search_type === 'neural')
       : getProviders(capability)
 
+  // When the caller pinned specific providers, filter to those in order.
+  if (isConstrained) {
+    const ordered: typeof allProviders = []
+    for (const id of preferredIds) {
+      const entry = allProviders.find((p) => p.id === id)
+      if (entry) ordered.push(entry)
+    }
+    allProviders = ordered
+  }
+
   const errors: Array<{ id: string; status: number; error: string }> = []
   let billingUrl: string | undefined
+  let zeroBalance = false
 
-  for (const provider of providers) {
+  for (const provider of allProviders) {
     if (provider.isApplicable) {
       let applicable: boolean
       try {
@@ -186,7 +209,11 @@ export async function executeWithFallback(
 
     if (hasResult) {
       log(`${capability} → ${provider.id} ✓ (${result.latencyMs}ms)`)
-      return { data: payload, _meta: { provider: provider.id, latencyMs: result.latencyMs } }
+      const meta: ExecutionResult['_meta'] = { provider: provider.id, latencyMs: result.latencyMs }
+      if (options?.matchedFrom && Object.keys(options.matchedFrom).length > 0) {
+        meta.matchedFrom = options.matchedFrom
+      }
+      return { data: payload, _meta: meta }
     }
 
     // Record the failure
@@ -201,23 +228,37 @@ export async function executeWithFallback(
 
     // Capture the billing URL the API surfaces in 402 responses so the
     // top-level error can include a clickable link for the user.
-    if (result.status === 402 && !billingUrl
-        && result.data && typeof result.data === 'object'
-        && typeof (result.data as Record<string, unknown>).billingUrl === 'string') {
-      billingUrl = (result.data as Record<string, string>).billingUrl
+    if (result.status === 402
+        && result.data && typeof result.data === 'object') {
+      const body = result.data as Record<string, unknown>
+      if (!billingUrl && typeof body.billingUrl === 'string') {
+        billingUrl = body.billingUrl
+      }
+      // Short-circuit the waterfall when the user has no credits at all.
+      // Every paid provider needs >= 1 credit, so trying the rest is wasted
+      // round-trips. Non-zero balances may still match a cheaper provider,
+      // so only bail when balance is exactly 0.
+      if (typeof body.balance === 'number' && body.balance <= 0) {
+        zeroBalance = true
+        debug(`${capability} → balance is 0, skipping remaining providers`)
+        break
+      }
     }
   }
 
   debug(`${capability}: all ${errors.length} providers failed — ${JSON.stringify(errors)}`)
-  const sanitized = errors.map((e, i) => ({
-    provider: `provider_${i + 1}`,
-    status: e.status,
-    error: e.error.slice(0, 200),
-  }))
 
-  const allOutOfCredits = errors.length > 0 && errors.every((e) => e.status === 402)
+  // When the user pinned specific providers, expose their real IDs in the error
+  // (they already know what they asked for). Otherwise anonymize to avoid leaking
+  // internal provider names on auto-route failures.
+  const sanitized = isConstrained
+    ? errors.map((e) => ({ provider: e.id, status: e.status, error: e.error.slice(0, 200) }))
+    : errors.map((e, i) => ({ provider: `provider_${i + 1}`, status: e.status, error: e.error.slice(0, 200) }))
+
+  const allOutOfCredits = zeroBalance
+    || (errors.length > 0 && errors.every((e) => e.status === 402))
   const topLevelError = allOutOfCredits && billingUrl
-    ? `Insufficient credits — every provider for ${capability} returned 402. Top up at ${billingUrl} to continue.`
+    ? `Insufficient credits — your account balance is 0 and this request requires credits. Top up at ${billingUrl} to continue.`
     : `All ${errors.length} providers failed for ${capability}`
 
   const out: ExecutionError = {

package/src/registry.ts

@@ -3073,6 +3073,26 @@ const registry: Record<Capability, ProviderEntry[]> = {
   fetch_page_content: fetchPageContentProviders,
 }
 
+/**
+ * Return the ordered provider IDs for a capability (for documentation / resolver).
+ */
+export function listCapabilityProviderIds(capability: Capability): string[] {
+  return getProviders(capability).map((p) => p.id)
+}
+
+/**
+ * Return the isApplicable guard for a specific provider within a capability.
+ * Returns undefined when the provider has no gate.
+ */
+export function getProviderApplicabilityGuard(
+  capability: Capability,
+  providerId: string,
+): ((input: Record<string, unknown>) => boolean) | undefined {
+  const providers = registry[capability]
+  if (!providers) return undefined
+  return providers.find((p) => p.id === providerId)?.isApplicable
+}
+
 /**
  * Get the ordered provider list for a capability.
  * Returns a copy sorted by priority (lower = first).

package/src/tools/enrich-company.ts

@@ -1,23 +1,30 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.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.'
+  '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. ColdIQ automatically picks the best provider based on which input fields are present — pass use_providers only if you need a specific tool.'
 
 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")'),
+  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('enrich_company').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function enrichCompanyHandler(input: Record<string, unknown>) {
-  if (!input.domain && !input.linkedin_url && !input.name) {
+  const { use_providers: rawUseProviders, ...restInput } = input
+  if (!restInput.domain && !restInput.linkedin_url && !restInput.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)
+  const resolved = resolvePreferredProviders('enrich_company', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('enrich_company', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/enrich-person.ts

@@ -1,12 +1,14 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.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.'
+  'Returns LinkedIn URL, headline, location, current role, and profile data. ' +
+  'ColdIQ automatically picks the best provider based on which input fields are present — pass use_providers only if you need a specific tool.'
 
 export const enrichPersonSchema = {
   email: z.string().email().optional().describe('Email address for reverse lookup — identify the person behind the email'),
@@ -16,10 +18,16 @@ export const enrichPersonSchema = {
   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'),
+  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('enrich_person').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function enrichPersonHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('enrich_person', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('enrich_person', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('enrich_person', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

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

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const fetchPageContentName = 'fetch_page_content'
 
@@ -25,10 +26,16 @@ export const fetchPageContentSchema = {
     .optional()
     .default(false)
     .describe('Generate a summary for each page in addition to the text (default: false).'),
+  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('fetch_page_content').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 export async function fetchPageContentHandler(input: Record<string, unknown>) {
-  const result = await executeWithFallback('fetch_page_content', input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('fetch_page_content', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('fetch_page_content', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }

package/src/tools/find-email.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { executeWithFallback, isExecutionError } from '../executor.js'
+import { resolvePreferredProviders, getProvidersForCapability } from '../utils/provider-resolver.js'
 
 export const findEmailName = 'find_email'
 
@@ -15,6 +16,7 @@ export const findEmailSchema = {
   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'),
+  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_email').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
 const inputSchema = z
@@ -40,7 +42,12 @@ const inputSchema = z
   })
 
 export async function findEmailHandler(input: Record<string, unknown>) {
-  const validation = inputSchema.safeParse(input)
+  const { use_providers: rawUseProviders, ...restInput } = input
+  const resolved = resolvePreferredProviders('find_email', restInput, rawUseProviders)
+  if (!resolved.ok) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(resolved.error, null, 2) }], isError: true }
+  }
+  const validation = inputSchema.safeParse(restInput)
   if (!validation.success) {
     const msg = validation.error.issues.map((i) => i.message).join('; ')
     return {
@@ -48,7 +55,7 @@ export async function findEmailHandler(input: Record<string, unknown>) {
       isError: true,
     }
   }
-  const result = await executeWithFallback('find_email', input)
+  const result = await executeWithFallback('find_email', restInput, { providers: resolved.providers, matchedFrom: resolved.matchedFrom })
   if (isExecutionError(result)) {
     return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
   }