---
title: Tools reference
description: Inputs, permissions, effects, retries, and examples for every Rinhelp tool.
sidebar:
  order: 2
---

MCP clients discover these tools automatically from `https://mcp.rinhelp.com/mcp`. The CLI uses the same names and input objects.

Use `account.whoami` first. The list below includes every tool available through Rinhelp's MCP server and CLI.

## Tool reference

The MCP server and CLI expose the same 23 tool names and input objects.

### Retry and duplicate prevention

`idempotency_key` identifies one request. If a request may have timed out, retry it with the same key and the same input. For example, retry `sources.start_crawl` with `idempotency_key: "help-site-1"` to check the original request instead of adding the website twice. Use a new key for a different request.

### `account.whoami`

Confirm which Rinhelp account, workspace, and role the client is using.

- **Permission:** `member`
- **Effect:** Shows your account, workspace, and role. It makes no changes.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

No inputs.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}
```

#### Example

```json
{}
```

### `sources.list`

List the websites you have added and their progress preparing pages for answers.

- **Permission:** `member`
- **Effect:** Reads the workspace website list.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`cursor` continues a paginated list. `limit` is an integer from 1 to 100.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
```

#### Example

```json
{
  "limit": 20
}
```

### `sources.start_crawl`

Add a public website so Rinhelp can use its pages in answers.

- **Permission:** `member`
- **Effect:** Returns a `run_id` while Rinhelp reads and prepares the pages. Use that value with `sources.show` until the work finishes.
- **Retry:** If the request may have timed out, retry with the same `url` and `idempotency_key`. Rinhelp returns the original request instead of adding the website twice.

#### Inputs

`url` is the public website URL. `idempotency_key` is a unique key for this request.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["url", "idempotency_key"],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "url": "https://example.com/help",
  "idempotency_key": "example-help-2026-09-15"
}
```

### `sources.show`

Check progress for a website you added and see the pages Rinhelp found.

- **Permission:** `member`
- **Effect:** Shows progress and the pages found.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`source_id` is the `run_id` returned by `sources.start_crawl`.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["source_id"],
  "properties": {
    "source_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "source_id": "run_01JEXAMPLE"
}
```

### `sources.show_page`

Read the text Rinhelp can use from one page.

- **Permission:** `member`
- **Effect:** Shows one page and its saved text.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`page_id` identifies the page from `sources.show`.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["page_id"],
  "properties": {
    "page_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "page_id": "page_01JEXAMPLE"
}
```

### `widget.show`

Read the current chat widget settings, publishable key, and installation snippet.

- **Permission:** `member`
- **Effect:** Reads widget configuration. The publishable key is safe to place in browser code.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

No inputs.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}
```

#### Example

```json
{}
```

### `widget.update_config`

Change one or more chat widget settings.

- **Permission:** `member`
- **Effect:** Saves the supplied settings and leaves omitted settings unchanged.
- **Retry:** Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

#### Inputs

`primary_color` accepts a color string. `position` is `bottom-right` or `bottom-left`. `title` and `greeting` are visitor-facing text.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "primary_color": {
      "type": "string"
    },
    "position": {
      "type": "string",
      "enum": ["bottom-right", "bottom-left"]
    },
    "title": {
      "type": "string"
    },
    "greeting": {
      "type": "string"
    }
  }
}
```

#### Example

```json
{
  "title": "Need a hand?",
  "greeting": "Ask us about setup or shipping.",
  "position": "bottom-right"
}
```

### `widget.preview`

Ask one test question against the help pages currently available to Rinhelp.

- **Permission:** `member`
- **Effect:** Returns one completed answer without creating a visitor conversation.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`message` is 1 to 4,000 characters.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["message"],
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    }
  }
}
```

#### Example

```json
{
  "message": "How long does shipping take?"
}
```

### `email.show`

Read the support address, forwarding destination, and email setup status.

- **Permission:** `member`
- **Effect:** Reads email settings. It does not change DNS or send mail.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

No inputs.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}
```

#### Example

```json
{}
```

### `email.setup`

Get a forwarding address for your support mailbox.

- **Permission:** `member`
- **Effect:** Creates or reuses the forwarding destination. Add the forwarding rule with your email provider.
- **Retry:** Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

#### Inputs

`support_email` is the customer-facing mailbox you want to forward from.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["support_email"],
  "properties": {
    "support_email": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "support_email": "support@example.com"
}
```

### `email.verify`

Send a test message to verify that forwarded support email reaches Rinhelp.

- **Permission:** `member`
- **Effect:** Starts a verification test. Check `email.show` for the resulting status.
- **Retry:** If the request may have timed out, retry with the same `idempotency_key`, then call `email.show` to check the test status.

#### Inputs

`idempotency_key` is a unique key for this test. Reuse it if the same test needs a retry.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["idempotency_key"],
  "properties": {
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "idempotency_key": "email-verify-example-1"
}
```

### `inbox.list`

List customer conversations in your team inbox.

- **Permission:** `member`
- **Effect:** Shows waiting chats and chats your team has taken over by default. `control=closed` reads closed conversations.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`cursor` continues a paginated list. `limit` is an integer from 1 to 100. `control` may be `closed`.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "control": {
      "type": "string",
      "enum": ["closed"]
    }
  }
}
```

#### Example

```json
{
  "limit": 20
}
```

### `inbox.list_items`

List all open inbox work, including conversations and pending Shopify refund requests.

- **Permission:** `member`
- **Effect:** Shows conversations and refund requests from the inbox. `control=closed` reads closed work.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`cursor` continues a paginated list. `limit` is an integer from 1 to 100. `control` may be `closed`.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "cursor": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "control": {
      "type": "string",
      "enum": ["closed"]
    }
  }
}
```

#### Example

```json
{
  "limit": 20
}
```

### `inbox.show`

Read one conversation and its messages.

- **Permission:** `member`
- **Effect:** Shows the saved conversation and messages.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

`conversation_id` identifies the conversation from an inbox list.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["conversation_id"],
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "conversation_id": "conversation_01JEXAMPLE"
}
```

### `inbox.reply`

Send a teammate reply in a visitor conversation.

- **Permission:** `member`
- **Effect:** Adds a teammate message. The first reply claims a waiting conversation for your team.
- **Retry:** If the request may have timed out, retry with the same conversation, message, and `idempotency_key`. Rinhelp avoids posting the same reply twice.

#### Inputs

`conversation_id` identifies the conversation. `message` is 1 to 4,000 characters. `idempotency_key` is a unique key for this reply.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["conversation_id", "message", "idempotency_key"],
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "conversation_id": "conversation_01JEXAMPLE",
  "message": "I can help with that. Your order ships tomorrow.",
  "idempotency_key": "reply-conversation-01"
}
```

### `inbox.end_live`

Close a live conversation after your team has finished helping the visitor.

- **Permission:** `member`
- **Effect:** Closes the chat and moves it to the closed inbox list.
- **Retry:** Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

#### Inputs

`conversation_id` identifies the live conversation.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["conversation_id"],
  "properties": {
    "conversation_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "conversation_id": "conversation_01JEXAMPLE"
}
```

### `team.show`

List the people in the workspace and, for owners, pending invitations.

- **Permission:** `member`
- **Effect:** Reads workspace access. Everyone can see the team; owners can also see pending invitations.
- **Retry:** Call it again if needed. It reads data and makes no changes.

#### Inputs

No inputs.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}
```

#### Example

```json
{}
```

### `team.invite`

Invite a person to join the workspace as a member.

- **Permission:** `owner`
- **Effect:** Sends an email invitation. A pending invitation for the same email is reused.
- **Retry:** Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

#### Inputs

`email` is the invitee address. This tool always creates the `member` role.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["email"],
  "properties": {
    "email": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "email": "teammate@example.com"
}
```

### `team.cancel_invite`

Cancel a pending workspace invitation.

- **Permission:** `owner`
- **Effect:** Invalidates the pending invitation so it can no longer be accepted.
- **Retry:** Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

#### Inputs

`invitation_id` identifies a pending invitation from `team.show`.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["invitation_id"],
  "properties": {
    "invitation_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

#### Example

```json
{
  "invitation_id": "invitation_01JEXAMPLE"
}
```

### `shopify.request_refund`

Look up an order and create a refund request for teammate review.

- **Permission:** `member`
- **Effect:** Adds a pending refund request. It does not refund the order.
- **Retry:** This creates a pending refund request only. If it may have timed out, retry with the same order details and `idempotency_key`, then wait for the request to appear before approving it.

#### Inputs

`order_number` and `email` identify the order. `amount` and `reason` are optional. `idempotency_key` identifies this refund request.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["order_number", "email", "idempotency_key"],
  "properties": {
    "order_number": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": "string",
      "minLength": 1
    },
    "amount": {
      "type": "string",
      "minLength": 1
    },
    "reason": {
      "type": "string",
      "minLength": 1
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "order_number": "1001",
  "email": "customer@example.com",
  "reason": "Wrong size",
  "idempotency_key": "refund-order-1001-1"
}
```

### `shopify.lookup_order`

Look up a Shopify order by its order number and email address.

- **Permission:** `member`
- **Effect:** Reads order status and tracking details. It does not change the order.
- **Retry:** If the request may have timed out, retry with the same order number, email, and `idempotency_key`. This tool only reads Shopify.

#### Inputs

`order_number` and `email` identify the order. `idempotency_key` identifies this lookup.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["order_number", "email", "idempotency_key"],
  "properties": {
    "order_number": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": "string",
      "minLength": 1
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "order_number": "1001",
  "email": "customer@example.com",
  "idempotency_key": "lookup-order-1001-1"
}
```

### `inbox.approve_action`

Approve a pending request and refund the order through Shopify.

- **Permission:** `member`
- **Effect:** Sends the refund to Shopify. Approving sends money back to the customer.
- **Retry:** If Shopify confirms a failure, retry with the same `action_id` and `idempotency_key`. If the result is unconfirmed, check the refund status before retrying.

#### Inputs

`action_id` is the `refund.id` from `inbox.list_items`. `idempotency_key` identifies this approval.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["action_id", "idempotency_key"],
  "properties": {
    "action_id": {
      "type": "string",
      "minLength": 1
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "action_id": "refund_action_01JEXAMPLE",
  "idempotency_key": "approve-refund-01"
}
```

### `inbox.reject_action`

Reject a pending refund request without refunding the order.

- **Permission:** `member`
- **Effect:** Marks the request rejected and does not call Shopify to create a refund.
- **Retry:** If the request may have timed out, retry with the same `action_id` and `idempotency_key`. This closes the request without sending a refund to Shopify.

#### Inputs

`action_id` is the `refund.id` from `inbox.list_items`. `idempotency_key` identifies this decision.

#### Input schema

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": ["action_id", "idempotency_key"],
  "properties": {
    "action_id": {
      "type": "string",
      "minLength": 1
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  }
}
```

#### Example

```json
{
  "action_id": "refund_action_01JEXAMPLE",
  "idempotency_key": "reject-refund-01"
}
```