Search companies

Find a prospect list supported by observed activity.

search_companies is an authenticated Jolts MCP tool. Connect your assistant first.

Find distinct companies with relevant evidence. Supports natural-language query planning, exact filters, and optional background processing.

Argument	Type	Default / requirement
query	string	Required; 1–500 characters
filters	object	{}; see supported filters below
limit	integer	10; minimum 1, maximum set by the subscription
target	integer	Optional; 1–1,000, at least limit; requested shortlist size, not page size
cursor	string or null	Omit on the first page
background	boolean	false; use true to retrieve results later
request_key	string	Required unless Idempotency-Key is supplied as a header

{
  "name": "search_companies",
  "arguments": {
    "query": "Restaurants serving chocolate desserts",
    "filters": { "countries": ["CA"], "exclude_domains": ["example.com"] },
    "limit": 10,
    "target": 100,
    "background": true,
    "request_key": "chocolate-prospects-1"
  }
}

The examples on this page are the params object inside a JSON-RPC tools/call request, not complete HTTP requests. Read usage.id from a pending result and call get_usage to retrieve it. Completed results contain companies, supporting observations, coverage, and next_cursor. Each company includes domains: [{ "id": 123, "hostname": "example.com" }] when a current domain relationship is supported by the delivered evidence. An empty array means no currently deliverable domain support; no additional provider lookup is performed to fill it. target requests a bounded shortlist; it does not guarantee that many supported matches. Omit it to acquire for one page while retaining up to 100 stored-data candidates. Use background: true for fresh acquisition. Keep query, filters, limit and target unchanged when following next_cursor, including leaving target omitted if the first call omitted it. Each page uses a new request key. Candidate scanning considers up to max(100, 2 * target) companies before relevance filtering and caps accepted results at an explicit target. candidate_limit reports that scan cap, not a total.

Supported filters

Filter	Accepted values
countries	Array containing CA and/or US; observation country, supported headquarters for profiles
kinds	Array of company_profile, procurement_request, facility_expansion
demand_classes	Array of explicit_request, proxy, structural
occurred_after, observed_after	ISO 8601 timestamp strings
company_ids, exclude_company_ids	Up to 100 positive integer IDs per field
domains, exclude_domains	Up to 100 hostnames per field; no URLs or email addresses

Values within a field are OR; different fields are AND. Exclusions win. Empty arrays do not restrict. Domain matching normalizes case, whitespace, and a trailing dot; it does not remove www or merge subdomains. Only currently evidenced domain relationships match.

Read the response

Read result.structuredContent; text-only clients receive the same JSON in result.content. Check result.isError before using data. A successful HTTP status alone does not prove tool success. See response examples and error handling.

coverage.requested_companies is the page size; target_companies is the acquisition goal. available_companies counts the frozen shortlist, not the total market. Eligibility is rechecked on delivery, so later evidence withdrawal can reduce results. company_profile supports structural fit, not active buying intent, and may have a null event date. Each company’s why_it_may_matter is a short classification-based explanation, not a new AI assessment or a buying-intent score. Read the facts and citations referenced by match.observation_ids before acting. Replayed searches completed before these coverage fields were introduced may omit target_companies and available_companies. Missing counts mean unavailable, not zero.

Related

• Choose a tool
• Company-list workflows
• Understand evidence