feat: improve build-list skill score 72% → 90%

skills/build-list/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-list
-description: Build a list of contacts or companies matching specific criteria. Describe what you're looking for in natural language and get a structured, tabular list you can export. Supports filtering by title, seniority, department, industry, company size, location, tech stack, growth rate, and more. Outputs a clean table artifact.
+description: "Build a targeted list of contacts or companies from ZoomInfo matching natural-language criteria. Supports filtering by title, seniority, department, industry, company size, location, tech stack, and growth rate. Outputs a structured, exportable table. Use when the user wants to build a prospect list, generate leads, find people or companies matching specific criteria, or create a sales outreach list."
 ---
 
 # Build List
@@ -10,11 +10,9 @@ Build a targeted list of contacts or companies from ZoomInfo and output as a str
 ## Input
 
 The user will describe what they want via `$ARGUMENTS`. Examples:
-- "CTOs at Series B+ startups in SF with 50-200 employees"
 - "VP of Sales at healthcare companies using Salesforce with 500+ employees"
 - "All SaaS companies in EMEA with $10M-$50M revenue"
 - "Directors of Engineering at companies similar to Datadog"
-- "Marketing leaders at Fortune 500 companies in financial services"
 
 The user may also specify:
 - How many results they want (default: 25)
@@ -30,56 +28,54 @@ The user may also specify:
    - Industry, employee count, revenue, geography, tech stack, company type → company filters
    - Growth rate, funding, rankings → company filters
 
-3. **Resolve all filter values** using `lookup` before searching. This is critical — do NOT guess values. For every filter you plan to use, call `lookup` with the corresponding field name to get the valid values and use the returned `id` values in your search parameters.
+3. **Resolve all filter values** using `lookup` before searching — do NOT guess values:
+
+   ```
+   lookup({ fields: [{ fieldName: "management-levels" }, { fieldName: "industries" }] })
+   ```
+   Use the returned `id` values (e.g., `managementLevel: 4` for "VP") in all search parameters. If a lookup returns no matching values for a filter term, inform the user and suggest alternative terms before proceeding.
 
 4. **Execute the search**:
-   - For **contacts**: Use `search_contacts` with all resolved filters. Sort by `-contactAccuracyScore`. Request up to 100 results.
-   - For **companies**: Use `search_companies` with all resolved filters. Sort by `-employeeCount` or `-revenue`. Request up to 100 results.
+   - For **contacts**: Use `search_contacts` with resolved filters. Sort by `-contactAccuracyScore`:
+
+     ```
+     search_contacts({
+       managementLevel: [4],
+       industryId: [52],
+       employeeCount: ["501-1000", "1001-5000"],
+       sortBy: "-contactAccuracyScore",
+       pageSize: 25
+     })
+     ```
+
+   - For **companies**: Use `search_companies` with resolved filters. Sort by `-employeeCount` or `-revenue`.
    - For **both**: Search companies first, then search contacts at the top results.
 
-5. **Enrich top results** if the search returns limited detail:
-   - Use `enrich_contacts` (batch of 10) or `enrich_companies` (batch of 10) on the top results to fill in emails, phones, and other details.
+   If the search returns zero results, broaden filters (remove the most restrictive one) and retry. Tell the user which filter was relaxed.
+
+5. **Enrich top results** if the search returns limited detail — use `enrich_contacts` or `enrich_companies` (batch of 10) to fill in emails, phones, and other details.
 
-6. **Output as a clean table artifact.** Create a markdown or CSV artifact the user can copy or export.
+6. **Output as a clean table artifact** the user can copy or export.
 
 ## Output Format
 
 ### Search Criteria Applied
 
-Show the user exactly what filters were used so they can verify:
-
-| Filter | Value |
-|--------|-------|
-| Management Level | Vice President |
-| Industry | Computer Software |
-| Employee Count | 51-100, 101-250 |
-| Metro Region | San Francisco-Oakland-Hayward, CA |
-| ... | ... |
+Show the exact filters used so the user can verify (table of Filter → Value).
 
-### Contact List (if contact search)
+### Results Table
 
-| # | Name | Title | Company | Email | Direct Phone | Accuracy | Location |
-|---|------|-------|---------|-------|-------------|----------|----------|
-| 1 | | | | | | | |
-| 2 | | | | | | | |
+For **contacts**: `# | Name | Title | Company | Email | Direct Phone | Accuracy | Location`
 
-### Company List (if company search)
-
-| # | Company | Industry | Employees | Revenue | HQ Location | Website | ZoomInfo ID |
-|---|---------|----------|-----------|---------|-------------|---------|-------------|
-| 1 | | | | | | | |
-| 2 | | | | | | | |
+For **companies**: `# | Company | Industry | Employees | Revenue | HQ Location | Website | ZoomInfo ID`
 
 ### List Summary
+
 - **Total results found**: X (showing top Y)
-- **Filters applied**: [summary]
+- **Filters applied**: brief summary
 - **Average accuracy score**: X (contacts only)
-- **Data quality**: Flag any concerns (low accuracy, stale records)
+- Flag any data quality concerns (low accuracy, stale records)
 
 ### Refinement Options
-If the list is too broad or too narrow, suggest specific filter adjustments:
-- "Add `revenue` filter to narrow from 847 to ~200 results"
-- "Remove metro region filter to expand from 12 to ~150 results"
-- "Try adjacent industries: Information Technology Services, Internet"
 
-If the user wants to iterate, they can re-run with adjusted criteria. Suggest the exact modified command.
+If the list is too broad or narrow, suggest specific filter adjustments — e.g., "Add `revenue` filter to narrow from 847 to ~200 results" or "Try adjacent industries: Information Technology Services, Internet". Suggest the exact modified command for re-running.