Skip to main content

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: 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 details), 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). Every tool has a title and the readOnlyHint, destructiveHint and openWorldHint annotations, which your client may use to ask you before it acts. Some of your businesses’ agents’ tools are not available to a connected client: the tools that return a credential (the database connection strings, the repository deploy key, the AI model key), setting the site’s environment variables, running a connected app’s actions, and the paid catalog of external services. history_pull returns at most the 5 most recent turns by default and 50,000 characters per result. Whenever older turns may exist, it gives before, the value that fetches the next older page; it says truncated only when it left turns out or cut a turn to fit. 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:
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: follow the turn_id it carries. With a credit or plan refusal, the user manages their plan and credits in the dashboard, then you 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. Follow the turn with get_turn and wait_seconds: 25: the call returns as soon as the turn is waiting or has ended, or after the wait, and poll_after_seconds says when to call again. Its status is one of queued, running, waiting, completed, failed or interrupted; terminal is true for the last three. A waiting turn carries the agent’s questions, each with its header, question, options (label and description) and multi_select: 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 and the running turn’s turn_id: follow that turn instead of sending the work again. 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.

Goals

A goal is a result the business works toward on its own, with the criteria that say when it is reached and a credit allowance. Goals are turned on per business and are not available on every account yet. When they are off, list_goals answers goals_enabled: false and the other goal tools refuse. The business’s agent proposes each goal. Call approve_goal only when the person said yes to that exact version in your conversation: talking about a goal is not approval. Pass the version that list_goals shows; when a newer version exists, the call is refused and you list the goals again. An approved goal starts working and uses the account’s credits, within its allowance. A proposal allows at most 100 credits: approving one above that is refused, and you ask the business for a new version. decline_goal applies only to a goal that has not started. To change or stop a goal that has started, or to raise its allowance, tell the business with send_message. approve_goal, pause_goal and resume_goal return the goal as list_goals shows it. Two goals run at a time: while two run, approving a new goal or resuming a paused one is refused until one is paused or ends.