> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveintelligence.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Response format

> Where Hive attaches provenance, and how the shape differs between hero tools and category tools.

Responses are typed and bounded, and material ones carry provenance. Where that provenance
sits depends on which surface answered.

## MCP tools

Tools reached through discovery attach a top-level `_hive` object alongside the payload:

```json theme={null}
{
  "_hive": {
    "receipt_id": "9f2c…",
    "provider": "coingecko",
    "tool": "get_coin_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "miss",
    "duration_ms": 184
  }
}
```

`_hive` also carries `receipt_version`, `server_version`, `input_digest`, and
`result_digest`. The digests are SHA-256 self-checks over the canonical arguments and the
normalized payload. They let you detect accidental mutation; they are not server signatures.

## Hero tools

The three hero tools return a `source_receipt` instead:

```json theme={null}
{
  "source_receipt": {
    "provider": "coingecko",
    "tool": "get_coin_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "hit",
    "source": "…",
    "receipt_id": "9f2c…"
  }
}
```

Same three fields you care about, different container. See [receipts](/concepts/receipts).

## runtime\_status values

`runtime_status` is an enum, not free text:

| Value           | Meaning                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `ok`            | The call succeeded against a healthy provider                                                                        |
| `invalid_input` | Your arguments failed validation, or the venue and method combination is unsupported. Fixable by correcting the call |
| `missing_key`   | The provider is not configured                                                                                       |
| `plan_required` | Your plan does not include this                                                                                      |
| `rate_limited`  | Throttled                                                                                                            |
| `degraded`      | The provider answered but is unhealthy. Treat the result as low confidence                                           |
| `failing`       | The provider is down                                                                                                 |

`invalid_input` is worth handling separately: it is not an outage, so retrying unchanged will
fail the same way.

## Cache fields

`cache_status` tells you whether the response came from Hive's cache. On a hit, `observed_at`
is when Hive first saw the data and `cache_age_ms` is how long ago that was.

A `cache_age_ms` of zero means Hive fetched from the provider just now. It does not promise
that the provider's own underlying datum is current.

## Normalization fields

Where Hive knows something is off about a datapoint, it says so in a field rather than
dropping the row:

| Field               | Meaning                                                |
| ------------------- | ------------------------------------------------------ |
| `is_delisted`       | No longer actively traded on the venue                 |
| `is_price_suspect`  | Diverges enough from other sources to warrant a check  |
| `funding_mechanism` | How this venue calculates funding, since venues differ |

Your agent decides what to do with a flagged row. Hive does not filter it out for you.

## Bounded output

Every list-returning tool respects `limit`, `page`, `per_page`, and `offset`, and Hive caps
total response size regardless of what you ask for. An unbounded response would burn the
context your agent needs for the actual task.

## Errors

Failures return an error object naming the cause and the next action. See
[errors](/reference/errors).