How to Build an Email Waterfall Tool for Your AI Agent
The provider stack, the ordering economics, and the Claude tool definition that turns enrichment from a Clay table into a capability your agents call.
TL;DR
- A waterfall beats any single provider because coverage is uncorrelated: one vendor's gap is another's hit. No single source we have tested clears 70 percent of a real B2B list; a well-ordered stack of five to seven does meaningfully better at lower cost per verified email.
- Order by economics, not by brand: cheap pattern inference and cached hits first, paid finders next, expensive lookups last, and verification exactly once at the end. The most common silent money leak is a build that verifies the same address twice.
- Verification is the gate, not a step. An address ships only when the verifier says deliverable. Accept-all domains get flagged and carried as judgment calls, not silently passed or silently dropped.
- Group work by company domain before dispatching. Ten contacts at one company should hit the pattern cache nine times, not pay the finder ten times.
- The unlock is packaging it as a tool your AI agent calls: one command in Claude, with the provider keys, ordering, caching, and gate logic inside. Then every workflow that needs an email, from list building to reply handling, gets the same quality without anyone re-deciding the stack.
Most teams meet waterfall enrichment inside a Clay table: a column of providers that fire left to right until one returns an email. That works until you want an AI agent to do the work, and then the table becomes the bottleneck, because your agent cannot call a spreadsheet. This guide is how we build the same capability as a standalone tool: a script or skill your agent invokes with a name and a domain, that runs the stack, verifies the result, controls the spend, and returns either a deliverable address or an honest miss.
Why a waterfall at all
Email finders have uncorrelated coverage. Each vendor crawled different sources, refreshes on different cycles, and is strong in different segments. On real B2B lists we have never seen a single provider clear 70 percent coverage, and the misses are not random: a vendor that is weak on mid-market manufacturing is weak on the whole segment. Stacking providers turns seven mediocre coverage maps into one good one. The waterfall is also a cost instrument: because you stop at the first hit, the expensive providers only ever see the hard residue.
The core stack, by role
| Stage | Cost | Role | Rule |
|---|---|---|---|
| Cache | Free | Anything found + verified in the last 30 days | Check first, always; date every entry |
| Pattern inference | Free | jane.doe@ seen once = every colleague guessed | Guesses still go through the gate |
| Finders (2-4) | Cheap to mid | Uncorrelated coverage maps stacked | Order by measured cost per hit, re-measure quarterly |
| Deep lookups | Expensive | The residue everything else missed | Last, and only the residue |
| Verification | Per address | BounceBan-class deliverability check | Exactly once; deliverable ships, accept-all is flagged |
| Phone (adjacent) | Varies | Same shape, Trestle-class validation | Refute-first: ships only when nothing contradicts it |
Ordering economics
The order is an economics decision you should be able to defend with numbers: expected cost per hit at each stage, measured on your own traffic. Run a hundred-contact sample through each provider independently once a quarter, record hit rate and cost, and let the resulting cost per hit set the order. Two orderings that look similar can differ by 3x in credits per verified email, and the difference is invisible unless you measure it.
The verification gate
The gate is what separates a waterfall tool from a list of guesses. Ours is simple and strict: deliverable means it ships, everything else does not, and accept-all is persisted as metadata rather than treated as a pass or a fail. Accept-all domains verify at the server level but not the mailbox level, so a confirmed format is not proof the person is still there; for a high-stakes send to a named executive, that flag is the difference between confident and reckless. Make the gate server-side and unskippable if more than one person or agent will use the tool. The first time someone bypasses it under deadline pressure is the day your bounce rate becomes a deliverability problem.
Wiring it into Claude
- Build it as a CLI first: name plus company domain in, JSON out with the address, the provider that found it, the verification result, and the credits spent. Every provider call isolated with retries and a per-item error captured, never a crashed batch.
- Give it resumability from day one: append results to a checkpoint file as they complete, and accept a start-at flag. Enrichment runs die at item 400 of 500; the rerun should cost 100 items, not 500.
- Wrap it in a skill: a short markdown file that tells Claude when to reach for the tool, what the inputs are, what the output means, and what the tool refuses to do. Now every list build, reply flow, or research pass in your Claude OS calls the same waterfall instead of improvising enrichment.
- Put the spend rules in the skill, not in someone's memory: cost estimate before bulk runs above a threshold, and an explicit approval step past it.
- Log per-run economics: contacts in, verified emails out, credits spent, per-provider hit counts. This is the data that reorders your stack next quarter.
Build order, one week
- Day 1: pattern inference + cache + one finder + the verifier, wired as a straight line. Ship nothing that is not deliverable.
- Day 2-3: add the remaining finders and the domain grouping. Measure cost per verified email on a 200-contact sample.
- Day 4: checkpointing, retries, the run-economics log, and the double-verification assertion.
- Day 5: the Claude skill wrapper plus the spend gate, and a side-by-side against your current process on a real list before you switch anything over.
Where builds go wrong
- Trusting a provider's own accuracy claims instead of measuring hit rates on your lists. Every vendor is excellent in their own benchmark.
- Treating verification as optional on 'obvious' patterns. The obvious pattern at a company that just migrated email domains is a bounce.
- Building the ordering into code as constants scattered across scripts instead of one configuration the whole team can see and change.
- Skipping the miss path. An honest 'not found' with the providers tried is more useful downstream than a low-confidence guess dressed as a hit.
The pattern generalizes past email. Phone lookups, LinkedIn resolution, technographic checks: each is the same shape, a cheap-first ordered stack behind a verification gate, packaged as a tool your agents call. Build the first one well and the second takes a day. This is what we mean when we say the operating system compounds.
Want this built for your team?
We build and run these systems embedded with your team.