run_tool

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:

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

Example start request:

{
  "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

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 hard daily limit.
• Invalid input: read the returned hint and corrected example.

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