Tools and turns

Tools

Start with list_businesses. Every tool that acts on one business takes a required business argument: the business’s handle or id. These tools are specific to connected clients:

Tool	What it does
`list_businesses`	The businesses in the account: name, handle, status, site and dashboard URLs, the business’s own balance in cents, open questions from the agent, and whether it can take messages (`agent_chat`).
`get_business`	One business in detail: status, site and dashboard URLs, mission, idea, whether it is ready, revenue, the account’s credits, open tasks, the last turn.
`create_business`	Creates a business from an `idea` (up to 20,000 characters), with an optional `name`, `handle` (only with a `name`) and `paused`. Starts its first turn if the business is already set up; otherwise call `start_first_pass` once `get_business` shows `ready`. See Founding a business.
`start_first_pass`	Starts a business’s first turn when `create_business` could not start it yet.
`pause_business`	Pauses a business: no scheduled agent runs. Messages still work.
`activate_business`	Resumes a paused business’s scheduled runs.
`send_message`	Sends a message to a business’s agent, with optional file attachments, and returns a turn handle at once.
`get_turn`	The state of a turn: status, elapsed seconds, the credits it cost once it ends (`null` when not reported), the agent’s text so far, the final answer.
`interrupt_turn`	Stops a running turn.
`get_billing_links`	The balance and plan, plus links to top up, upgrade and open the billing portal. Nothing is charged.
`get_credits`	The balance, today’s spend, the minimum to start a turn, and the plan.
`upload_file`	Uploads a file (base64, up to 3 MB) for the agent to read; attach its id to `send_message`.

The rest of the catalog is the tool set your businesses’ agents use (email, products and payments, documents, tasks, files, site and domain, analytics, ads, prospects, web research, images, database and repository access), each with the business argument added. tools/list is the source of truth: it is sorted by name and cached for one hour (ttlMs, cacheScope: private), or five minutes for an account that does not see every tool yet. These tools only return a link and change nothing: cancel_platform_subscription, change_auto_topup, request_withdrawal, archive_business, delete_account, rotate_api_key, rotate_app_signin_secret, rotate_user_auth_secret and connections_request (the link opens the business’s Connections tab). Their result is:

{
  "action": "open",
  "url": "https://...",
  "note": "This opens the page where you do this. Nothing was changed."
}

cancel_subscription is a different tool: it cancels a subscription that one of the business’s customers bought.

Founding a business

create_business returns at once with business, welcome_credits_granted and first_pass. first_pass.status is one of:

started: poll its turn_id with get_turn.
provisioning: the business is still being set up (about a minute). Poll get_business until ready is true, then call start_first_pass.
skipped: the business already has its founding plan; there is nothing to start.
not_started: the business exists but its first turn could not start. detail says why, and error names the refusal when there is one. With conflict, a turn is already running: poll the turn_id it carries. Otherwise fix the cause (for example insufficient_credits), then call start_first_pass.

Never call create_business again for the same idea: a retry of the same idea by the same client within ten minutes returns the business already created instead of a second one.

Turns

send_message returns turn_id, session_id and business_id at once. Poll get_turn every few seconds. Its status is one of queued, running, waiting, completed, failed or interrupted. A waiting turn carries the agent’s question: relay it to the user and answer with send_message on the same business. A business runs one turn at a time; a message sent while one runs is refused with conflict. Clients on revision 2026-07-28 that declare the io.modelcontextprotocol/tasks extension get a task from send_message instead: the task id is the turn id, and pollIntervalMs is 5 seconds. tasks/get reports it as working, completed or cancelled: a failed turn is completed with an error result, and an interrupted one is cancelled. tasks/cancel stops the turn. tasks/update is not supported: send a new message instead.

AI agents

MCP reference

Tools

Founding a business

Turns

​Tools

​Founding a business

​Turns

Tools

Founding a business

Turns