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

# Read an MCP response

> Tell a finished search from a pending request, an empty result, or an error.

Your assistant usually reads these responses for you. If you are connecting a tool yourself,
this page explains what to check before showing a result to someone else.

## Two layers, one answer

MCP wraps the answer in a JSON-RPC message. The outer `id` matches your request, not a company ID.
Inside `result`, `structuredContent` contains the company data or error. `content` contains the
same answer as JSON text for clients that cannot read structured data. Do not count these as two
different results.

Check `result.isError` before using the answer. A successful HTTP request does **not** necessarily
mean the tool succeeded. Authentication and protocol failures may happen before a tool runs, so
also handle a non-success HTTP status or a top-level JSON-RPC `error`.

## A search is still running

For `search_companies` with `background: true`, read `result.structuredContent.usage`:

```json Pending usage excerpt theme={null}
{
  "id": 981239949,
  "status": "pending",
  "request_key": "company",
  "request_units": 0,
  "delivered_units": 0,
  "fresh_evidence_units": 0
}
```

This is only the `usage` object, not a complete response. IDs and amounts are illustrative.
`pending` or `processing` means wait and call `get_usage` with that ID. Do not start another search
just because results are not ready. Polling does not consume another request unit. Stop polling
when you receive results or a terminal error, and avoid a tight retry loop.

## A completed company search

The complete company result has the same shape as the HTTP API's
[company search response](/api-reference/companies/search-companies). Open its response example
to see every field, including fictional companies and their supporting evidence.

Read these fields in `result.structuredContent`:

| Field                            | What it means                           | What to do                                                            |
| -------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |
| `companies`                      | The companies returned on this page     | Show the names with their supporting observations                     |
| `companies[].observations`       | Evidence supporting each company result | Preserve source links, dates, confidence, and demand class            |
| `coverage` and `coverage_status` | Limits of the search                    | Explain partial coverage; do not claim the whole market was checked   |
| `next_cursor`                    | A continuation token, or `null`         | Request another page only when a token is present                     |
| `usage`                          | This operation's status and metering    | Do not confuse request units with companies returned                  |
| `request_allowance`              | Remaining request allowance             | Do not describe it as a count of prospects                            |
| `withheld_units`                 | Previously delivered units now withheld | Respect the current response rather than restoring withdrawn evidence |

For another page, keep the query, filters, and limit unchanged; add the returned cursor and a new
request key. For an identical retry of the same page, reuse its original key.

## An empty list is not an error

`companies: []` with a delivered usage means no deliverable companies were returned for this request.
It does not mean no company could need your product. Read the coverage limitations before changing
your search. Never manufacture a company or source to fill the list.

## A tool could not complete the request

This complete response is returned when `diagnostic` is called without its required
`Idempotency-Key` header. It does not consume a diagnostic request unit.

```json Tool error theme={null}
{
  "jsonrpc": "2.0",
  "id": "example",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":{\"code\":\"missing_request_key\",\"message\":\"Provide an Idempotency-Key header.\"}}"
      }
    ],
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "missing_request_key",
        "message": "Provide an Idempotency-Key header."
      }
    }
  }
}
```

Use `structuredContent.error.code` to decide the next step. Fix invalid inputs; do not retry them
unchanged. Respect supplied retry guidance for limits. Never ask someone to paste their API key
into a support conversation. See [troubleshooting](/troubleshooting) for individual errors.

## What a customer should hear

Explain the result, not the protocol: “Here are the companies we found, why each may fit, and the
sources.” Keep observed facts separate from inferred need. A procurement request is evidence of a
stated requirement; a facility expansion may suggest a need. Neither guarantees a purchase.

For account-specific questions, public documentation cannot tell you someone's balance, billing
state, or private search results. Use an authorized account tool or hand off to support.

Continue with the [tool parameters](/mcp-tools) or [evidence guide](/evidence).