Prospect Engine MCP Server

Run Prospect Engine

run_prospect_engine

Idempotent

Run B2B prospecting workflows: enrich companies, discover hiring signals, find contacts, or chain all three with ICP scoring into one flat, Clay-ready table.

Instructions

A composed prospecting actor with four modes. enrich_companies resolves identity, firmographics, LinkedIn and social for each domain or company name you supply, and needs no vendor key at all. discover_jobs finds who is hiring for your keywords and resolves the real employer behind each posting, including postings a job board placed on an employer's behalf. find_contacts finds people at the companies you name, with optional email discovery and verification. full runs discovery, enrichment, ICP scoring and then contact discovery, passing only the companies at or above min_icp_score through to the contact stage. Every row comes back flat and Clay ready with per field provenance. Vendor keys are yours: you supply them, those vendors bill you directly, and the per event price covers the actor only. discover_jobs and full require a SerpApi key, which is a different vendor from the Serper key that powers people search. Use it when you need companies, hiring signals, or contacts in one flat table. Do not use it to verify a single email you already have (that is the Work Email Waterfall) or to score a list you already enriched (that is the ICP Fit Scorer). Cost controls: max_results and max_pages bound discovery, target_contacts bounds contacts per company, target_roles skips paid lookups for non-matching contacts, and max_spend_usd caps your own vendor spend. Requires an APIFY_TOKEN and consumes Apify credits. Read only: it enriches and discovers, it writes nothing.

Input Schema

Name	Required	Description
`mode`	No	What to run. enrich_companies resolves identity, firmographics, LinkedIn and social for each company. discover_jobs finds who is hiring for your keywords and resolves the real employer from the job description. find_contacts finds people at each company. full chains all three. Default: "enrich_companies".
`country`	No	Two letter country code for job search, for example us or gb. Default: "us".
`domains`	No	One domain per line. Used by enrich_companies and find_contacts.
`keywords`	No	Roles to search for. Used by discover_jobs and full. Example: copy editor, proofreader, content editor. Default: ["copy editor", "proofreader", "content editor"].
`location`	No	Optional location filter for job search, for example New York.
`max_pages`	No	1 to 5. Each page is one SerpAPI call, so this is the main cost dial on discovery. Default: "1".
`score_icp`	No	true to score every row against the ICP rules and tier it A to D. Default: "true".
`seniority`	No	c_level, vp, director, manager, senior.
`icp_preset`	No	Which scoring model to apply. "editorial_services" scores for a seller of managed copy editing and proofreading. "generic_b2b" scores on hiring intent, employer resolvability and headcount with no service-specific vocabulary. Default: "editorial_services".
`job_titles`	No	Titles to search for when finding contacts.
`skip_cache`	No	true to ignore the 7 day cross-run cache and recompute everything. Default: "false".
`brand_voice`	No	How the opener should sound. Leave empty and it writes plainly and directly.
`deny_tokens`	No	Whole words that disqualify a contact even when the title matched a target role, for example product refuses Product Owner and keeps Production Editor. Applies even when no target roles are set.
`departments`	No	marketing, sales, engineering, product, finance, hr, operations, legal.
`max_results`	No	Cap on postings returned per run. Keeps a broad keyword set from running away. Default: "25".
`personalize`	No	true to write a one or two sentence opener per contact that has an address, referencing something specific about the company. Needs claude_api_key; skipped without it. Default: "true".
`remote_only`	No	true to keep only postings flagged remote by the board. Default: "false".
`serpapi_key`	No	Your SerpApi key. Required by discover_jobs and full. Distinct from a Serper key: different vendor.
`target_roles`	No	Only enrich contacts whose title plausibly matches one of these roles. Filters after discovery and before any paid email lookup, so a non-matching contact costs nothing. Leave empty to keep every contact the seniority and department filters allow.
`verify_email`	No	true to verify each address. Needs a BounceBan key. Default: "true".
`company_names`	No	One name per line. Used when you have a name but no domain.
`include_email`	No	true to run the email waterfall. Needs an Icypeas or Prospeo key, which you supply and are billed for directly. Default: "false".
`lookback_days`	No	Drop postings older than this many days. Sent as a string because Clay sends every field as a string. Default: "30".
`max_spend_usd`	No	Stop making paid vendor calls once this much of your own vendor spend (Findymail, Icypeas, Prospeo, BounceBan) is committed, and return everything completed so far. Caps your vendor bills, not the Apify charge for this actor. Leave empty for no cap.
`min_icp_score`	No	In full mode, only companies scoring at or above this go on to contact discovery. Default 45: at 25 the filter passed every keyword-discovered editorial posting, because 25 is the floor such a posting can score. Default: "45".
`claude_api_key`	No	Your own Anthropic key, used for position verification and the personalized opener. Both steps are skipped when it is absent. Never stored.
`include_social`	No	true to resolve Facebook, Instagram, X and YouTube alongside LinkedIn. Default: "true".
`max_charge_usd`	No	Optional. The actor's own spend cap for this run, in USD. The run stops before a charge would take its total past this amount, writes one notice row saying so, and keeps every row already charged. Leave it empty for no cap of your own; the maximum cost per run set in Apify is honored either way.
`serper_api_key`	No	Your Serper.dev key. Powers people search in find_contacts, which is the highest-coverage layer. Without it the free fallback is measurably poor.
`icypeas_api_key`	No	Your Icypeas key. Runs on Findymail misses.
`prospeo_api_key`	No	Your Prospeo key. Runs on the residual after Findymail and Icypeas.
`signal_taxonomy`	No	Override the default signal types. Each entry is an object with type, strength, title_keywords, and optional also_keywords and description_keywords.
`target_contacts`	No	1 to 25. Default: "3".
`verify_position`	No	true to ask a model whether each contact's title on record is consistent and plausibly current, from the supplied evidence only. Needs claude_api_key; skipped without it. Contacts found on the company's own website are skipped. Default: "true".
`company_size_max`	No	Drop companies above this headcount. Same condition as the minimum.
`company_size_min`	No	Drop companies below this headcount. Only takes effect once headcount is known, so it applies in full mode and to any discovery row that carried an employee count. Discovery alone does not enrich.
`exclude_staffing`	No	true to drop postings from staffing and recruitment agencies. Default: "true".
`bounceban_api_key`	No	Your BounceBan key. Second verifier, used for the catch-all case.
`findymail_api_key`	No	Your Findymail key. First provider in the email waterfall.
`new_postings_only`	No	true to return only postings not seen in a previous run. Default: "false".
`previous_run_date`	No	YYYY-MM-DD watermark for delta detection when the cross-run cache is unavailable.
`extra_marketplaces`	No	Additional marketplace names to filter out.
`fetch_posting_page`	No	true to open the job posting when the description alone does not identify the employer. Slower, and it is what catches a job board posting on an employer's behalf. Default: "true".
`company_concurrency`	No	How many companies to work at once. Simultaneous provider calls are this times contact_concurrency; 6 x 3 = 18 sits under the tightest documented provider ceiling. Default: "6".
`contact_concurrency`	No	How many contacts to enrich at once within one company. The email waterfall itself always runs in order. Default: "3".
`extra_exclude_names`	No	Any company whose name contains one of these is excluded.
`source_timeout_secs`	No	5 to 120. A source that exceeds this is marked degraded and the run continues. Default: "30".
`exclude_marketplaces`	No	true to drop Upwork, Fiverr, Freelancer and similar gig listings. Default: "true".

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv1.2.0Oct 17, 2026

addedInput schema / properties / brand_voice

Added value: +{
+  "description": "How the opener should sound. Leave empty and it writes plainly and directly.",
+  "type": "string"
+}

addedInput schema / properties / claude_api_key

Added value: +{
+  "description": "Your own Anthropic key, used for position verification and the personalized opener. Both steps are skipped when it is absent. Never stored.",
+  "type": "string"
+}

addedInput schema / properties / company_concurrency

Added value: +{
+  "description": "How many companies to work at once. Simultaneous provider calls are this times contact_concurrency; 6 x 3 = 18 sits under the tightest documented provider ceiling. Default: \"6\".",
+  "type": "string"
+}

addedInput schema / properties / contact_concurrency

Added value: +{
+  "description": "How many contacts to enrich at once within one company. The email waterfall itself always runs in order. Default: \"3\".",
+  "type": "string"
+}

addedInput schema / properties / deny_tokens

Added value: +{
+  "description": "Whole words that disqualify a contact even when the title matched a target role, for example product refuses Product Owner and keeps Production Editor. Applies even when no target roles are set.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / icp_preset / description

Previous value: -"Which scoring model to apply. \"proofed_editorial\" scores for a seller of managed copy editing and proofreading. \"generic_b2b\" scores on hiring intent, employer resolvability and headcount with no service-specific vocabulary. Default: \"proofed_editorial\"."New value: +"Which scoring model to apply. \"editorial_services\" scores for a seller of managed copy editing and proofreading. \"generic_b2b\" scores on hiring intent, employer resolvability and headcount with no service-specific vocabulary. Default: \"editorial_services\"."

changedInput schema / properties / icp_preset / enum

Previous value: -[
-  "proofed_editorial",
-  "generic_b2b"
-]New value: +[
+  "editorial_services",
+  "generic_b2b"
+]

addedInput schema / properties / max_charge_usd

Added value: +{
+  "description": "Optional. The actor's own spend cap for this run, in USD. The run stops before a charge would take its total past this amount, writes one notice row saying so, and keeps every row already charged. Leave it empty for no cap of your own; the maximum cost per run set in Apify is honored either way.",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / max_spend_usd

Added value: +{
+  "description": "Stop making paid vendor calls once this much of your own vendor spend (Findymail, Icypeas, Prospeo, BounceBan) is committed, and return everything completed so far. Caps your vendor bills, not the Apify charge for this actor. Leave empty for no cap.",
+  "type": "string"
+}

addedInput schema / properties / personalize

Added value: +{
+  "description": "true to write a one or two sentence opener per contact that has an address, referencing something specific about the company. Needs claude_api_key; skipped without it. Default: \"true\".",
+  "type": "string"
+}

removedInput schema / properties / reoon_api_key

Removed value: -{
-  "description": "Your Reoon key. First email verification provider.",
-  "type": "string"
-}

addedInput schema / properties / target_roles

Added value: +{
+  "description": "Only enrich contacts whose title plausibly matches one of these roles. Filters after discovery and before any paid email lookup, so a non-matching contact costs nothing. Leave empty to keep every contact the seniority and department filters allow.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / verify_email / description

Previous value: -"true to verify each address. Needs a Reoon or BounceBan key. Default: \"true\"."New value: +"true to verify each address. Needs a BounceBan key. Default: \"true\"."

addedInput schema / properties / verify_position

Added value: +{
+  "description": "true to ask a model whether each contact's title on record is consistent and plausibly current, from the supplied evidence only. Needs claude_api_key; skipped without it. Contacts found on the company's own website are skipped. Default: \"true\".",
+  "type": "string"
+}

First observedv1.0.0Aug 10, 2026

TDQS

A4/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description asserts 'Read only: it enriches and discovers, it writes nothing,' while the annotations explicitly declare readOnlyHint=false. That is a direct negation of the structured safety signal, and the actor in fact writes cache state and output/notice rows and consumes credits, so the text is also factually off. Per the rubric, a description that contradicts its annotations scores 1; otherwise this text would be rich (it does disclose APIFY_TOKEN auth, per-vendor billing, concurrency ceilings and cost caps).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long (~10 sentences) but front-loaded: modes first, then mode/key dependencies, then usage boundaries, then cost controls, then auth. For a 48-parameter multi-mode actor the length is justified and nearly every sentence carries non-redundant information; only the trailing read-only claim is wasted and misleading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description states the return shape ('every row comes back flat and Clay ready with per field provenance'), the mode pipeline, the required APIFY_TOKEN, the bring-your-own-key vendor model, and the cost/limit controls. An agent has enough to invoke it correctly and to anticipate the billing and result format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the per-parameter baseline is 3, but the description adds genuine cross-parameter meaning: it groups max_results/max_pages/target_contacts/target_roles/max_spend_usd into a single cost-control model and states which vendor key is required by which mode (SerpApi for discover_jobs/full vs Serper for people search). That relational context is not derivable from any single property description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific composite actor and enumerates all four modes (enrich_companies, discover_jobs, find_contacts, full) with what each does, including the pipeline ordering in full mode. An agent immediately knows the verb, resource, and scope, and the definition also distinguishes itself from the named non-sibling tools (Work Email Waterfall, ICP Fit Scorer).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit positive trigger ('Use it when you need companies, hiring signals, or contacts in one flat table') and explicit exclusions with the correct alternatives named ('Do not use it to verify a single email... that is the Work Email Waterfall... or to score a list you already enriched... that is the ICP Fit Scorer'). This is textbook when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools

run_prospect_engineA