Filter discipline — compose before you pay

Every paid enrichment call costs virtual USD (or x402 after balance hits zero). Bill-on-match refunds no-match results, but you still burn latency and agent attention on bad inputs.

Rules

  1. Pick the narrowest tool first - Have an email → enrich_email - Have a domain → enrich_company with domain - Have a phone → enrich_phone - Have only a business name + city → enrich_websearch (see enrich_websearch_when) - Need a list by filters → leads_search

  2. Normalize inputs - Email: lowercase, trim whitespace - Domain: strip https:// and trailing paths - Phone: prefer E.164 (+1…)

  3. Lead search: always send at least one filter - Combine industry + state or city + title before widening - Use limit ≤ 25 on first page to cheaply probe coverage - Paginate with cursor only after the first page looks useful

  4. Check balance before a batch - GET /api/v1/agents/balance or MCP agents_balance - Prepay at /connect?action=topup if running headless

MCP tool map

User intent Tool
Single email enrich_email
Company / domain enrich_company
Phone lookup enrich_phone
Business name + geo enrich_websearch
Filtered lead list leads_search