> ## 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          |
| `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": "Companies seeking charging equipment",
    "filters": { "countries": ["CA"], "exclude_domains": ["example.com"] },
    "limit": 10,
    "background": true,
    "request_key": "charging-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`.

### Supported filters

| Filter                               | Accepted values                                                           |
| ------------------------------------ | ------------------------------------------------------------------------- |
| `countries`                          | Array containing `CA` and/or `US`; observation location, not headquarters |
| `kinds`                              | Array of `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).

## Related

* [Choose a tool](/mcp-tools)
* [Company-list workflows](/workflows)
* [Understand evidence](/evidence)