Waiting and limits

Waiting: pending and progress

An agent cannot hold a request open for minutes the way your code can. The waiting tools therefore wait for a bounded time and report back.

Tool	timeout (seconds)	Default	Maximum
wait_for_sms, wait_for_email	optional	60	300
resolve_captcha	optional	120	600

• A result arrived. wait_for_sms and wait_for_email return status: "received" with the same fields as the API response. wait_for_email leaves out html and headers unless you ask for them with include_html and include_headers, to keep the result small.
• Nothing arrived yet. They return { "success": true, "status": "pending", "message": "..." }. This is normal and not an error: the agent calls the same tool again. A wait that finds nothing costs nothing.
• Captchas return their own status: solved, failed or timeout. failed and timeout are free and are not tool errors.
• Progress. If the client sends a progress token with the request, the three waiting tools send a progress notification right away and every 10 seconds after (progress is the elapsed seconds and total the timeout), so the client knows the call is alive.
• If the client cancels the call or disconnects, the wait in the API is cancelled too.

Spend limits

An agent that can spend money needs a budget. Three things bound it, and the strictest one wins:

1. The team balance. Nothing is spent without balance. A call that cannot be covered fails with insufficient_balance before anything happens.
2. The token’s limits. Each MCP token, and each OAuth sign-in, can have a daily and a monthly limit in USD, set under MCP in the console. Days and months are UTC. Leave a limit empty for none.
3. The project’s limits. The limits in the project’s Settings apply to everything the project does, including the agent.

A call that would go past a limit fails with spend_limit_exceeded, and the error names the scope (mcp_token or project), the period, the limit and what was spent. The agent can read its limits and spending with get_balance. See Billing.

Keeping an agent safe

• Create a token per agent or task, so each can be revoked on its own.
• Select only the tools it needs. An agent that only reads SMS does not need rent_number.
• Give any token that can spend a daily limit.
• Let it check prices first: get_number_prices, list_captcha_types and get_balance are free.