Read an MCP response

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:

Pending usage excerpt

{
  "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. 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.

Tool error

{
  "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 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 or evidence guide.

​Two layers, one answer

​A search is still running

​A completed company search

​An empty list is not an error

​A tool could not complete the request

​What a customer should hear