Replies and next steps

An MCP tool result is a plain-English briefing for the user and the agent, followed by one line of JSON with only what the next call needs. Read the briefing, do what What to do says, and use the JSON line for the next call.

Support revision: envoy@2026-10. Last updated: 3 November 2026.

The HTTP API (/tools/*) returns the full reply envelope instead. See the HTTP API for that format. This page covers MCP only.

What an MCP tool result contains

• content holds one text item: the briefing, a blank line, then the data as one JSON line.
• structuredContent is the same JSON object. The MCP outputSchema declares it.
• isError is true when the call returned an error. A checkout report may already be saved when its reply fails.
• _meta["money.envoy/support"] holds diagnostics for support and hosts. Hosts do not pass it to the model.

The briefing has one to three sentences for the user, then What to do: for the agent. It has no codes, ids, field paths or timestamps.

Sometimes the user must act in the Envoy app and the agent has a call to make. Then What to do: comes first. Tell the user the app step, then follow the returned next.tool and next.args to check progress. The user part says the assistant carries on by itself, and asks the user to reply "done" only if it doesn't.

A synthetic waiting reply:

What to do: Tell the user the message below once; they can't see tool results. They need to do it within about 15 minutes. Call get_purchase_status with the next tool and args from the data below: it waits up to 45 seconds for a change. Follow each returned next action until the situation changes or Envoy says to stop. get_purchase_status moves on by itself as soon as the user finishes in the Envoy app; the user doesn't need to tell you.

Approve this purchase in the Envoy app. (₹2,499.00 at "Example Store") Your assistant carries on by itself once you approve.
{"situation":"waiting_for_user","money":"not_charged","purchase_id":"pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c","next":{"tool":"get_purchase_status","args":{"purchase":"pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c","after_revision":1,"wait_seconds":45}}}

The full synthetic replies for every tool are in the MCP reference.

A held get_purchase_status call that sends a progressToken is answered as a stream; see Transport.

Read a result

1. Tell the user the first part of the briefing in your own words.
2. Do what What to do says.
3. Wait next.wait_seconds when present, then pass next.args unchanged to next.tool. This delay precedes the call; next.args.wait_seconds bounds waiting inside it.
4. Use purchase_id for later calls.
5. Never show the JSON line, or any code, id, key or timestamp, to the user. The user cannot use them.
6. Give support_ref only if the user asks for help.

Data keys

Over MCP the agent does not see ok, purchase.state, status_text, next.action, error codes, reason codes or the rail. Those are REST only; see Errors and reason codes.

What each situation means

situation says where the purchase stands. money says whether money moved. Read both. The same situation can come with different money values, and the money value changes what you tell the user.

stopped always has money of not_charged or refunded. Suppose a purchase ended and money is set_aside, refunding or unknown. Then Envoy reports needs_support instead. The money outcome is not safe to call.

A synthetic confirming reply:

Envoy is confirming whether the payment for ₹2,499.00 at "Example Store" went through.

What to do: Tell the user it isn't confirmed yet. Don't pay again or start a new purchase for this. Call get_purchase_status again to follow it: it waits up to 45 seconds for a change. If the user asks for help, give them the reference EV-72Z0SF.

{"situation":"confirming","money":"unknown","purchase_id":"pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c","next":{"tool":"get_purchase_status","args":{"purchase":"pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c","after_revision":1,"wait_seconds":45}},"support_ref":"EV-72Z0SF"}

A synthetic stopped reply:

This purchase could not be completed. You have not been charged. (₹2,499.00 at "Example Store")

What to do: Tell the user in your own words and stop this purchase; don't retry it. If they still want it, you can start a new purchase. If the user asks for help, give them the reference EV-72Z0SF.

{"situation":"stopped","money":"not_charged","purchase_id":"pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c","retry":"new_purchase","support_ref":"EV-72Z0SF"}

Map MCP situations to HTTP states

Never copy an MCP parser into HTTP code, or the reverse.

Read money

money says whether money moved: not_charged (nothing moved), set_aside (reserved for this purchase), charged, refunding, refunded or unknown. When money is unknown, treat the purchase as confirming. Never pay again to get unstuck, because the first payment may have gone through.

Read retry

retry appears on errors and on stopped or unsupported purchases. It says whether the same call is safe to send again.

After a lost reply or a timeout, call get_purchase_status first. See Recover a purchase.

Escalate to support

When a reply carries support_ref (for example EV-72Z0SF), give it to the user if they ask for help. The user quotes it to support at envoy.money/support. Support finds the request, its error and its state with that one reference. The agent never sees those codes.

support_ref appears on confirming, needs_support, most stopped results and most errors. It does not appear on input errors, NOT_FOUND-style lookups, key conflicts or rate limits, because the agent fixes those itself. There is no status page. See Resolve a connection or purchase problem.

Rate limits

Each access token may make 120 tool requests per minute, shared between MCP and HTTP. Over that, a tools/call returns a tool result with isError: true, a wait time in next.wait_seconds and retry same_call. Wait that long, add a little random jitter, and repeat the same call. Other over-limit MCP requests get JSON-RPC error -32000. Requests that fail authentication are also limited per client IP.

Protect the card details

card contains secret payment details: either a one-time card or a gift-card voucher. It appears only in an authorized ready get_purchase_status, in both the JSON line and structuredContent. The briefing never carries card values. A report stops use of the current handout. Envoy can return a new ready handout after reconciliation. A disconnect ends disclosure. A cancelled purchase does not release credentials. Host history may keep the text.

• Use the card once, at the checkout for this purchase. Then call report_checkout_result. Report paid only if the merchant confirmed the payment. If you cannot tell whether payment completed, report failed with failure_reason: other.
• If the checkout fails, report failed with the closest failure_reason. Follow the returned recovery option. An eligible retry_of can use Envoy checkout; price_changed and out_of_stock do not offer that retry. See Report the result.
• Keep card details, checkout codes, voucher codes and PINs out of replies, files, logs, traces, memory, feedback and analytics.
• Clear local copies after use.

Support reference and _meta

support_ref (for example EV-72Z0SF) is the one short reference for a result. Support finds the request with it. Give it to the user only when the user asks for help.

_meta["money.envoy/support"] carries support_ref, request_ref, request_id, trace_id, tool, error_code, reason_code, state, user_task, situation, rail and rail_reason. It is for hosts and support, not for the model. Do not show it to the user.

Read the envelope

REST only. An MCP agent does not see this envelope. The values below are what POST /tools/:tool returns.

The HTTP API returns one envelope for every tool, on success and on failure. Read ok, then follow next.

The REST-only next.action values are call_tool, checkout, fix_input, retry, continue, done, stop, reconnect and update_client. Every field is in the shared schemas, and every error code is in Errors and reason codes.

Which tools change things

get_account, list_transactions, list_purchases, list_gift_card_merchants, get_merchants, search_products and report_checkout_step do not move money. A checkout-step reply returns no card; keep using the authorized handout rather than reading ready status again. get_purchase_status reads progress, but a ready read releases authorized payment details and can start Envoy's gift-card checkout. Do not poll or auto-refresh ready status. start_purchase, report_checkout_result and cancel_purchase can change a purchase or money; retry each only as the result directs, with the same key or purchase reference. answer_purchase_question (deprecated name submit_answer) sends the user's reply to an open question, or optional feedback; retry it with the same key and the same answer. Tool annotations describe these effects; they do not grant permission.