# Outcomes and recovery

Always inspect the tool result's top-level `outcome` before reading its payload. A valid MCP response is not necessarily completed work.

| Outcome | Interpretation | Next action |
| --- | --- | --- |
| `success` | The verb succeeded or work was accepted | Interpret that verb's fields; poll an accepted async job |
| `payment_required` | A priced offer has been frozen | Confirm scope and spending authority; pay, then execute using only payment ID |
| `suggested` | A choice is required; no bound result yet | Show options and basis; repeat with the selected field named by `resume` |
| `incomplete` | An answer is pending or incomplete where the verb supports it | Keep the diagnostic; do not treat it as completed metric data |
| `error` | Product refusal or failure | Inspect `kind`, `message`, optional `not` and `remedy`; repair the specific issue |

Product errors normally arrive with MCP `isError: false`. Transport failures are different: inspect MCP error/connection status and do not assume an interrupted charge or accepted job was rolled back.

## range_unavailable

`read` does not index and refuses a window that is not fully covered. Its `materialized` and `materializing` geometry is clipped to the requested range. If missing blocks are already in flight, inspect their jobs and wait. Otherwise materialize the remaining holes. Use the full bound-function inspect card for the complete range ledger.

A provenance coverage error reports its available range lists according to that tool's contract. Do not blindly reuse the read-specific clipping assumption for other tools.

## invalid_params

Check the deployed schema, identity type, exact field spelling, required subject fields, paired block ends, address shape, and declared measure names. Remove retired `cursor` and `limit`. Do not add generic fields such as `query` or `sql` to tools that do not advertise them.

`read` accepts row-key filtering through `key`; its old `attributes` and `entity` inputs are retired. `provenance` no longer accepts `attribute`. Current `read` outcomes are `payment_required`, `success`, and `error`.

## suggested

The server supplies the answer's target field through `resume`. Merge the chosen answer into the original call instead of replacing the whole request. Do not automatically choose a different metric, window, or economic tradeoff. The operator's prior explicit choice can supply the answer; otherwise request it.

## Interrupted paid work

Keep the frozen quote and payment IDs. Inspect coverage and job state before retrying or paying again. Quote expiry does not cancel a background job already started. Repeating an unpaid request does not refresh its expiry. Inspect job errors and refund records; see [payments](/agents/payments/).

## Final answer quality

Report only successful data, with chain, scope, exact block window, measure meanings, and verification evidence. If coverage or assembly failed, report that limitation explicitly. Do not invent a value from the metric's name, marketing copy, or the animated homepage demo.