run_tool is the only control tool that spends money or calls a provider. It starts one catalog-tool execution. Use get_run to read an existing run.

Signature

Start a run:

code

run_tool({ tool_id, input, idempotency_key, wait_seconds? })

Example start request:

code

{
  "name": "run_tool",
  "arguments": {
    "tool_id": "<tool_id from discover>",
    "input": { "<field from inspect>": "<your value>" },
    "idempotency_key": "<one client-generated UUID for this logical start>",
    "wait_seconds": 0
  }
}

Input fields

Field	Type	Meaning
`tool_id`	string	The selected catalog tool. Required for a new run.
`input`	object	The inspected tool's input. Required for a new run.
`idempotency_key`	UUID	Required for a new paid run. generate one UUID and reuse it for an exact retry after an uncertain response.
`wait_seconds`	integer, 0–120	How long to wait; defaults to 50 seconds.

Return and money behaviour

Every accepted run retains run_id, including successful and failed terminal responses. A successful result includes status, result, any artifacts, cost_estimated, cost_final and cost_display. A pending result is a non-error response; call get_run with that ID to keep waiting without starting work or paying again.

If a start response is lost, repeat the exact tool_id, input and idempotency_key. Scrollport returns the original run and its current state without another hold or provider job. A reused key with different authority, tool or canonical input returns idempotency_conflict. A fresh UUID means an intentional fresh paid execution.

The server validates before reserving funds. A response of confirmation_required includes an approval_url; show the estimate and URL to the user. Approval queues the existing run, which the agent reads with get_run({ run_id }). The agent cannot approve its own request. A failed run releases all reserved funds and is not billed. A daily_spend_limit_reached response means the daily allowance cannot cover the run; wait for the reported reset time or ask the user to review the limits.

Common errors

Missing tool_id or input: inspect the selected tool and supply both fields.
Missing or invalid idempotency_key: send a UUID for the paid start. Retain the start UUID for retries after an uncertain response.
idempotency_conflict: retry the original authority, tool and input unchanged, or use a fresh UUID only for an intentional additional run.
run_id is not accepted by run_tool; use get_run for an existing run.
connection_required: give the human connect_url, then inspect again.
insufficient_balance: the direct HTTP API may return a topup_url; Remote MCP deliberately removes purchase links. In MCP, tell the human to review the Scrollport wallet. An agent cannot add funds.
daily_spend_limit_reached: wait for the wallet's reported reset time or ask the human to review the daily cap.
Invalid input: read the returned hint and corrected example.

Read get_wallet before a batch and runs and recovery when a call is asynchronous.