> ## Documentation index
> Fetch the complete documentation index at: [llms.txt](../llms.txt)
> Use this file to discover all available pages before exploring further.

# Onboarding and health tools

Eight tools that set up a new account from inside an AI tool, step by step, and check that the server is up.

Someone who connects Sleuth to an AI tool before they have an account can set up their account without leaving the chat. Before a new user's first task, or when any tool returns `onboarding_required`, call `get_onboarding_status` and follow only the `current_step` and `next_action` it returns. People who already use Studio skip most of this.

## The steps

| `current_step` | What the user does | Tool |
| --- | --- | --- |
| `role` | Confirms their job title, and optionally a LinkedIn URL and a description of their role | `save_onboarding_role` |
| `setup` | Chooses where they'll use Sleuth: Studio, their AI tool, or both | `save_onboarding_usage_mode` |
| `use_cases` | Picks and orders the jobs they want done | `save_onboarding_use_cases` |
| `work_style` | Answers a few questions about how they work | `save_onboarding_work_style` |
| `access_request` | Requests access, in Studio or right in the chat | `submit_onboarding_access_request` |
| Browser steps | Accepts policies or joins a workspace in the browser, then reconnects the AI tool | None: ask the user to refresh the connection, then check status again |
| `mcp_setup` | Confirms the connection works | `complete_mcp_setup` |

When `next_action` is `await_approval`, the request is with Sleuth. Tell the user it needs approval and that they'll get an email.

> **For agents:** Confirm every value with the user before you save it, and never fill in a value they didn't give. Use plain, customer-facing words, and don't tell the user what role or access their account has.

### `get_onboarding_status`

Get the user’s onboarding state: `current_step`, `next_action`, and anything already filled in. Call it before a new user’s first task and after any `onboarding_required` error.

*No inputs.*

### `save_onboarding_role`

Save the user’s role. Use only when `current_step` is `role`.

| Input | Type | Notes |
| --- | --- | --- |
| `job_title` (required) | string | Confirmed with the user |
| `linkedin_url` | string |  |
| `role_description` | string |  |

### `save_onboarding_usage_mode`

Save where the user will use Sleuth. Use only when `current_step` is `setup`.

| Input | Type | Notes |
| --- | --- | --- |
| `usage_mode` (required) | string | `studio`, `mcp`, or `both` |

### `save_onboarding_use_cases`

Save the user’s jobs in priority order, using the IDs from `state.use_cases`. Use only when `current_step` is `use_cases`.

| Input | Type | Notes |
| --- | --- | --- |
| `use_cases` (required) | string[] | IDs in the user’s order |

### `save_onboarding_work_style`

Save the user’s work-style answers, using the question and option IDs from `get_onboarding_status`. Leave out questions they didn’t answer. Use only when `current_step` is `work_style`.

| Input | Type | Notes |
| --- | --- | --- |
| `answers` (required) | object[] | Each with `question_id`, `selected` option IDs, and optional `other` text |

### `submit_onboarding_access_request`

Submit an access request from the chat. Use only when `current_step` is `access_request` and the user chose to request it here instead of in Studio.

| Input | Type | Notes |
| --- | --- | --- |
| `company_name` (required) | string | Confirmed with the user |
| `country` (required) | string | Confirmed with the user |
| `company_website` | string | Needed when the user signed in with a work email |
| `linkedin_url` | string | Needed when the user signed in with a personal email |
| `first_name` | string | Only if status didn’t return it |
| `last_name` | string | Only if status didn’t return it |

### `complete_mcp_setup`

Finish setup once the user confirms the connection works. Use only when `current_step` is `mcp_setup`.

*No inputs.*

### `get_health`

Check that the server and Sleuth’s API are up. It still needs a signed-in connection.

*No inputs.*

## Related

- [Sign up and get access](sign-up.md): How to request an account, what approval looks like, and what onboarding asks.
- [Fix connection problems](ai-troubleshooting.md): The most common problems connecting Sleuth to an AI tool, and how to fix each one.
- [Errors and limits](mcp-errors.md): Every limit an agent can hit on the Sleuth MCP server, and what to do about each error.

*Updated November 9, 2026.*
