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:

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, limit and target unchanged, including omission of target; add the returned cursor and a new request key. For an identical retry, 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 get_companies is called with valid IDs but without a request_key argument or Idempotency-Key header. It does not consume a request unit.

Tool error

{
  "jsonrpc": "2.0",
  "id": "example",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":{\"code\":\"invalid_lookup\",\"message\":\"Request key can't be blank\"}}"
      }
    ],
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_lookup",
        "message": "Request key can't be blank"
      }
    }
  }
}

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.