`run_tool` is the only control tool that spends money or calls a provider. It starts one catalog-tool execution. Use [get_run](https://scrollport.com/docs/control-tools/get_run) to read an existing run.

## Signature

Start a run:

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

Example start request:

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

Read [get_wallet](https://scrollport.com/docs/control-tools/get_wallet) before a batch and [runs and recovery](https://scrollport.com/docs/guides/runs) when a call is asynchronous.