@pipeworx/enrich-waterfall

Connect: https://gateway.pipeworx.io/enrich-waterfall/mcp · Install: one-click buttons

Tools: 1

Find a person’s work email by trying several email-finding vendors on the caller’s own accounts, in the caller’s own order, stopping at the first one that actually returns an address.

Tools

Auth

Bring your own keys. There is no other mode. Pass a key for at least one vendor and only those vendors are called:

A call with no vendor key at all returns reason: "api_key_required" and a message saying so — it is a missing credential, not a failure.

Pipeworx charges 0 credits for this tool on every tier. The pack is wired zeroRated: true in the gateway.

Hard rails

These are product commitments. They are restated in the source header because each one is a thing a future change could quietly undo:

• BYOK only. Every vendor leg runs on a key the caller passed on that call. There is no platform-key fallback, and this pack must never be given a platformKeyEnv. A vendor with no key is reported as skipped_no_key, never attempted on a Pipeworx account.
• No credit resale, no markup waterfall. We do not bill for this and do not mark up anyone’s vendor spend. Pricing this tool would convert a BYOK orchestrator into a data reseller, which is exactly what it was scoped not to be.
• No LinkedIn scraping. A linkedin_url appears only when a vendor the caller already pays for returned one.

Why this is not a thin wrapper

The four vendors disagree on every axis a caller would need them to agree on:

Three input conventions, three paths to the address, two mutually incomparable confidence scales, and one vendor with no person lookup at all. Looping them caller-side means writing four adapters and keeping them current.

Two things make the orchestration worth more than the adapters:

Early exit is where the money is. A parallel fan-out bills every vendor on every lookup; stopping at the first hit bills one. That is only safe if “did this vendor actually find it” is reliably answerable — which it is not by default, because:

findymail returns HTTP 200 with a populated contact record whose email is null when it has no match. A naive loop sees a truthy object, calls it a hit, stops, and returns a contact with no address. Every adapter here decides hit-versus-miss on the address, never on the envelope.

Reading the result

• email, answered_by — the address and which vendor produced it.
• confidence + confidence_basis — the vendor’s own number and what scale it is on. PDL’s likelihood is rescaled ×10 so a caller can sort one list; that does not make it comparable to hunter’s score, and confidence_basis travels with every number so nobody assumes it does.
• attempts[] — one row per vendor: status (hit / not_found / error / skipped_no_key / not_attempted), latency_ms, and vendor_quota_consumed. That last one is true even on a miss, because a miss still spends the caller’s quota — it is the number that actually decides a good vendor order.
• vendors_charged_to_you — which of the caller’s accounts were billed.
• On a miss, reason distinguishes not_found_by_any_vendor from all_vendors_errored. A caller retries on exactly one of those.

We deliberately do not quote per-call dollar prices for the vendors. Their pricing is plan-dependent and per-account, so any figure we printed would be a guess presented as a fact. latency_ms and vendor_quota_consumed are measured; the caller’s own invoice is the authority on price.

Data sources

• Hunter Email Finder — https://hunter.io/api-documentation/v2#email-finder
• Findymail — https://findymail.com/docs
• People Data Labs Person Enrichment — https://docs.peopledatalabs.com/docs/person-enrichment-api
• Snov.io Domain Search — https://snov.io/api

Each vendor is reached through its existing Pipeworx pack (mcps/hunter, mcps/findymail, mcps/peopledatalabs, mcps/snov) rather than directly, so a vendor’s quirks stay fixed in one place.

Tools

• enrich_find_email — Find a person’s work email by trying several email-finding vendors in order on YOUR OWN accounts, stopping at the first one that returns an address. Bring your own keys for hunter.io, findymail, Peopl