AI Prospecting

ai_prospecting (atomic)

Phoenix is the prospecting engine. This tool answers ONE question — "who are the best prospects (likely buyers / champions) to approach at this ACCOUNT?" — and lets Phoenix's model decide who. It ranks prospects for a company via the single action action="run". It is not a people search and has no single-person scoring path.

When to use this

• The user wants buyers / champions / a "who should I talk to" list at a company.
• A batch run across many companies (still uses action="run").
• In short: the user asks the engine to surface the best prospects for an account and leaves the who up to the model.

Don't use this for identity resolution alone (use match-company / match-person) or for emails / phones (use contact-data-enrichment).

When NOT to use this — vs ask_onfire

ai_prospecting is account-level ranking only. It is the wrong tool when the user has already decided which people they want, or names one specific person:

• The user specifies WHICH people by deterministic criteria — a title, seniority, persona, location, or technology (e.g. "get me the top-level CISOs at Microsoft", "VPs of Security at US banks", "data engineers at Stripe"). That is a filter query → route to the ask_onfire tool over the contact entity, NOT ai_prospecting. Phoenix doesn't take title/seniority/persona filters; if you feed it one you'll get its own ranked picks, not the filtered set the user asked for.
• The user names ONE specific person and asks if they're worth pursuing ("is Jane Doe worth a meeting?"). ai_prospecting has no path for this — there is no single-person scoring. Do not use it.
• Identity / LinkedIn URL resolution → match_company / match_person.
• Emails / phones → contact_data_enrichment.

Litmus test: if the request names the people or their criteria → ask_onfire. If it asks the engine to surface the best prospects for an account → ai_prospecting.

Inputs you need first

action="run" requires a company LinkedIn URL (one, or a batch list).

If you don't have it, run the upstream atomic first:

• Missing company LinkedIn → match-company.

action="run" — rank prospects for a company

Pass either a single URL or a batch list.

# Single company
ai_prospecting(action="run", company_linkedin_url="https://linkedin.com/company/pathwatch")

# Batch
ai_prospecting(action="run", linkedin_urls=[
    "https://linkedin.com/company/pathwatch",
    "https://linkedin.com/company/frostbyte",
    ...
])

linkedin_urls (list) takes precedence over company_linkedin_url (single) when both are passed.

Optional flags:

• use_cache=True — let Phoenix return cached results from a recent identical run instead of recomputing. Use only when it's clearly a re-run of something already executed in this conversation. Default False.
• activate_shadow_run=True — run against the caller's shadow schema instead of the live team schema. Use when the user is iterating on schema config via manage-ai-prospecting. Default False. 404 from this means there is no shadow yet — call create_shadow first via manage-ai-prospecting.

The polling pattern (don't skip this)

Phoenix runs can take a few minutes. The MCP server polls Phoenix internally and may return:

{"status": "still_running", "message": "...", "companies": ["..."], "run_ids": [24685]}

When you see this, call the tool again. Two equivalent options:

1. Preferred — pass run_ids back: ai_prospecting(action="run", run_ids=[24685]). Skips the redundant POST to Phoenix and polls the existing run directly via GET /v1/prospecting/runs/{run_id}. Use this whenever the previous response surfaced run_ids.
2. Identical arguments: ai_prospecting(action="run", company_linkedin_url="...") (same as the first call). Phoenix's server-side dedup picks up the in-flight run row and returns the same run_id. Slightly more network, same outcome.

Either path is safe — the server never creates a duplicate public.runs row. Keep calling until you get a status="completed" payload back. If you change company_linkedin_url or linkedin_urls between polls, that's a new request for a different company, not a retry.

On the very first response (before any run_ids are known), you may instead see:

{"status": "still_running", "message": "...", "companies": ["..."]}

— no run_ids yet because the start request itself didn't return in time. Retry with identical arguments; the next call will pick up the in-flight row and surface its run_ids.

Output shape (action="run", completed)

The server picks one of two shapes based on the size of the filtered prospect set:

• Inline shape — when filtered_prospects ≤ 20 (small runs, the common case for single-company prospecting) or when the serialized rows fit the byte budget. Every prospect ships in a prospects array with the full broad column set on each row. The agent renders every row directly and does NOT call query_datasets. The dataset is still created so download_dataset and contact_data_enrichment keep working uniformly.
• Preview shape — when both row-count and byte thresholds are exceeded. top_picks carries the ranked "start here" subset (5 rows by default), preview_rows carries the next slice in scored order, and the remaining prospects live in the dataset. Both top_picks and preview_rows carry the full broad column set on each row — the agent renders both with the same prospect-card template, then pulls the rest via query_datasets("SELECT *…") if needed.

The whole prospect set is also persisted as a short-lived MCP dataset (auto-expires) so the response is intentionally compact on preview shape; on inline shape the response itself is the deliverable and the dataset is just for download / enrichment hand-off.

The response is self-describing — but the full contract lives outside the response by default. Every completed-run payload includes:

• field_index — the sorted list of every field name documented in the glossary. This is your safety-net check: if every field you encounter in the response is in field_index, you already have the contract loaded; if you see something new, the schema has evolved and you should re-fetch.
• field_glossary_resource_uri — pointer to the full glossary (onfire://ai_prospecting/field_glossary).
• field_glossary — only present when the caller passed include_field_glossary=True on the call (legacy path; see below).

The full glossary (~12 KB JSON) is reachable three ways, all backed by the same in-memory dict so they never drift:

1. ai_prospecting_field_glossary tool (recommended). Zero-argument MCP tool that returns the glossary JSON. Call it once before — or right after — your first ai_prospecting run this conversation. Works on every MCP client.
2. As an MCP resource at onfire://ai_prospecting/field_glossary. MCP clients that support resource injection (auto-loading server-attached metadata into the agent's context at session start) will pick this up automatically — you'll see the contract in your available context without making any explicit call.
3. Legacy inline opt-in via include_field_glossary=True on an ai_prospecting call. Still supported for backward compatibility but no longer the preferred path — it couples glossary fetching to a run call, which makes it awkward when you want the contract before deciding what to run. Prefer ai_prospecting_field_glossary instead.

Decision tree for the agent:

Is the glossary already in your context (resource auto-loaded by the host)?
├── Yes  → proceed normally; rely on field_index to detect drift
└── No   → call ai_prospecting_field_glossary() ONCE this conversation.
           After that, omit the call and rely on field_index to confirm
           nothing new appeared.

The content is byte-stable within a server version, so re-fetching mid-conversation is pure waste. One call per conversation is the cap.

The glossary is the source of truth for field semantics; this skill is the playbook for using them.

{
  "status": "completed",
  "dataset": {
    "id": "ds_abc123…",
    "source": "ai_prospecting",
    "row_count": 42,
    "columns": ["FULL_NAME", "LINKEDIN_URL", "TITLE_NAME", "HEADLINE", "LOCATION_COUNTRY", "LOCATION_REGION", "COMPANY_NAME_DISPLAY", "COMPANY_LINKEDIN_URL", "CURRENT_PERSONAS", "prospect_tags", "WORKED_IN_CLIENT_COMPANY_IN_PAST", "CONNECTING_EMPLOYEE_NAME", "product_talking_points", "ai_reasoning", "..."],
    "schema": [{"name": "FULL_NAME", "type": "string"}, ...],
    "created_at": "...",
    "expires_at": "...",
    "facets": { "WORKED_IN_CLIENT_COMPANY_IN_PAST": {"true": 5, "false": 37}, "CURRENT_PERSONAS": {...}, ... }
  },
  "top_picks": [ /* "start here" top 5 in Phoenix's native best-first order, each row carrying the full broad column set */ ],
  "priority_summary": {
    "existing_customer_alumni": 5,
    "with_named_connector": 39
  },
  "preview_rows": [ /* up to 5 already-projected full prospect rows, in returned order */ ],
  "facets": { "WORKED_IN_CLIENT_COMPANY_IN_PAST": {...}, "prospect_tags": {...}, "CURRENT_PERSONAS": {...}, "COMPANY_LINKEDIN_URL": {...} },
  "total_prospects": 67,
  "filtered_prospects": 42,
  "ranking_method": "individual",
  "message": "Full AI prospecting results (42 prospect(s)) are available via query_datasets / describe_dataset using dataset_id='ds_abc123…'. Use top_picks for a \"start here\" subset and priority_summary for the alumni / named-connector counts at a glance."
}

top_picks (preview shape only — the "start here" subset)

Top-N projection in Phoenix's native best-first order — Phoenix already returns rows ranked by its model (warm-intro path, persona fit, momentum and the rest weighed internally); the scores themselves are not exposed. Each top-pick row carries the full broad column set — identity, CURRENT_PERSONAS, prospect_tags, the full warm-intro path, career-momentum signals (MONTHS_SINCE_LAST_PROMOTION, BUDGET_MANAGEMENT_EXPERIENCE), PAST_COMPANIES_USED_CLIENT_TECH, signals / events / product_talking_points, and ai_reasoning (cleaned, markdown-bolded).

Render every row in top_picks as a complete prospect card using the canonical template above — not a one-line paraphrase. Top_picks is the "start here" set; if filtered_prospects > 5 (or whatever the configured _TOP_PICKS_COUNT is), preview_rows carries the next rows in returned order and the dataset has the rest.

priority_summary (the BDR-facing lede)

Pre-computed counts that let you write the one-line summary without re-reading every row. Exactly two keys:

• existing_customer_alumni — prospects who used to work at the client company (the highest-value expansion signal).
• with_named_connector — prospects who have a named warm-intro connector you can ping.

Paraphrase naturally, e.g. "5 alumni and 39 with a named connector — start there." Both values are integers.

preview_rows (preview shape only — the next slice after top_picks)

Up to 5 full projected prospect rows in returned (best-first) order (same broad column set as top_picks). Render every row with the same prospect-card template — preview_rows is not a "sanity-check sample" to glance at, it's the rows immediately after the top_picks subset and deserves the same treatment.

prospects (inline shape only — every row, every field)

Present when filtered_prospects ≤ _SMALL_RUN_INLINE_THRESHOLD or when the serialized rows fit the byte budget. Array of every filtered prospect with the full broad column set. Render each row with the canonical card template. Do not call query_datasets on this shape — every field for every row is already in your context; the dataset_id exists only for download/enrichment hand-off.

Full projected field set

Each prospect row in the dataset (and in preview_rows) carries the broad field set Phoenix exposes — identity, persona classification, warm-intro path, signals + ready-made talking points, career momentum, and narrative reasoning. Rows arrive in Phoenix's native best-first order; the model's internal scores are not exposed. Notable named fields:

No score fields are returned — there is no rank_position, no MASTER_SCORE_*, no COMPOSITE_SCORE or sub-scores, no relevancy_reasoning or should_filter_reason. Take rows in the order Phoenix returns them.

Don't promise fields outside this set — no emails, no phones, no full tenure history. If the user asks for emails/phones, that's contact-data-enrichment.

If Phoenix returns zero prospects the response is the same shape with dataset: null, top_picks: [], priority_summary: {}, and preview_rows: [].

failed_companies (always present on action="run") is a list of any company URLs that failed during the batch fan-out — each entry has linkedin_url, error, and status_code (when the failure came back as an HTTP error from Phoenix). On a fully-successful run it's []. If the user passed N URLs and some are listed here, mention them — those companies were not prospected. If every URL failed, the tool returns status="error" with the same failed_companies list and no dataset.

Working with the dataset

The full ranked list lives in the dataset, not in preview_rows. Use the dataset companion tools to inspect or slice it without paying its context cost:

• describe_dataset(dataset_id) — schema + a head sample. Good first call before writing SQL.
• query_datasets({alias: dataset_id}, sql, row_limit=N) — read-only DuckDB SQL against the dataset. Filter, count, slice, or pull a specific page.
• download_dataset(dataset_id) — mint a short-lived URL the user can click to download the dataset as CSV. Use whenever the user asks for the file ("send me the CSV", "download the results", "export this", "give me the spreadsheet"). Surface the returned download_url directly in the chat — that link IS the deliverable.
• list_datasets() — surface earlier datasets from this conversation (e.g. to compare a live run vs a shadow run).

Useful patterns:

# Top 20 prospects, ranked
query_datasets(
    datasets={"p": "ds_abc123"},
    sql="SELECT * FROM p LIMIT 20",
    row_limit=20,
)

# Just US-based engineering leads
query_datasets(
    datasets={"p": "ds_abc123"},
    sql="""
        SELECT FULL_NAME, TITLE_NAME, LINKEDIN_URL, ai_reasoning
        FROM p
        WHERE LOCATION_COUNTRY = 'US'
        AND TITLE_NAME ILIKE '%engineer%'
        LIMIT 50
    """,
    row_limit=50,
)

# How are prospects spread across companies in a batch run?
query_datasets(
    datasets={"p": "ds_abc123"},
    sql="""
        SELECT COMPANY_LINKEDIN_URL, COUNT(*) AS prospect_count
        FROM p
        GROUP BY COMPANY_LINKEDIN_URL
        ORDER BY prospect_count DESC
    """,
)

facets on the response are pre-computed distribution counts over the prioritization-driving dimensions: WORKED_IN_CLIENT_COMPANY_IN_PAST (alumni count), prospect_tags (which product/category tags appear), CURRENT_PERSONAS (persona match distribution), and COMPANY_LINKEDIN_URL (per-company breakdown for batch runs). Use these for quick "what's the shape of this run?" answers without a query_datasets round-trip. There are no score-based facets — Phoenix's internal scores aren't exposed. Location facets were intentionally removed — LOCATION_COUNTRY/LOCATION_REGION are still per-row fields in the dataset but aren't what a BDR prioritizes on; if a user really wants a geographic breakdown, run query_datasets with GROUP BY LOCATION_COUNTRY.

ai_reasoning is already display-ready

The MCP server now converts the $$-onfire-bold-$$ sentinel pairs to markdown **bold** on the way out, and strips obvious LLM JSON-leak fragments (text_before, stray "},{evidence:[...] chunks) before the response reaches you. Render ai_reasoning verbatim — don't paraphrase, don't strip the bullets, don't drop the quoted evidence. The bullets are structured as - [summary] / - [buyer] / - [technical] / - [warm] / - [receptive] with markdown bold around emphasized phrases and quoted evidence captured between literal " quotes.

If you ever see a literal $$-onfire-bold-$$ token, that's a stale client; convert each pair to **bold** once and continue. No other escaping is needed.

Default rendering

Two response shapes; pick the right one and render every prospect as a complete card.

• Inline shape — when the response contains a prospects key (every row has the full broad field set). This is the shape for any run with ≤ 20 prospects, or any larger run small enough to fit the inline budget. Don't call query_datasets — every field for every row is already in your context.
• Preview shape — when the response contains top_picks + preview_rows + a dataset handle. top_picks and preview_rows BOTH carry the full broad field set on each row (not the old slim 11-field projection). The remaining filtered_prospects − len(rows-you-have) are in the dataset for follow-up query_datasets calls.

Flat-dumping the rows is the failure mode — that's what generic contact tools produce. Onfire's edge is the pre-computed prioritization layer plus the full evidence-backed reasoning per prospect. Surface both.

Step 1 — Open with the priority_summary lede (one line)

Paraphrase priority_summary into a single BDR-facing sentence before any list. Examples:

"5 alumni connections and 39 with a named warm-intro connector — out of 42 total prospects." "No alumni on this run, but 30 of the 42 have a named connector to reach them through." "All 20 have a named connector; 5 are former employees of the client — start there."

Pick whichever count is highest-signal for the run. Order of preference: existing_customer_alumni > with_named_connector. If both are zero, just give the total count.

Step 2 — Render every available prospect as a full card

On the inline shape, render every row in prospects. On the preview shape, render every row in top_picks and every row in preview_rows (they don't overlap — top_picks is the canonical "start here" subset, preview_rows is the next rows in scored order). For a 9-prospect run that means 9 cards rendered, not 3.

The canonical prospect-card template is below. Every field in the no-drop list must appear in every card you render — if you render it for prospect #1, you render it for prospect #9. Consistency across rows is what separates a real briefing from a head-sample.

Canonical prospect-card template

**N. {FULL_NAME}** — {TITLE_NAME} ({LOCATION_REGION}, {LOCATION_COUNTRY})
[{LINKEDIN_URL}]({LINKEDIN_URL}) · warm intro via {CONNECTING_EMPLOYEE_NAME} ({SHARED_COMPANY})

Persona match: {top three persona names by weight from CURRENT_PERSONAS, e.g. "devsecops 9.2, engineering 9.2, code_contributor 9.2"}.
Career momentum: {MONTHS_SINCE_LAST_PROMOTION} months since last promotion{ · budget management experience if BUDGET_MANAGEMENT_EXPERIENCE = true}.
Past employers with relevant tech: {PAST_COMPANIES_USED_CLIENT_TECH, only if non-empty}.

{ai_reasoning verbatim — five-bullet structure with markdown bold and quoted evidence already in place}

Talking point: {first value from product_talking_points dict, only if non-empty}

If a field is None, empty, or false, drop that one line but keep the rest of the card. Do not collapse the whole card.

Format notes:

• If CONNECTING_EMPLOYEE_NAME is empty, the warm-intro line becomes no warm-intro path available.
• If WORKED_IN_CLIENT_COMPANY_IN_PAST is true, prepend the warm-intro line with **Alumni** — used to work at the client company (highest-value expansion signal).
• CURRENT_PERSONAS is a JSON-encoded list of single-key dicts like [{"engineering": 9.2}, {"devops": 4.6}]. Parse, sort by weight desc, take top 3.

No-drop fields list

These fields are sales-actionable. If they are present on the row, they appear in the rendered card. Never silently drop:

1. FULL_NAME, TITLE_NAME, LINKEDIN_URL, LOCATION_COUNTRY, LOCATION_REGION
2. CONNECTING_EMPLOYEE_NAME + SHARED_COMPANY (the reachability story)
3. WORKED_IN_CLIENT_COMPANY_IN_PAST (alumni flag — call it out explicitly when true)
4. Top 3 personas from CURRENT_PERSONAS with their weights
5. MONTHS_SINCE_LAST_PROMOTION and BUDGET_MANAGEMENT_EXPERIENCE (the "why now" signals)
6. PAST_COMPANIES_USED_CLIENT_TECH (prior-exposure signal — high credibility hook)
7. ai_reasoning verbatim (it is structured + bolded + evidence-quoted already)
8. product_talking_points first entry (Phoenix wrote the opener — don't invent your own)

Step 3 — Tail block (counts + dataset_id)

After the cards, give one concise paragraph: total surfaced → filtered, the alumni / named-connector counts from priority_summary, and the dataset_id. This is the "what's in the rest of the dataset" footer.

Step 4 — Make the enrichment + download offers (next section)

These are still required after every run. See below.

Multi-company / batch runs

The same four-step flow applies, but the lede should mention per-company spread when relevant ("12 prospects across 3 accounts; the alumni connections cluster at Acme"). For a per-company breakdown, the COMPANY_LINKEDIN_URL facet has the counts; for full grouping, query_datasets with GROUP BY COMPANY_LINKEDIN_URL.

Long lists / pagination

On preview shape, after rendering top_picks + preview_rows, pull the remaining rows via query_datasets({"p": dataset_id}, "SELECT * FROM p LIMIT N OFFSET K") — the dataset is already stored in Phoenix's native best-first order, so plain LIMIT/OFFSET paginates in that order (there is no rank_position or score column to sort on). Use SELECT * so you don't silently drop high-leverage fields. Render those rows with the same prospect-card template. If the user wants the file rather than a paged view, call download_dataset(dataset_id) and surface the returned download_url — that's the canonical CSV. For a download of just a slice (e.g. "the first 50"), run the slice through query_datasets(..., persist_as_dataset=True) first to get a new dataset_id, then download_dataset on that.

Worked example — what a rendered prospect card actually looks like

For an Artifex-tenant run against Continental Bank, the third prospect's card should look like:

3. John Doe — SVP, Senior Tech Manager – Application Development (California, United States) linkedin.com/in/johndoe · warm intro via Jane Roe (Continental Bank)

Persona match: engineering 12.2, architect 12.2, devsecops 8.1. Career momentum: 9 months since last promotion · budget management experience. Past employers with relevant tech: acme financial | globex bank | initech.

• [summary] A strategic technology leader with extensive experience driving enterprise-scale cloud migrations and building complex integration platforms — "adept at leveraging cutting-edge technologies and building high-performing teams to achieve business objectives." Making him a critical stakeholder for large-scale modernization initiatives.
• [buyer] He has proven oversight of major legacy-to-vendor migrations valued at hundreds of millions of dollars and designed custom integration services — "Successfully oversaw the migration of a large in-house legacy servicing platform worth $250 million to a vendor solution" — "Designed and patented a custom data-integration service on an internal platform." Demonstrating his capacity to manage high-stakes budgets and lead complex architectural integrations.
• [technical] His technical background spans the modernization of core applications using OpenShift and Kafka while integrating disparate systems via an internal platform — "Leading cloud migration of internal applications to RHEL, OpenShift Container Platform" — "Building a new integration platform leveraging Kafka and a modern event-driven stack." Highlighting his deep hands-on expertise.
• [warm] He maintains a professional connection to Artifex through Jane Roe, with whom he overlapped for 45 months as a senior leader at Continental Bank.

Talking point: Artifex Registry's binary repo + SBOM management for OpenShift-deployed core bank applications.

This is what every card should look like — not a one-line summary, not a paraphrase, not a "see ai_reasoning for details." If you render this for the top 3, you render it for prospects 4 through 9 too.

The enrichment offer (required, not optional)

After every run — single run or batch run, no matter what — tell the user they can pull verified emails and phones for any of the returned prospects. Not just the top N you displayed in preview_rows; all of them are available to enrich. Most of the workflow's value is downstream of contact data, and users frequently assume contact data is gated to whatever's on screen.

Phrase it naturally:

"I can pull verified emails and phone numbers for any of these — top 5, all 42, or a subset you pick. Just say which."

The dataset_id from the run can be passed straight to contact_data_enrichment(dataset_id="ds_…", ...) to enrich the entire run set without rebuilding contact dicts; for a custom subset, build dicts from the rows the user picked. See contact-data-enrichment.

Every run's dataset already carries LOCATION_COUNTRY, so pass location_country_column="LOCATION_COUNTRY" on the enrichment call — tenants on geo-based waterfalls use it to pick a region-specific provider order, and it costs you nothing here since the column is already in the rows. Keep it on the LOCATION_COUNTRY key when you build dicts for a user-picked subset too.

This is part of the playbook, not a polite extra.

The download offer (also required)

In the same breath as the enrichment offer, mention they can grab the full ranked list as a CSV. Most users want the file — preview_rows is a smell test, not the deliverable.

"I can also send you the full -row CSV — say the word and I'll drop a download link."

If the user already asked for a file (any phrasing — "send", "export", "download", "give me the spreadsheet"), skip the offer and just call download_dataset(dataset_id). Surface the returned download_url directly. The link is short-lived (default 1 hour, max 24 hours), so don't sit on it.

Hard rules

• Never pass target_tenant_id. Tenant comes from OAuth. The override is super-tenant only and will error for everyone else.
• Polling is mandatory — {"status": "still_running"} means call again, preferably with run_ids from the response (or identical args if no run_ids are present yet).
• Don't invent fields outside the projected set. The dataset carries the field set documented in the table above — no emails, no phones, no full tenure history, and no score fields (rank_position, MASTER_SCORE_*, COMPOSITE_SCORE and the like are not returned). If the user asks for emails/phones, route to contact-data-enrichment.
• Take rows in returned order. Phoenix returns prospects already in best-first order; there is no score or rank_position column to sort or paginate on. Don't tell the agent to sort by a score.
• Render every available row as a full prospect card. On inline shape, render every prospect. On preview shape, render every row in top_picks and preview_rows. Drop a card-line only when its underlying field is null/empty — never silently skip a no-drop field on row 4 that you showed on row 1. Consistency across rows is the contract.
• Render ai_reasoning verbatim. Server already converts the $$-onfire-bold-$$ sentinels to markdown bold and strips JSON-leak artifacts. Don't paraphrase the bullets into a one-liner — that's where the evidence quotes live.
• Use the named warm-intro connector. If CONNECTING_EMPLOYEE_NAME is populated, name them; that's the introduction path.
• Don't try to re-fetch the full prospect list by re-running. Use the returned dataset_id with query_datasets / describe_dataset instead — it's free, fast, and doesn't trigger a Phoenix run.
• Don't set use_cache=True unless it's plausibly a re-run of something already executed this session.
• activate_shadow_run=True only when the user is iterating on schema (and a shadow exists).

Common pitfalls

• Rendering only the top 3-5 and stopping. The biggest failure mode and the one that triggered this skill's last rewrite. If the run returned 9 filtered prospects, you render 9 cards — not 3 with a "I can pull more anytime" footer. On inline shape every row is in your context; on preview shape top_picks already has the ranked subset plus preview_rows for the next slice. The user asked for a prospect list, give them the prospect list.
• Rendering some fields for the top prospects and dropping them for the rest. If row 1 has score breakdown + persona match + career-momentum + past tech employers, then rows 2–N have the same lines (where the underlying data is present). Inconsistency across rows reads as sloppiness and signals the model gave up partway through.
• Paraphrasing ai_reasoning into a one-liner. The five-bullet structure with quoted evidence is the differentiator — that's what makes Onfire's output a briefing rather than a contact dump. Render verbatim, don't summarise.
• Inventing opener prose when product_talking_points exists. Phoenix already wrote product-specific openers per prospect. Use them. Don't paraphrase ai_reasoning into an opener and pretend you did the work.
• Ignoring the warm-intro path. If CONNECTING_EMPLOYEE_NAME is populated, name them in the output. That's the warm-intro contact the user can ping; burying it inside ai_reasoning is wasteful.
• Missing the alumni callout. WORKED_IN_CLIENT_COMPANY_IN_PAST=TRUE is the highest-value expansion signal in the response. If any row has it, prepend the warm-intro line with the alumni callout.
• Treating still_running as an error. It's the documented async signal. Just call again — pass back the run_ids if present.
• Forgetting to pass run_ids on the retry when they were surfaced. Both paths work (identical args also dedups server-side), but passing run_ids is one round-trip cheaper and signals to the server "I'm resuming, not starting over."
• Treating top_picks or preview_rows as the full list on preview shape. They're the best-first subsets; the rest live in the dataset. Pull more via query_datasets("SELECT * FROM p LIMIT N OFFSET K") (the dataset is already in best-first order) and render with the same card template.
• Re-running ai_prospecting to "see more." Use the dataset tools instead — the run already produced the full list.
• Mixing linkedin_urls and company_linkedin_url. Pick one — linkedin_urls wins if both are set, but it's clearer to use only the one you need.
• Skipping the enrichment offer. It's the single most important post-run behavior; users keep asking "can I get emails?" because we forgot to tell them yes.
• Forgetting the dataset_id + filtered_prospects total in the tail block. Even when you rendered every row, the user needs to know where the file lives.

Worked examples

Single company by name.

1. match-company on "Pathwatch" → linkedin_url
2. ai_prospecting(action="run", company_linkedin_url=<url>)
3. If still_running, call again until status="completed" — pass back `run_ids` from the previous response when present.
4. Detect the shape:
   - response has ``prospects`` → inline shape, render EVERY row.
   - response has ``top_picks`` + ``preview_rows`` → preview shape,
     render every row in both, then pull the rest via
     query_datasets("SELECT * FROM p") if
     filtered_prospects > rows-in-hand and the user wants them all.
5. Open with the priority_summary lede (one line: alumni count,
   named-connector count — whichever is highest-signal).
6. Render every prospect using the canonical card template above. Every
   no-drop field on every card where the underlying value is present.
   ai_reasoning rendered verbatim (markdown bold + quoted evidence
   already in place).
7. Tail block: total surfaced → filtered, alumni / named-connector
   counts from priority_summary, dataset_id.
8. Make the enrichment + download offers.

Deterministic people lookup — NOT this tool.

User: "get me the top-level CISOs at Microsoft"
→ This names the criteria (title/seniority). Route to ask_onfire over the
  contact entity, NOT ai_prospecting. ai_prospecting would return its own
  ranked picks, not the CISO filter the user asked for.

Batch run, 30 accounts.

1. match-company on the list (one call, ≤100 entries) → linkedin URLs.
2. ai_prospecting(action="run", linkedin_urls=[...]) — possibly poll.
3. Lede: priority_summary + per-company spread from the
   COMPANY_LINKEDIN_URL facet. Example: "42 prospects across 8 accounts;
   alumni cluster at 2 of them."
4. Render every row in top_picks + preview_rows as full prospect cards
   (the cross-account "start here" set). If the user wants per-company
   grouping, query_datasets with GROUP BY COMPANY_LINKEDIN_URL.
5. For "show me all 42" requests, query_datasets(
   "SELECT * FROM p") and render each as a card.
6. Offer xlsx / CSV export via download_dataset(dataset_id).
7. Make the enrichment offer.

Drilling in after a run.

1. ai_prospecting(action="run", ...) → dataset_id="ds_abc"
2. User: "Just the alumni ones"
3. query_datasets(
     datasets={"p": "ds_abc"},
     sql="""SELECT FULL_NAME, TITLE_NAME, LINKEDIN_URL,
            CONNECTING_EMPLOYEE_NAME, SHARED_COMPANY,
            ai_reasoning
            FROM p
            WHERE WORKED_IN_CLIENT_COMPANY_IN_PAST = 'TRUE'""",
   )
4. Render the slice (same prioritization rendering as top_picks).
   Re-iterate the enrichment offer.

Enriching the whole run.

1. ai_prospecting(action="run", ...) → dataset_id="ds_abc", filtered_prospects=42
2. User says "get emails and phones for all of them"
3. contact_data_enrichment(
     contacts=[],                       # phase 1: consent (>10)
     total_count=42,
     dataset_id="ds_abc",
     linkedin_url_column="LINKEDIN_URL",
     account_website_column="COMPANY_LINKEDIN_URL",
     person_name_column="FULL_NAME",
   )
4. Show user_facing_message verbatim. Stop. After yes, phase 2 in batches of ≤20 with the same dataset_id + confirmation_token.

Iterating on schema config.

1. manage-ai-prospecting create_shadow / update_shadow per user edits.
2. ai_prospecting(action="run", activate_shadow_run=True, company_linkedin_url=...) → dataset_id_shadow
3. ai_prospecting(action="run", company_linkedin_url=...) (live) → dataset_id_live
4. Compare with query_datasets({"shadow": ds_shadow, "live": ds_live}, "SELECT ...") if useful.
5. Promote with manage-ai-prospecting ship_shadow when satisfied.

What this skill does NOT do

• It doesn't resolve LinkedIn URLs — that's match-company / match-person.
• It doesn't return contact info — that's contact-data-enrichment.
• It doesn't edit schema config — that's manage-ai-prospecting.
• It doesn't analyse the dataset for you — that's query_datasets / describe_dataset (companion tools to the dataset handle).