fivos-contact-enrichment

Fivos Contact Enrichment

Contact-level enrichment. Self-sufficient - every provider call happens inside this skill, no delegation to other skills.

Hard rules

• Self-sufficient. This skill calls Find Email MCP and BetterContact MCP directly. It does NOT call bettercontact-phone or any other skill. Every external call here is its own MCP invocation.
• Email first, phone only when requested. Phone enrichment is ~10x the cost - do not run by default. Only if the play shape (from fivos-campaign-strategist) includes a phone channel.
• Verification is mandatory on every email before it reaches the copywriter. Undeliverable and catch-all-not-safe are dropped.
• Stop on deliverable. Once a contact has a deliverable or catch-all-safe email, downstream providers are not called on that contact. Saves 50%+ of waterfall spend.
• Per-column provenance is written to the CSV for every enriched field.

Inputs

• Contact CSV from fivos-contact-sourcing (required).
• Enrichment columns requested - typically email, optionally phone.
• Budget ceiling (optional).
• Tier column (optional) - if present, allow different waterfall aggression by tier (A runs full waterfall, B/C cut off earlier).

Outputs

1. Contact CSV with added columns: email, email_status, email_source, email_verified_at, phone, phone_source, phone_verified_at.
2. Verification status per email (deliverable, catch_all_safe, catch_all_not_safe, undeliverable, unknown).
3. Per-contact cost ledger.
4. Coverage report.

Providers + MCPs

Provider	MCP prefix	Status
Find Email (Findymail)	mcp__findymail__*	To be wired
BetterContact	mcp__bettercontact__*	To be wired
Zerobounce (verification)	mcp__zerobounce__*	To be wired

Until the MCPs are registered, fall back to each provider's REST API via Bash + curl with API keys in env (FINDYMAIL_API_KEY, BETTERCONTACT_API_KEY, ZEROBOUNCE_API_KEY).

Workflow

Step 1 - Cost estimate + Gate

Contact enrichment estimate - <client> / <campaign>

Contacts: N
Columns: email, [phone]
Waterfall depth:
  - Tier A: full (Find Email → BetterContact bulk)
  - Tier B: Find Email only
  - Tier C: Find Email only (single pass, no fallback)

Projected cost (assuming typical hit-rate cascade):
  - Email: $X
  - Phone: $Y (if requested)
Total: $X+Y

Proceed? Manager approval required if over budget.

Step 2 - Email waterfall

See waterfall.md for canonical order, stop-conditions, and per-provider batch sizes. High-level:

1. Find Email MCP first (cheapest, highest pre-verified hit rate).

mcp__findymail__find_emails({
  contacts: [
    { full_name: "<name>", domain: "<domain>" },
    ...
  ]
})

2. BetterContact bulk for any contact that Find Email missed. BetterContact is async - poll until done.

mcp__bettercontact__bulk_enrich({
  contacts: [
    { full_name: "<name>", domain: "<domain>", linkedin_url: "<url>" },
    ...
  ],
  enrich_phone_number: false
})
# returns { id }

mcp__bettercontact__get_result({ request_id: <id> })
# poll every 30s until state == "done", typically 30-120s (up to 10min)

Stop on deliverable or catch_all_safe per contact.

Step 3 - Verify every email

Run Zerobounce on every email returned that isn't already pre-verified by the source.

mcp__zerobounce__validate_email({ email: "<addr>" })

Drop undeliverable and catch_all_not_safe. Keep deliverable and catch_all_safe (only for domains on the client's safe catch-all allow-list).

Update email_status per contact. Only rows with deliverable or catch_all_safe flow to the copywriter.

Step 4 - Phone waterfall (only if requested)

Same self-sufficient pattern. Gate explicitly on approval before running - phone is expensive.

mcp__bettercontact__bulk_enrich({
  contacts: [...],
  enrich_phone_number: true
})

See waterfall.md for phone provider order.

Step 5 - Coverage report

Email coverage - <client> / <campaign>

Contacts in: N
Deliverable: X (X%)
Catch-all safe: Y (Y%)
Undeliverable / dropped: Z (Z%)

By tier:
  - Tier A: X% deliverable, Y% catch-all-safe
  - Tier B: ...
  - Tier C: ...

Phone coverage (if requested):
  - Mobile found: X (X%)
  - Landline only: Y
  - None: Z

If Tier A email coverage is below 70%, investigate before handing off - usually a persona / domain issue from upstream.

Step 6 - Upload + handoff

Write enriched contacts to the internal DB with full provenance. Hand off to fivos-lead-scoring (if not already scored at account level) or directly to fivos-copywriter.

Cost controls

• Always stop on deliverable. Do not run later providers "for comparison" - it wastes credits.
• Skip verification when the provider returns a pre-verified email. Providers that return verification: verified do not need a Zerobounce pass.
• Cap waterfall depth by tier. Tier C contacts do not justify a full waterfall.

Sub-files

• waterfall.md - canonical order, stop conditions, per-provider cost + quirks, MCP call syntax per step.

References

• ~/.agents/skills/gtm-meta-skill/provider-playbooks/bettercontact.md
• ~/.agents/skills/gtm-meta-skill/provider-playbooks/zerobounce.md