Use this guide when you are integrating Scrollport directly and need the explicit control-tool calls. If your agent is already connected, the [quickstart](https://scrollport.com/docs/quickstart) is the simpler path: describe the outcome and let the agent handle this sequence.

The catalog response and tool input are live, so placeholders below stand for values returned by the current API rather than a claim that a particular provider call ran.

## Start safely

Give the agent the [recommended setup prompt](https://scrollport.com/docs/quickstart), complete the browser approval and call `get_wallet`. Confirm `available` is enough for the selected job before asking it to run.

## Discover the outcome

```json
{ "name": "search_tools", "arguments": { "query": "find the text of a web page" } }
```

Select a `tool_id` from the response. The provider name is provenance, not the job to search for.

## Inspect the selected tool

```json
{ "name": "inspect_tool", "arguments": { "tool_id": "<returned tool_id>" } }
```

Read `input_schema`, `worked_example` and `common_errors`. Copy the worked input and substitute your own value without changing its shape.

## Run once

```json
{
  "name": "run_tool",
  "arguments": {
    "tool_id": "<returned tool_id>",
    "input": { "<inspected field>": "<your value>" },
    "idempotency_key": "<one client-generated UUID for this logical start>",
    "wait_seconds": 0
  }
}
```

If the response is still queued or running, keep the `run_id` and read it with `get_run`:

```json
{ "name": "get_run", "arguments": { "run_id": "<returned run_id>", "wait_seconds": 50 } }
```

This read needs no idempotency key and cannot start another run. If the run asks for approval, stop and show the human the estimate, then use `get_run` after approval. If it asks for a connection, give the human the connection URL.

## Reconcile the wallet

Call `get_wallet` after the run. A successful run has `cost_final`; a failed run has released its hold and is not billed. This final read makes the money result visible rather than treating provider output as the only success signal.