Confirmations & Spend Safety

Mailhub checks the confirm value on the tool call itself. Mailhub does not rely on the assistant to decide whether a write is safe to run.

Tool	Changes data	Requires confirm: true	Spends wallet funds
mailhub_create_order	Yes	Yes	No
mailhub_update_order_status	Yes	Yes	No
mailhub_buy_label	Yes	Yes	Yes
mailhub_cancel_label	Yes	Yes	No

The other four tools — mailhub_list_orders, mailhub_get_order, mailhub_get_shipment_rates, and mailhub_download_label — read only and need no confirmation. Rates need a stronger Mailhub permission than the other reads, but rating changes nothing and buys nothing, so it is not a changing tool.

What confirmation proves

Every changing MCP tool takes a confirm argument, and Mailhub runs the operation only when that argument is the JSON boolean true.

• Missing or false is a refusal. The tool returns MCP_CONFIRMATION_REQUIRED and nothing happens.
• The string "true" is not confirmation. Only the boolean counts.
• The refusal comes from the server, not from the assistant. Mailhub applies a default-deny rule to changing tools, so an unconfirmed write is rejected even if a client tries to invoke it directly.

What this contract does and does not establish

A true value passes the confirmation gate and nothing more. This documentation does not specify how a supported client obtains approval from its user — whether it shows a dialog, who sets the field, and what the user saw are the client's behavior, not part of the published Mailhub server contract. Treat confirm: true as "this call was made deliberately", not as evidence that Mailhub displayed a prompt and a person clicked it.

After a MCP_CONFIRMATION_REQUIRED refusal the call can be repeated — but only with the confirmation set, which makes the retry a decision rather than a reflex.

What confirmation does not bypass

confirm: true means "I intend to perform this change." It does not bypass Mailhub permissions or business rules. A fully confirmed call is still refused when:

• Agent Access is off, or your Mailhub user lacks the permission — Before You Connect;
• the Order's status does not allow the operation — Order Statuses;
• the wallet cannot cover the purchase, or the agent spend limit would be exceeded, or the write-rate guard is active — below;

and every one of those refusals is listed in Errors & Troubleshooting.

Financial transactions

mailhub_buy_label is the only current MCP tool that moves money. Creating an Order does not spend anything, changing a status does not spend anything, and cancelling a Label does not automatically return funds to the wallet.

A Label purchase needs both enough wallet balance and enough remaining agent spend allowance. These are two independent checks, and passing one says nothing about the other:

• Remaining agent spend allowance does not guarantee the wallet holds enough. Insufficient funds are refused with Wallet.InsufficientFunds.
• A well-funded wallet does not guarantee the agent spend limit permits the purchase. Exceeding it is refused with Wallet.McpSpendCapExceeded.

Both are evaluated before any money moves and before the carrier is called, so a purchase Mailhub refuses on either ground does not debit first and unwind afterwards.

The agent spend limit	Current behavior
Scope	The account
Window	Rolling 24 hours
Default	1000, in the account wallet's own currency
Unlimited	Supported, when no limit is configured
Applies to	Label purchases made through MCP
Does not apply to	Normal non-MCP account spending, which does not consume this limit
Counted while pending	Yes — a purchase in progress already occupies the limit
Released purchases	An abandoned or failed purchase frees its part of the limit again
Cancelled Label	The original spend still counts for the rest of its 24-hour window
Who can change it	An authorized account user, in Mailhub

An assistant cannot raise its own limit through MCP, and MCP cannot add funds to a wallet — there is no account-settings tool and no top-up tool. Either older spend ages out of the rolling window, or an authorized account user changes the limit in Mailhub.

The write-rate guard

Mailhub currently targets a guard of about 10 changing MCP calls per minute per account. Reaching it returns MCP_WRITE_RATE_LIMITED; wait briefly and try again. It counts only the four changing tools — reads do not consume it, and an unconfirmed call does not either, because confirmation is checked first. It is a request-rate safety guard, not a billing or spend quota.

Retrying a changing call

There is no blanket answer, and treating one tool's protection as the rule for all four is the mistake that costs the most.

Tool	Repeating the same confirmed call	If the outcome is uncertain
mailhub_create_order	Creates a second Order. There is no deduplication	List Orders and look for it before creating another
mailhub_update_order_status	Normally refused as already in that status, rather than applying another transition	Read the Order; the status itself is the answer
mailhub_buy_label	Does not buy a second Label for the same Shipment and Rate	Read the Order, or ask for the Label link — one that is not ready says so
mailhub_cancel_label	Safe. An already-cancelled Label is not cancelled again with the carrier	Re-read the Order; a return to Packed is what confirms it

Label-purchase replay safety does not generalize

Repeating the same purchase does not buy a second Label. That protection applies to Label purchase only. It does not make the other changing tools safe to repeat, and in particular it says nothing about mailhub_create_order, where a repeated confirmed call does create a duplicate.

Mailhub does not use automatic transport retries as a substitute for write safety.

Next

Read the Tool Reference for what each tool takes and returns.

• Reading a refusal? Errors & Troubleshooting.