Tools reference

Inputs, permissions, effects, retries, and examples for every Rinhelp tool.

AI apps connected to Rinhelp find these tools at https://mcp.rinhelp.com/mcp. The Rinhelp command-line tool uses the same names and inputs.

Use account.whoami first to check which account and workspace are connected. The list below includes every tool available to AI apps and the command line.

Tool reference

AI apps and the command-line tool use the same 26 tools and inputs.

Retry without repeating work

idempotency_key is a retry key for one request. If a request may have timed out, retry it with the same key and input. Rinhelp will continue the first request instead of repeating the action. Use a new key for a new request.

account.whoami

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

• Who can use it: member
• What it does: Shows your account, workspace, and role. It makes no changes.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

No inputs.

Accepted input

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

Example

{}

sources.list

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

• Who can use it: member
• What it does: Reads the workspace website list.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

Use the cursor from a previous response to see the next results. limit sets how many results to return, from 1 to 100.

Accepted input

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

Example

{
  "limit": 20
}

sources.start_crawl

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

• Who can use it: member
• What it does: Returns a run_id while Rinhelp reads and prepares the pages. Use that value with sources.show until the work finishes.
• If it fails or times out: 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.

What to provide

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

Accepted input

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

Example

{
  "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.

• Who can use it: member
• What it does: Shows progress and the pages found.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

source_id is the run_id returned by sources.start_crawl.

Accepted input

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

Example

{
  "source_id": "run_01JEXAMPLE"
}

sources.show_page

Read the text Rinhelp can use from one page.

• Who can use it: member
• What it does: Shows one page and its saved text.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

page_id identifies the page from sources.show.

Accepted input

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

Example

{
  "page_id": "page_01JEXAMPLE"
}

widget.show

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

• Who can use it: member
• What it does: Reads widget configuration. The publishable key is safe to place in browser code.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

No inputs.

Accepted input

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

Example

{}

widget.update_config

Change one or more chat widget settings.

• Who can use it: member
• What it does: Saves the supplied settings and leaves omitted settings unchanged.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

primary_color accepts a color string. position is bottom-right or bottom-left. title and greeting are text your customers see.

Accepted input

{
  "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

{
  "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.

• Who can use it: member
• What it does: Returns one completed answer without creating a customer conversation.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

message is 1 to 4,000 characters.

Accepted input

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

Example

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

email.show

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

• Who can use it: member
• What it does: Reads email settings. It does not change domain settings or send email.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

No inputs.

Accepted input

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

Example

{}

email.setup

Set up sending and receiving for your team email address.

• Who can use it: member
• What it does: Creates or reuses the sending setup and forwarding address. It does not change where your domain receives mail.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

email is the address your team uses to send and receive customer email.

Accepted input

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

Example

{
  "email": "hello@example.com"
}

email.verify

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

• Who can use it: member
• What it does: Starts a verification test. Check email.show for the resulting status.
• If it fails or times out: If the request may have timed out, retry with the same idempotency_key, then call email.show to check the test status.

What to provide

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

Accepted input

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

Example

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

email.sending.show

Read the team sending address, domain records, and verification status.

• Who can use it: member
• What it does: Reads sending settings. It does not change domain settings or send email.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

No inputs.

Accepted input

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

Example

{}

email.sending.setup

Create or reuse the setup for sending from your team address.

• Who can use it: member
• What it does: Returns the two domain records you need to add with your domain provider.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

sending_email is the address Rinhelp will use to send email.

Accepted input

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

Example

{
  "sending_email": "hello@example.com"
}

email.sending.verify

Check whether the sending domain records are verified.

• Who can use it: member
• What it does: Checks both records. Rinhelp cannot send from the team address until both pass.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

No inputs.

Accepted input

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

Example

{}

inbox.list

List customer conversations in your team inbox.

• Who can use it: member
• What it does: Shows waiting chats and chats your team has taken over by default. control=closed reads closed conversations.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

Use the cursor from a previous response to see the next results. limit sets how many results to return, from 1 to 100. Set control to closed to see closed conversations.

Accepted input

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

Example

{
  "limit": 20
}

inbox.list_items

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

• Who can use it: member
• What it does: Shows conversations and refund requests from the inbox. control=closed reads closed work.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

Use the cursor from a previous response to see the next results. limit sets how many results to return, from 1 to 100. Set control to closed to see closed work.

Accepted input

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

Example

{
  "limit": 20
}

inbox.show

Read one conversation and its messages.

• Who can use it: member
• What it does: Shows the saved conversation and messages.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

conversation_id identifies the conversation from an inbox list.

Accepted input

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

Example

{
  "conversation_id": "conversation_01JEXAMPLE"
}

inbox.reply

Send a teammate reply in a customer conversation.

• Who can use it: member
• What it does: Adds a teammate message. The first reply claims a waiting conversation for your team.
• If it fails or times out: If the request may have timed out, retry with the same conversation, message, and idempotency_key. Rinhelp avoids posting the same reply twice.

What to provide

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

Accepted input

{
  "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

{
  "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 customer.

• Who can use it: member
• What it does: Closes the chat and moves it to the closed inbox list.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

conversation_id identifies the live conversation.

Accepted input

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

Example

{
  "conversation_id": "conversation_01JEXAMPLE"
}

team.show

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

• Who can use it: member
• What it does: Reads workspace access. Everyone can see the team; owners can also see pending invitations.
• If it fails or times out: Call it again if needed. It reads data and makes no changes.

What to provide

No inputs.

Accepted input

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

Example

{}

team.invite

Invite a person to join the workspace as a member.

• Who can use it: owner
• What it does: Sends an email invitation. A pending invitation for the same email is reused.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

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

Accepted input

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

Example

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

team.cancel_invite

Cancel a pending workspace invitation.

• Who can use it: owner
• What it does: Invalidates the pending invitation so it can no longer be accepted.
• If it fails or times out: Repeat it with the same input if needed. Rinhelp applies the same result without creating another one.

What to provide

invitation_id identifies a pending invitation from team.show.

Accepted input

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

Example

{
  "invitation_id": "invitation_01JEXAMPLE"
}

shopify.request_refund

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

• Who can use it: member
• What it does: Adds a pending refund request. It does not refund the order.
• If it fails or times out: 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.

What to provide

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

Accepted input

{
  "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

{
  "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.

• Who can use it: member
• What it does: Reads order status and tracking details. It does not change the order.
• If it fails or times out: If the request may have timed out, retry with the same order number, email, and idempotency_key. This tool only reads Shopify.

What to provide

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

Accepted input

{
  "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

{
  "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.

• Who can use it: member
• What it does: Sends the refund to Shopify. Approving sends money back to the customer.
• If it fails or times out: 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.

What to provide

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

Accepted input

{
  "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

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

inbox.reject_action

Reject a pending refund request without refunding the order.

• Who can use it: member
• What it does: Marks the request rejected and does not call Shopify to create a refund.
• If it fails or times out: 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.

What to provide

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

Accepted input

{
  "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

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