> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jolts.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Search companies

> Find a prospect list supported by observed activity.

`search_companies` is an authenticated Jolts MCP tool. [Connect your assistant](/mcp-overview) 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                    |

```json theme={null}
{
  "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](/mcp-responses) and [error handling](/troubleshooting).

`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](/mcp-tools)
* [Company-list workflows](/workflows)
* [Understand evidence](/evidence)