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.
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.