Skip to content
OnFire OnFire Docs

ai_prospecting

Trigger a live AI Prospecting request — either rank likely buyers or champions at one or many target companies (action="run"), or score a single named person within a company context (action="get_prospect").

When to use it

Section titled “When to use it”
  • “Find buyers at Acme.” → action="run".
  • “Run prospecting on these 30 companies.” → action="run" (batch).
  • “Is Jane Doe at Acme worth pursuing?” → action="get_prospect".
  • After editing your schema with manage_ai_prospecting, test the draft with activate_shadow_run=True.

Don’t use this for identity resolution alone (use match_company / match_person) or for emails / phones (use contact_data_enrichment).

Inputs (action = run)

Section titled “Inputs (action = run)”
ParameterTypeRequiredDescription
action"run"YesWhich sub-action to perform.
linkedin_urlsstring[]Yes*Company LinkedIn URLs. Takes precedence over company_linkedin_url.
company_linkedin_urlstringYes*Shortcut for a single target company.
use_cachebooleanNoReturn cached results if a recent identical run exists. Default false.
activate_shadow_runbooleanNoRun against the caller’s shadow schema. Ignored while impersonating tenants.
run_idsnumber[]NoOn a retry after still_running, pass back the run ids to skip re-POSTing.
include_field_glossarybooleanNoLegacy opt-in to inline the field glossary. Prefer ai_prospecting_field_glossary.
target_tenant_idstringNoSuper tenants only.

* One of linkedin_urls or company_linkedin_url is required.

Inputs (action = get_prospect)

Section titled “Inputs (action = get_prospect)”
ParameterTypeRequiredDescription
action"get_prospect"YesWhich sub-action to perform.
company_linkedin_urlstringYesTarget company’s LinkedIn URL.
person_linkedinstringYesTarget person’s LinkedIn URL.
target_tenant_idstringNoSuper tenants only.

Returns

Section titled “Returns”

action="run" is asynchronous (runs take 1–3 minutes). The MCP server polls internally and returns either:

  • A completed envelope with a dataset handle plus agent-facing accelerators:
    • top_picks — the ranked “start here” subset with tier, warm-intro path, and ready-made talking points.
    • priority_summary — count histograms (tier 1 prospects, platinum/gold warm intros, alumni, tech champions).
    • preview_rows — up to ~5 projected prospect rows for a sanity check.
    • facets — distribution histograms over tier, warm-intro tier, alumni flag, persona tags, per-company breakdown.
    • field_index — the sorted list of every field name in the response.
    • field_glossary_resource_uri — MCP resource URI for the full field contract (auto-loaded by supporting clients).
  • A still_running envelope with companies and run_ids. Call again with the same run_ids to resume polling without re-POSTing.

action="get_prospect" returns a single projected prospect inline (no dataset).

Notes & limits

Section titled “Notes & limits”
  • The full prospect list is never inlined — it lives in a short-lived MCP dataset. Use query_datasets to filter / sort / paginate, or describe_dataset for the schema and a head sample.
  • On a still_running retry, prefer passing run_ids back — it skips a redundant POST to Phoenix. Re-calling with the same company_linkedin_url/linkedin_urls also works (server-side dedup short-circuits) and never produces duplicate runs.
  • Projected rows are limited to identity, ranking + tier, persona classification, warm-intro path, signals + outreach payload, career-momentum, and narrative reasoning. Module internals, all_prospects, and schema internals are never returned.
  • Bold sentinels in ai_reasoning ($$-onfire-bold-$$) are rewritten to plain " before the response leaves the server.
  • To enrich the run’s contacts, hand the run’s dataset_id straight to contact_data_enrichment — no need to rebuild contact dicts.

Example agent prompts

Section titled “Example agent prompts”

“Run AI prospecting for linkedin.com/company/acme and linkedin.com/company/globex. Use the cache.”

“Score Jane Doe at Acme — show me her reasoning summary.”