gtm-mcp

Category: Development & Coding | Uploader: petrNikolaev1 | Downloads: 0 | Version: v1.0（Latest）
Convert natural language segment descriptions into Apollo.io API search filters.
Changelog: Source: GitHub https://github.com/petrNikolaev1/gtm-mcp
Directory Structure

Current level: tree/main/.claude/skills/apollo-filter-mapping/
📄 SKILL.md 14.6 KB
SKILL.md

# Apollo Filter Mapping Skill

Convert natural language segment descriptions into Apollo.io API search filters.

## When to Use

- User provides a gathering query ("find IT consulting companies in Miami")
- After offer extraction produces segments with keywords
- When generating filters for pipeline preview

## Filter Classification

### Mandatory (must have before pipeline starts, ask user if missing)
- **Geo** (locations) — from user query or document
- **Segments** (query describing target companies) — from user query or document

### Inferred (derive automatically, don't ask user)
- **Size** (employee range) — infer from offer context
- **Industries** (Apollo industry tag_ids) — pick 2-3 from 84 real industries with tag_ids
- **Keywords** (free-text search terms) — generate 20-30 freely, informed by seeds

### Prioritization (nice-to-have, graceful degradation)
- **Funding** (series_a, series_b) — from document. Applied when Apollo has data, silently dropped when exhausted

## How Apollo Filters Actually Work

### Two Completely Different Filter Types

**Type A — Industry Tag IDs** (`organization_industry_tag_ids`):
- Uses hex MongoDB ObjectIds (e.g. `5567cdd67369643e64020000`)
- Only **84 industries** have confirmed tag_ids (from real Apollo data)
- BEST pagination quality in Apollo — most reliable results per page
- Each tag_id in a SEPARATE parallel API request

**Type B — Keywords** (`q_organization_keyword_tags`):
- Accepts ANY free-text strings — no validation, no predefined list
- Apollo OR-combines keywords within a single request
- Generate with LLM, use natural language, product names, anything
- Industry names WITHOUT tag_ids (banking, biotechnology, insurance, etc.) go here as keywords

### The Cardinal Rule

**NEVER combine `organization_industry_tag_ids` with `q_organization_keyword_tags` in the same API request.**

Apollo ANDs filters across types. Combining narrows results catastrophically — often returns 0. Use ONE or the OTHER per request, run both types as parallel streams.

**Base filters** (locations, employee_ranges, funding_stages) combine safely with EITHER type:
```
KEYWORD REQUEST:  {"q_organization_keyword_tags": ["..."], "organization_locations": [...], "organization_num_employees_ranges": [...]}
INDUSTRY REQUEST: {"organization_industry_tag_ids": ["..."], "organization_locations": [...], "organization_num_employees_ranges": [...]}
```

### 1 Filter Per Request Rule

Apollo's ranking picks ~100 "best matches" per page. Combining multiple keywords or multiple tag_ids in one request distorts ranking:

| Strategy | Unique Domains | Credits |
|----------|---------|---------|
| Each keyword alone (10x5p) | **930** | 50 |
| All 10 together (1x5p) | **126** | 5 |
| Single-only (missed by together) | **904** | — |

**Rule: 1 keyword per request, 1 industry_tag_id per request. All in parallel.**

## Seed Data from Example Companies

When user provides example companies (e.g., "companies like nike.com and adidas.com"), enrich them to extract seed data for filter generation.

### Algorithm: `tam_enrich_from_examples`

**Input**: List of example domains (e.g., ["nike.com", "adidas.com", "puma.com"])

**Step 1**: Enrich each domain via `apollo_enrich_companies([domains])` (1 credit per domain)
- Apollo returns per company: `industry`, `industry_tag_id`, `keywords[]`, `employee_count`, `sic_codes`

**Step 2**: Aggregate common patterns (no LLM needed):
- Collect ALL `keywords` arrays across all examples
- Count frequency of each keyword
- Collect ALL `industry_tag_id` values
- Count frequency of each industry

**Step 3**: Keyword prioritization (LLM call):
- From aggregated keywords, filter to keep only segment-relevant ones (max 8)
- Exclude: technology stacks, product names, generic frameworks ("react", "python", "aws")
- Keep: business model descriptors, industry terms, activity descriptors
- Prompt: "Given these are {segment} companies, which keywords describe their BUSINESS (not tech stack)?"

**Step 4**: Industry tag_id prioritization (LLM call):
- From collected industries, select 2-3 most relevant to the segment
- Map back to tag_ids from taxonomy
- Prompt: "Which 2-3 of these industries best represent {segment}?"

**Step 5**: Store as seed_data on project:
```json
{
  "seed_data": {
    "keywords": ["athletic footwear", "sportswear", "fashion brand", ...],
    "industry_tag_ids": ["5567cd82736964540d0b0000", ...],
    "example_domains": ["nike.com", "adidas.com", "puma.com"],
    "source": "examples"
  }
}
```

**How seeds are consumed**: Seeds flow into filter generation (Step B below). The LLM uses seed_keywords as starting point + inspiration for generating 20-30 keywords. Seed industry_tag_ids are merged with LLM-selected tag_ids in Step E.

**Seeds are ADVISORY**: The agent uses them as hints, not hard constraints. For "fashion brands in Italy", seeds from Nike help — but the LLM may ignore "athletic footwear" for a "luxury brands" query.

## Step-by-Step Filter Generation

### Step A: Industry Selection (Tag IDs)

1. Call `apollo_get_taxonomy()` tool → returns `industry_tags` dict (name → hex tag_id)
2. From the 84 industries with tag_ids, pick 2-3 that match the user's query
3. Get the hex tag_ids from the mapping
4. If an industry name you want has NO tag_id → use it as a keyword in Step B instead

**SPECIFIC vs BROAD classification** (determines strategy):
- **SPECIFIC**: industry DIRECTLY matches query, most companies in it ARE what user wants
  - "fashion brands" → "apparel & fashion" → SPECIFIC (tag_id: `5567cd82736964540d0b0000`)
  - "video production" → "media production" → SPECIFIC (tag_id: `5567e0ea7369640d2ba31600`)
  - Rule: if industry name CONTAINS query words → almost certainly SPECIFIC
- **BROAD**: industry is SUPERSET with many irrelevant types
  - "IT consulting" → "information technology & services" → BROAD (includes SaaS, hardware, media)
  - "influencer agencies" → "marketing & advertising" → BROAD (includes PR, publishers)
- **When in doubt**: classify as SPECIFIC (industry search = 90% target rate vs 30-40% for keywords)

**Strategy:**
- `industry_first` if ANY industry is SPECIFIC → industry_tag_ids as primary search stream
- `keywords_first` if all BROAD or no matching industries → keywords as primary search stream
- Both streams always run in parallel regardless of strategy — strategy determines which gets more keywords/pages

### Step B: Keyword Generation + Expansion

Generate 20-30 BASE keywords, then expand to 80-100 total before pipeline starts.

**Base keywords** (20-30): Generated by LLM from query + offer + seeds.

**Expansion to 80-100** (before pipeline starts, add 50-70 more):
- Specific product/platform type names
- Technology terms (PCI DSS, ISO 20022, SWIFT, etc.)
- Use case phrases ("reduce fraud", "automate compliance")
- Buyer search terms ("RFP", "procurement", "vendor selection")
- Include ALL original keywords + 50-70 new ones

Include:
- Industry terms and sub-sectors
- Product/service names specific to the segment
- Technology names, protocols, standards
- Synonyms and alternative phrasings
- Adjacent niches and crossover terms
- Business model descriptors
- Specific platform/tool names

**Industries without tag_ids as keywords**: "banking", "biotechnology", "insurance", "computer software", "internet", "capital markets" — these have no tag_id but work as free-text keyword searches. Include relevant ones in the keyword list.

If seed keywords exist from offer extraction, use them as starting point and inspiration.

**Apollo keyword behavior (verified live):**
- `q_organization_keyword_tags` accepts ANY free-text strings
- Multiple keywords are OR-combined — expands the pool
- BUT: More keywords changes Apollo's RANKING, not just adds to list
- Running PARALLEL streams with DIFFERENT keywords yields MORE unique companies than one combined stream

### Step C: Location Extraction

Extract locations from the query. Common patterns:
- "in Miami" → "Miami, Florida, United States"
- "in US and UK" → ["United States", "United Kingdom"]
- "in DACH" → ["Germany", "Austria", "Switzerland"]
- "in Nordics" → ["Sweden", "Norway", "Denmark", "Finland"]

Document locations OVERRIDE query locations if both provided.

### Step D: Employee Size

Infer from offer context (see offer-extraction skill for mapping table).
Apollo formats: "1,10", "11,50", "51,200", "201,500", "501,1000", "1001,5000", "5001,10000", "10001,"

### Step E: Seed Data Merge

If project has seed_data (from offer extraction or example companies):
- Merge seed_data.keywords with generated keywords (dedup)
- Merge seed_data.industry_tag_ids with selected tag_ids (union)

### Auto-Taxonomy Extension

When enriching companies or people via Apollo, new `industry_tag_id` values may appear. The `apollo_enrich_people` and `apollo_enrich_companies` tools auto-extend `industry_tags.json` with newly discovered mappings. Call `apollo_get_taxonomy()` again to get the latest.

## Filter Dispatch — What Gets Sent to Apollo

The generated filters are NOT one API call. They are dispatched as PARALLEL STREAMS:

```
BASE FILTERS (always applied):
  organization_locations: ["United States"]
  organization_num_employees_ranges: ["51,200", "201,500"]

KEYWORD STREAM — 1 keyword per request, all in parallel:
  Request 1: {"q_organization_keyword_tags": ["payment gateway"], ...base}
  Request 2: {"q_organization_keyword_tags": ["PSP platform"], ...base}
  Request 3: {"q_organization_keyword_tags": ["checkout integration"], ...base}
  ...up to 85 keyword requests

INDUSTRY STREAM — 1 tag_id per request, all in parallel:
  Request 1: {"organization_industry_tag_ids": ["5567cdd67369643e64020000"], ...base}
  Request 2: {"organization_industry_tag_ids": ["5567cd4773696439b10b0000"], ...base}
  ...2-3 industry requests

FUNDED VARIANTS (if funding available, run simultaneously):
  Every keyword request ALSO runs with funding filter added
  Every industry request ALSO runs with funding filter added
  → Doubles the number of parallel streams
  → Funded companies found first (higher quality, actively scaling)
```

All streams feed a shared dedup set (seen_domains). Stop adding new requests when 400 unique companies reached per round.

## Apollo Probe (Preview Phase)

Before committing credits, probe with separate calls:
- 1 probe per top-3 industry_tag_ids
- 1 probe per top-3 keywords
- Each probe = 1 credit, returns company count + sample companies

Show probe_breakdown to user:
```json
[
  {"type": "industry", "tag_id": "5567cdd67369643e64020000", "name": "financial services", "total": 3200, "companies": 100},
  {"type": "keyword", "name": "payment gateway", "total": 3199, "companies": 85}
]
```

**Apollo total_entries is UNRELIABLE** (reports 3,199-10,179 but returns ~130 in 5 pages). All KPIs use actual deduped company counts.

Probe companies are saved and reused on confirm (skip re-fetching page 1).

## Cost Estimation

**Constants:**
- DEFAULT_TARGET_RATE = 0.35 (35% of Apollo companies are targets)
- DEFAULT_CONTACTS_PER_COMPANY = 3
- EFFECTIVE_PER_PAGE = 60 (Apollo returns ~60 unique per 100 requested)
- APOLLO_COST_PER_CREDIT = $0.01

**Formula:**
1. target_companies = target_count / contacts_per_company (e.g., 100/3 = 34)
2. companies_needed = target_companies / target_rate (e.g., 34/0.35 = 97)
3. pages_needed = ceil(companies_needed / 60) (e.g., 97/60 = 2 pages)
4. search_credits = pages_needed
5. people_credits = target_count (1 per verified email)
6. total = search_credits + people_credits
7. Show: "Default (100 contacts): ~102 credits ($1.02)"

## Funding Filter as Prioritization Layer

When document mentions funding:

```
Level 0 (highest priority): Keywords/Industries + Funding filter
  - ~1,933 companies (funded pool). High quality, actively scaling.
  - FIXES Apollo's sparse pagination issue
  - 10 consecutive empty pages = exhausted → drop funding

Level 1: Keywords/Industries WITHOUT funding
  - ~43,212 companies BUT sparse pagination (0 per page!)
  - Will exhaust quickly

Level 2+: Keyword regeneration, industry fallback
```

**CRITICAL FINDING** (tested 2026-04-02): Funding filter FIXES Apollo's sparse pagination. Without funding, Apollo returns 0 results per page despite 43K total. With funding, returns 20+ per page. Funding is essential when available.

## Concentric Circles Model

For keyword generation, think in expanding circles:
- **CORE**: Exact match (payment gateways → "payment gateway API")
- **ADJACENT**: Related sub-sector (payment gateways → "merchant acquiring", "checkout platform")
- **PERIPHERAL**: Broader ecosystem (payment gateways → "financial infrastructure", "fintech SaaS")

Generate keywords at all three levels for maximum coverage.

## 84 Apollo Industries With Tag IDs

Call `apollo_get_taxonomy()` to get the live mapping. Below is the reference list — use EXACT names for tag_id lookup:

**Technology & Computing:**
computer & network security, computer games, computer hardware, electrical/electronic manufacturing, information technology & services, semiconductors, telecommunications

**Business Services:**
consumer services, executive office, facilities services, human resources, management consulting, marketing & advertising, public relations & communications, security & investigations, translation & localization

**Finance & Investment:**
financial services, fund-raising, venture capital & private equity

**Healthcare & Science:**
health, wellness & fitness, hospital & health care, medical devices, mental health care, pharmaceuticals, research, veterinary

**Manufacturing & Industry:**
automotive, building materials, chemicals, civil engineering, construction, glass, ceramics & concrete, machinery, mechanical or industrial engineering, mining & metals, oil & energy, packaging & containers, paper & forest products, textiles, utilities

**Media & Entertainment:**
animation, design, entertainment, media production, music, online media, photography, publishing, sports

**Government & Nonprofit:**
defense & space, government administration, government relations, international affairs, international trade & development, law enforcement, libraries, military, museums & institutions, nonprofit organization management, political organization, religious institutions, think tanks

**Education:**
e-learning, education management, higher education

**Real Estate & Construction:**
architecture & planning, real estate

**Food & Hospitality:**
food & beverages, food production, hospitality, restaurants

**Transport & Logistics:**
airlines/aviation, aviation & aerospace, logistics & supply chain, package/freight delivery, railroad manufacture, transportation/trucking/railroad

**Legal:**
law practice, legal services

**Retail & Consumer:**
apparel & fashion, luxury goods & jewelry, retail

**Other:**
alternative dispute resolution, environmental services, gambling & casinos
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
gtm-mcp

Directory Structure

SKILL.md

Report

Notice
