# Rukou MCP tools

Your connected AI app discovers Rukou's tools from the agent's MCP address. Tool availability
depends on your organization's enabled features and the agent's permissions. Use the tool
schemas returned by your connection for the complete argument definitions.

## Tool reference

| Tool | Use |
|---|---|
| `rukou_status` | Check the connected organization, workspace, and agent, whether browsers can start, and session limits |
| `browser_session` | Choose `action`: `start`, `list`, `extend`, or `stop`; `save` is available with Logins |
| `browser_tabs` | Choose `action`: `list`, `open`, or `close` |
| `browser_navigate` | Navigate to `url`, or use `go`: `back`, `forward`, or `reload` |
| `browser_observe` | Read the page's accessibility tree; optionally wait first with `wait_for` |
| `browser_click` | Click a target, or press and hold with `hold_ms` |
| `browser_fill` | Fill a target using one of `value` for text, `option` for a select, or `checked` for a checkbox or radio |
| `browser_press` | Focus a target and press a key or key combination |
| `browser_scroll` | Use a `scroll`, `swipe`, or `drag` gesture |
| `browser_screenshot` | Take a screenshot of the specified tab |
| `browser_adblock` | Turn the session's ad blocker on or off |
| `browser_settings` | Read or change browser settings, when the agent has permission |
| `browser_remove` | Remove obstructing page elements, when the agent has permission |
| `browser_request_help` | Ask a person to help on a tab, or withdraw a request |
| `browser_logins` | List approved logins or use `action: "sign_in"`, when Logins is enabled |
| `browser_new_ip` | Give the session a new egress IP address |
| `rukou_site_guide` | Read a site's guide, or add a workspace tip with `tip` |
| `rukou_feedback` | Report a problem or suggest an improvement |

A new egress IP address applies to every session on the same node, and interrupts each of
them for a few seconds. Tabs and cookies stay, but open network connections drop. Follow the
tool's retry guidance and reload affected pages when needed.

## Complete a first session

The JSON blocks below are tool arguments, not shell commands. Replace `SESSION_ID` and
`PAGE_ID` with the values returned by your calls. Use them with the agent that owns the session.

First call `rukou_status`:

```json
{}
```

Confirm the workspace and browser availability, then call `browser_session`:

```json
{
  "action": "start",
  "label": "first-visit"
}
```

Keep the returned `session_id` and first `page_id`. If the browser is still starting, repeat
the same start request after a few seconds. Once ready, call `browser_navigate`:

```json
{
  "session_id": "SESSION_ID",
  "page_id": "PAGE_ID",
  "url": "https://example.com"
}
```

Navigation may already return the page content you need. To read it again, call
`browser_observe`:

```json
{
  "session_id": "SESSION_ID",
  "page_id": "PAGE_ID"
}
```

When finished, call `browser_session`:

```json
{
  "action": "stop",
  "session_id": "SESSION_ID"
}
```

## Work with pages

To open another tab, call `browser_tabs` with the session ID and `action: "open"`. Use the new
page ID for calls on that tab. List tabs if you lose track of their IDs; closing the last tab
creates a blank replacement.

For example, call `browser_tabs` to open a second page in the existing session:

```json
{
  "session_id": "SESSION_ID",
  "action": "open"
}
```

Use the new tab's `page_id` as `SECOND_PAGE_ID` when you call `browser_navigate`:

```json
{
  "session_id": "SESSION_ID",
  "page_id": "SECOND_PAGE_ID",
  "url": "https://www.iana.org/domains/reserved"
}
```

Read either tab by passing its own page ID to `browser_observe`. Close the second one with
`browser_tabs` when finished:

```json
{
  "session_id": "SESSION_ID",
  "action": "close",
  "page_id": "SECOND_PAGE_ID"
}
```

Stop the session after all its tabs are finished; closing a tab alone does not stop it.

Read the page before choosing a target. Use the current observation's element reference with
its `snapshot_id`, or a specific label, text, or role and name that identifies the intended
control. Read again when a page changes or a reference becomes stale.

For a form that loads later, `browser_observe` can wait for an element before reading:

```json
{
  "session_id": "SESSION_ID",
  "page_id": "PAGE_ID",
  "wait_for": {
    "target": { "label": "Email" },
    "state": "visible"
  }
}
```

An action's reply may return only changes since the last complete read. Call `browser_observe`
without `target` or `find` for a full reading, or include `observe: true` on an action that
supports it. If a response is cut and contains `more`, pass that value to `browser_observe`
to read the next part.

Browser action calls can take an optional `request_id`. Repeating the same call with the same
ID and arguments returns its recorded result instead of acting twice. Use a new ID for a
different action. If an action's outcome is unknown, inspect the page before retrying it.

## Use a login and save its sign-in

Call `browser_logins` with `action: "list"` to find a login approved for this agent and check
whether the connection is ready to use it. On an allowed sign-in page, call:

```json
{
  "action": "sign_in",
  "session_id": "SESSION_ID",
  "page_id": "PAGE_ID",
  "login": "Research account"
}
```

Each call handles one sign-in step or restores saved state. Read the page after it. Once
signed in, keep the state for later with `browser_session`:

```json
{
  "action": "save",
  "session_id": "SESSION_ID"
}
```

Check the save result for each login before stopping. See [Logins](logins.md) for approval
setup and codes that require a person's help.