icp-list-builder

ICP List Builder

Overview

This skill answers the questions people ask when they want a contact list: how many companies fit, how many decision-makers sit in them, how to tier them, what it costs, and how to end up with verified emails. It then builds the list: a send file where every email validated valid, a hold file for catch-all and unknown addresses, and a report whose funnel accounts for every dropped row.

When ScraperCity is reachable, the counts are free, so the skill runs them before answering and delivers a run report with live numbers. When no call can run (no API key or MCP server in the session), it delivers a plan report: company counts from Census firm data, contact counts from published buying-group sizes, costs as ceilings, and dated steps that replace each estimate.

It prevents three expensive mistakes: describing an ICP in adjectives and pulling whatever the database returns; quoting invented counts and rates as if they were measured; and paying to validate thousands of contacts the tiers will never email.

When to Use

• "Build me a list of the people who decide on X at Y companies with 200-2,000 employees. How many exist, how would you tier them, what does it cost?"
• "Here are 5 of our best customers, build me a list of more like them."
• "Pull VP Sales at 50-200 employee SaaS companies in the US."
• "Here's my Sales Navigator search, get me emails for these people."
• "Lookalike list", "ICP list", "target account contacts", "buying committee at companies like these".

Use a different skill when:

Prerequisites

Collect these before the first call. A missing input never blocks the work: use the sourced default in the table and ask for the input once, as a Next Steps row.

Authoritative Foundations

Details and when to open each file: references/framework-notes.md.

Workflow

1. Decide run or plan

Call check_wallet. If it answers, every count below is free: run them and write a run report. If ScraperCity is not reachable in the session, write a plan report: size companies from SUSB (step 4), contacts as companies x 5-11 (Gartner), costs as ceilings, and put every call in Next Steps with an owner and a date. Never fill a plan with invented counts, valid shares or catch-all shares; a figure is sourced, computed from sourced figures, or left to the step that measures it.

2. Build the evidence worksheet, or ask for it once

For each best-fit and lost domain, call query_lead_database with companyDomain and limit: 5; record industry as the database spells it, employees, keywords, HQ, the signer's title and the trigger at purchase. Trait rules are in references/icp-evidence-worksheet.md: a trait every best-fit account shares becomes a filter; a trait on fit losses only becomes an exclusion the user approves; competitor, price and timing losses never exclude. With no evidence, write the ICP statement from the instruction and one "Evidence:" line asking for domains; never a table of empty rows. Get the user's yes on the statement before pulling.

3. Map the buying group into role families

One query per role family, so a long title list in one family cannot leak rows into another. Most B2B purchases need four: the economic buyer, the day-to-day owner of the problem, the technical evaluator, and IT or systems when the product touches their stack. Title and notTitle strings are in references/title-synonyms-and-exclusions.md (section "Buying-group families"). The economic-buyer family always carries Owner, Co-Owner, Founder, Co-Founder and Managing Partner next to CEO and President: family-owned and founder-led companies use those titles for the person who signs. Guard the partial matches: "vice" stops "President" from matching every Vice President, "coordinator" stops "COO", "product owner" and "process owner" stop "Owner".

Start the shared filters from the closest recipe in references/icp-filter-recipes.md, or translate a Sales Navigator search with references/sales-navigator-filter-map.md. Add hasEmail: true, the anti-ICP notKeywords, and industry only once a customer lookup shows the database's label.

4. Count companies and people

• People: one limit: 1 count per family; read pagination.total. Read the first 100 rows of each and put the word behind every wrong title into notTitle, then recount. Widen or tighten with the table in references/count-and-paging-runbook.md.
• Companies: the Lead Database counts people. Pull the families (included in the plan) and dedupe on company_domain; that is the company count. Do not multiply a title proxy by an assumed ratio.
• Benchmark: SUSB firm counts for the NAICS codes and employment classes of the band (references/count-and-paging-runbook.md section 9). A database count far below SUSB after exclusions means widen keywords, then look up the domains on the industry's association member directory or trade-show exhibitor list with companyDomain; far above means the keywords admit other industries.
• Band edges: in industries with mostly hourly staff (warehousing, manufacturing, retail, healthcare delivery, construction, hospitality), count the band just below the floor as its own query. Step 6 admits those companies one by one.

Wait for a go-ahead when the paid part exceeds $5.

5. Pull with cursor paging

Page each family with after: "0", limit: 100, then each pagination.next_after until null. Keep filters identical across pages and save each page as it arrives. Add excludeDelivered: true on later cycles. Loop and failures: references/count-and-paging-runbook.md.

6. Check the business model and the band edges

When keywords cannot separate companies that run the operation the product serves from look-alikes (a 3PL that runs warehouses versus a freight broker; a food plant versus a brand that uses a co-manufacturer; a clinic versus a billing company), read each account's own site before scoring: record yes or no and the URL that shows it (plant_check_url, site_check_url). Drop the no's before any paid step. In the same pass, a company from the below-floor band joins only when its site, a press release or a job posting states a headcount inside the band; a company inside the band whose site states one above the ceiling leaves. No ScraperCity charge; it costs reading time, so it runs after dedupe and exclusions.

7. Tier the accounts (when asked, or when the list exceeds what the team can work)

Fit sets the tier, using only columns every account has (size band, segment, role families present); a column filled for some accounts stays out of the score. Tier rows add up to the account total. Contacts per account fall by tier and never exceed the buying group. Movers (a dated trigger such as a new site, a new leader in the buyer's seat, hiring for the role the product serves, or a past reply in the CRM) lift an account one tier for the next send cycle; two movers still lift one tier. Tier 1 size comes from the user's AE headcount; without it, one Capacity line asks for it. Spend ceilings appear only on a "Deal inputs (from you):" line with the user's deal size, margin and win rates. Weighted lift scores across a whole market belong to tam-builder.

8. Normalize, dedupe, suppress

Map fields to the person schema in the quality standard (section 2a), normalize (section 3), dedupe on email, then LinkedIn URL, then first + last + domain. Suppress in this order: unsubscribes and remove requests, the do-not-contact list, bounces, complaints, current customers, open opportunities, competitors, anyone contacted inside the re-contact window. Count every drop by reason.

9. Validate only the selected slots

Pick a primary and one backup per slot under each tier's cap. Validate the primaries with validate_emails; an invalid slot gets its backup validated, an unknown gets one re-check on a later day, so each slot is validated at most twice. Top-tier slots still empty take a named person from the same family query with hasEmail removed, then find_emails ($0.05 per email found, free if none). Poll check_run_status until SUCCEEDED, download_results, map email_result (valid_catch_all becomes catch_all). Only valid goes into the send file; catch-all and still-unknown go to the hold file.

10. Fit sample, deliver, test cell

Check a random sample per tier by hand on title, company, location, domain and still-employed. Size it as n = 3 / the misfit ceiling, n over 30 (Eypasch 1995): 60 rows caps misfits under 5% when none miss. A miss a filter word would have stopped means fix the filter and re-pull, never hand-patch rows. Write the report from templates/output-template.md and run scripts/check-output.py on it. Release a 100-contact test cell first (Berman, Lean B2B 2020) and the rest only while bounces stay under 2% (alexberman.com); the hold file follows as its own 100-contact cell under the same line. Sort replies by title family; when referral replies keep naming another title, move it up on the next pull. Change the list or the copy per cycle, never both.

ScraperCity Implementation

Count call (MCP), one per role family

{
  "title": "VP Sales, Vice President of Sales, VP of Sales, Head of Sales, Chief Revenue Officer, CRO",
  "notTitle": "assistant, intern, former, retired, advisor, board, investor, operations, enablement, engineer",
  "keywords": ["saas", "b2b"],
  "notKeywords": ["agency", "staffing"],
  "minEmployees": 50,
  "maxEmployees": 200,
  "country": ["United States"],
  "hasEmail": true,
  "limit": 1
}

Seniority can replace part of a title list: "seniority": ["vp", "c_suite"] with "department": ["sales"]. The tool documents vp, director and c_suite as seniority values; confirm any other value (such as owner) with a limit: 1 call and read the rows, or put the titles in title.

Pull loop (MCP)

after = "0"
while after:
    r = query_lead_database({...same filters..., "limit": 100, "after": after})
    save(r.data)
    after = r.pagination.next_after

REST and CLI

curl -s -X POST -H "Authorization: Bearer $SCRAPERCITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"VP Sales, Head of Sales, CRO","keywords":["saas"],"minEmployees":50,"maxEmployees":200,"country":["United States"],"hasEmail":true,"limit":100,"after":"0"}' \
  https://app.scrapercity.com/api/v1/database/leads
curl -s -X POST -H "Authorization: Bearer $SCRAPERCITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]"]}' https://app.scrapercity.com/api/v1/scrape/email-validator

Then GET /api/v1/scrape/status/{runId} until SUCCEEDED and GET /api/downloads/{runId}. CLI: db-leads, email-validate, poll, download.

Worked cost estimate (plan report)

Food and beverage manufacturers, 200-2,000 employees: 1,228 firms in SUSB 2022, tiered 171 / 320 / 737 with 4 / 3 / 2 contacts.

$44.74 sits inside Growth's $159 monthly credit, so the cash cost is the $149 plan fee. It exceeds $5, so show this table and wait for a yes before step 9.

Error handling

Output Format

The user receives the send file and hold file (run report only) and one markdown report from templates/output-template.md:

1. Title, then one Status: line: "Ran YYYY-MM-DD" with plan and wallet, or "Plan, prepared YYYY-MM-DD" with the one sentence saying nothing ran and which step replaces the estimates. That sentence appears nowhere else in the report.
2. ## Answer first: a table with one row per question the user asked, in their words. In a plan, counts are sourced ranges or ceilings.
3. ## ICP Definition: the statement; the evidence table only when accounts were supplied, otherwise one "Evidence:" line asking for them.
4. ## Filters Used: shared filters, then one row per role family with title and notTitle.
5. ## Count Check: one table holding every count and benchmark (Call, Result, Decision). No separate market-size table.
6. ## Account Tiers when tiering was asked for: rows summing to a Total row, then Movers and Capacity lines.
7. ## Pull Funnel and ## Validation Results with the Fit sample line, run report only. A plan carries no projected funnel or bucket shares.
8. ## Cost Estimate ending in a "Prices: ... checked YYYY-MM-DD" line.
9. ## Output Schema: columns with one example each. No sample-rows section.
10. ## Next Steps: a table with Step, Owner (You, Agent, a named role), Date and Done when. In a plan this table is the run plan.

Economy rules: each figure appears once (the Answer points to a section instead of repeating its numbers); every outside number names its source and date on first mention; assumed rates carry no causal story; no internal tool ids, file paths or skill names (describe the action: "import to the sequencer with cross-campaign duplicate checking on"); file names only in a run report; no value left as "you set" when a sourced default or a Next Steps row can carry it; no framework lists, self-graded checklists or legal commentary.

Quality Check

• ## Answer is the first section and answers every question the user asked.
• The Status line is the only place that says nothing ran.
• Every number is a live result, a sourced figure with its date, or arithmetic on those.
• Companies are counted by deduping company_domain (run) or from SUSB (plan), never title proxy x assumed ratio.
• The economic-buyer family includes Owner, Founder and Managing Partner with their notTitle guards.
• Hourly-workforce industries: the below-floor band was counted and admitted only by site-stated headcount.
• Look-alike business models were checked on each company's site, with the URL recorded.
• Tier rows sum to the Total; no spend ceiling without a "Deal inputs (from you):" line.
• Run report: funnel rows add up, buckets sum to the total validated, the send file is 100% valid.
• Every Next Steps row has an owner and a date.
• scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• tam-builder to size and score a whole market at company level.
• decision-maker-finder when the user already has the account list.
• account-researcher for briefs on the Tier 1 accounts.
• signal-triggered-outbound for the movers: new sites, new leaders, hiring.
• cold-email-list to format the send file for one sequencer's import.
• email-list-cleaner to re-validate an older export of this list.
• crm-enricher to push the result into HubSpot or Pipedrive.
• scrapercity-lead-database for every Lead Database parameter in depth.
• cold-email-strategy for what to send once the list is ready.