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