MCP tools
Tools reached through discovery attach a top-level_hive object alongside the payload:
_hive also carries receipt_version (always "1.0"; the credit fields were added without
bumping it), server_version, input_digest, and result_digest. credit_cost,
credits_used and credits_remaining are described under
receipts; on an error the object also carries
cause, next_action and doc_url. 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 add asource_receipt describing the provider call they made underneath,
alongside their own top-level _hive:
_hive as the way to detect
one. source is an enum with four values: live, cached, fallback, and unavailable.
Same three fields you care about, different container. See receipts.
CLI
hive ... --json is a third shape. It wraps everything in an envelope, and the provenance
lands in meta rather than _hive or source_receipt:
quota_remaining is a deprecated alias of credits_remaining kept for one release; read
the new name. meta.tool is the tool you called and meta.provider is the surface that served it, so a hero
tool reads Hive here. The upstream provider for that call is in source_receipt inside
data, not in meta.
--jq filters data only, so --jq '.price' reaches into the payload and not the envelope.
--jq '.ok' returns nothing, because ok lives on the envelope.
runtime_status values
runtime_status is an enum, not free text:
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:
Your agent decides what to do with a flagged row. Hive does not filter it out for you.
Bounded output
Where a list-returning tool supportslimit, page, per_page, or offset, use them. Not
every tool takes all four, so check the schema with get_api_endpoint_schema or
hive tools info <name>.
Hive caps total response size regardless of what you ask for: 25,000 tokens, or roughly 100,000
characters. Responses trimmed to fit set truncated to true. An unbounded response would burn
the context your agent needs for the actual task.
Errors
Failures return the same four legs on every surface:code, message, cause,
next_action, plus retryable, retry_after when a wait is known, and doc_url, an anchor
on the errors page. REST keeps type, param and request_id
alongside; JSON-RPC cap errors carry the fields under error.data; the CLI keeps
suggestion as an alias of next_action for one release.