`run` is the only control tool that spends money or calls a provider. It can start a new catalog-tool execution or resume one already started.

## Signatures

Start a run:

```text
run({ tool_id, input, confirm?, wait_seconds? })
```

Resume a run:

```text
run({ run_id, wait_seconds? })
```

Example start request:

```json
{
  "name": "run",
  "arguments": {
    "tool_id": "<tool_id from discover>",
    "input": { "<field from inspect>": "<your value>" },
    "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. |
| `confirm` | boolean | Only `true` after a human approves a quoted estimate. |
| `wait_seconds` | integer, 0–120 | How long to wait; defaults to 50 seconds. |
| `run_id` | string | Resume an existing run instead of starting one. |

## Return and money behavior

A completed result includes `run_id`, `status`, optional `result` and artifacts, `cost_estimated`, `cost_final` and a display cost. A still-running call returns a `run_id`; resuming it starts nothing and costs nothing.

The server validates before placing a hold. A confirmation-threshold response is `confirmation_required`; show its estimate to the human and retry the identical input with `confirm: true` only after they agree. A failed run releases its entire hold and is not billed.

## Common errors

- Missing `tool_id` and `run_id`: choose one valid mode.
- `run_id` mixed with `tool_id` or `input`: remove the new-run fields.
- `connection_required`: give the human `connect_url`, then inspect again.
- `insufficient_balance`: give the human `topup_url`; an agent cannot add funds.
- Invalid input: read the returned `hint` and corrected example.

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