> ## 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.

# Tool reference

> Seven tools for company research, evidence, and account usage.

Start with [MCP connection setup](/mcp). Call `tools/list` to discover the schemas advertised by the
server you are connected to. These tools return the same business data as the HTTP API.

## search\_companies

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.

## get\_company

```json theme={null}
{ "name": "get_company", "arguments": { "id": 123 } }
```

`id` is a required positive integer returned by search. Returns `company` with identity, supported
domains, and up to three recent observations. This is an unmetered, subscription-authorized read,
not a full profile or a fresh lookup. `company_not_found` means no deliverable company was found.

## search\_observations

```json theme={null}
{ "name": "search_observations", "arguments": { "query": "charging", "limit": 10, "request_key": "charging-evidence-1" } }
```

Accepts `query`, `filters`, `limit`, `cursor`, and `request_key` with the same basic types as company
search. Filters support countries, kinds, demand classes, and the two timestamp fields only.
Company lists, domain lists, and `background` are **not** accepted here. This search does not use
company-search query planning. Returns individual `observations` rather than grouped companies.

## get\_observation

```json theme={null}
{ "name": "get_observation", "arguments": { "id": 456 } }
```

`id` is a required integer from a returned observation. Returns `observation` and its currently
permitted evidence. Unmetered, but requires subscription access. Does not start new research.

## create\_usage

```json theme={null}
{ "name": "create_usage", "arguments": { "query": "charging", "limit": 10, "request_key": "background-evidence-1" } }
```

Queues an **observation search**, using the same inputs as `search_observations`. Returns an operation
to poll with `get_usage`. For background **company** results, use `search_companies` with
`background: true` instead.

## get\_usage

<CodeGroup>
  ```json Read an operation theme={null}
  { "name": "get_usage", "arguments": { "id": 789 } }
  ```

  ```json Read account limits theme={null}
  { "name": "get_usage", "arguments": {} }
  ```
</CodeGroup>

Optional `id` is an integer. With an ID, returns the account-owned operation's status or results;
without it, returns subscription usage and limits. Neither read is metered. An ID from another
account returns `usage_not_found`.

## diagnostic

```json theme={null}
{ "name": "diagnostic", "arguments": {} }
```

Requires an `Idempotency-Key` **header**; there is no `request_key` argument. Returns subscription
plan/status and metering information. It consumes one request unit for a new successful operation.
Prefer unmetered `tools/list` to check connectivity or `get_usage` to check allowance.

## Handle responses safely

* Read `result.structuredContent`. Text-only clients can parse the equivalent JSON in `result.content`.
* Check `result.isError` and `structuredContent.error.code`; HTTP success alone is not tool success.
* Reuse a request key only for identical retries. A next page uses a new key with unchanged query,
  filters, and limit, plus the returned cursor.
* Stop on subscription or capacity errors. Inspect the structured retry guidance when supplied.
* Do not describe partial or empty coverage as proof that no prospect exists.

OAuth, change-feed tools, contact enrichment, and automated outreach are not implemented.