# 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 |
| x402 payment required | A priced offer has been frozen in an MCP error result | Confirm scope and spending authority; retry the same call with payment metadata |
| `suggested` | A choice is required; no bound result yet | Show options and basis; repeat with the selected field named by `resume` |
| `error` | Product refusal or failure | Inspect `kind`, `message`, optional `not` and `remedy`; repair the specific issue |

Product errors normally arrive with MCP `isError: false`; x402 payment required
is the intentional exception. 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.

Priced `materialize` and `read` calls accept only their advertised work fields;
extra payment-policy fields return `invalid_params`. The payment settles the
exact quoted amount. Keep spending caps in the agent's wallet or signer.

`read` accepts row-key filtering through `key`; its old `attributes` and
`entity` inputs are retired. `provenance` no longer accepts `attribute`.

## 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 response. Inspect coverage and job state
before retrying or paying again. A lost answer retried with the same spent
payment or the same x402 `payment-identifier` is served again without a second
charge. Reusing an identifier for different work is refused as
`payment_identifier_conflict`. Quote expiry does not cancel a background job
already started.

`payment_recovery_pending` means the original signed payment has been retained
while the daemon resolves or records its settlement. Do not sign a replacement:
retry the original paid call. An unknown settlement remains pending after quote
expiry until finalized chain evidence resolves it. 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.