Onboarding Tools

Step-by-step tools that walk a new user through setup. Onboarding must be completed before trading tools become available. The order of steps matters -- legal documents must be presented first.

These tools are visible immediately after authentication (no hub expansion needed). Once onboarding is complete, they are hidden from the MCP tool list and replaced by the root hub tools.

Onboarding Flow

get_legal_document(name='eua')  -->  accept_eua
                                        |
                                        v
get_legal_document(name='risk-disclosure')  -->  acknowledge_risk
                                                    |
                                                    v
                                              set_risk_profile
                                                    |
                            +-----------------------+-----------------------+
                            |                                               |
                            v                                               v
                    activate_demo_mode                              set_account_mode
                            |                                               |
                            v                                               v
                    ONBOARDING COMPLETE               get_legal_document(name='alpaca-authorization')
                            |                                               |
                            v                                               v
                    Trading tools unlocked                  set_broker_keys(authorization_confirmed=True)
                                                                            |
                                                                            v
                                                                    ONBOARDING COMPLETE
                                                                            |
                                                                            v
                                                                    Trading tools unlocked

Two paths after set_risk_profile:

Demo mode: call activate_demo_mode to skip broker connection entirely. Uses simulated positions with $100k virtual capital.
Broker mode: call set_account_mode, then present the Alpaca authorization disclosure and connect with set_broker_keys.

Both paths unlock the same trading tools (account, strategy, trade, positions).

`get_legal_document`

Retrieve a legal document by name. Call this before the corresponding onboarding step -- the system tracks which documents have been read and will reject the step if the document was not retrieved first.

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	`"eua"`, `"risk-disclosure"`, or `"alpaca-authorization"`

Response

Returns the full document text as markdown.

Web links

If the chat format makes full text impractical, give the user the web link:

EUA: https://assistatron.com/docs/eua
Risk disclosure: https://assistatron.com/docs/risk-disclosure
Alpaca authorization: https://assistatron.com/docs/alpaca-authorization

Error codes

Code	Cause
`INVALID_DOCUMENT`	Unknown document name

Step 1: `accept_eua`

Accept the End User Agreement. Legal requirement: the agent MUST present the full EUA text to the user before calling this tool.

Pre-requisite

Call get_legal_document(name='eua') to get the full EUA text, then present it to the user verbatim. The system will reject the call with DOCUMENT_NOT_READ if the document was not retrieved first.

Parameters

Parameter	Type	Required	Default	Description
`confirmed`	bool	Yes	--	Must be `true`. Only call after explicit user agreement
`eua_version`	string	No	"2026-05-draft"	Version of the EUA being accepted

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "eua",
  "message": "End User Agreement accepted.",
  "next_step": "acknowledge_risk"
}

Error codes

Code	Cause
`DOCUMENT_NOT_READ`	`get_legal_document(name='eua')` was not called first

Step 2: `acknowledge_risk`

Acknowledge the options trading risk disclosure. Legal requirement: the agent MUST present the full risk disclosure to the user before calling this.

Pre-requisite

Call get_legal_document(name='risk-disclosure'), then present it to the user.

Parameters

Parameter	Type	Required	Default	Description
`confirmed`	bool	Yes	--	Must be `true`. Only call after explicit user acknowledgement
`risk_version`	string	No	"2026-05-draft"	Version of the risk disclosure

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "risk",
  "message": "Risk disclosure acknowledged.",
  "next_step": "set_risk_profile"
}

Error codes

Code	Cause
`DOCUMENT_NOT_READ`	`get_legal_document(name='risk-disclosure')` was not called first

Step 3: `set_risk_profile`

Set the user's experience level and risk tolerance. This determines the default optimizer preset.

Parameters

Parameter	Type	Required	Description
`options_experience`	string	Yes	`"never"`, `"a_few_times"`, or `"regularly"`
`iron_condor_experience`	string	Yes	`"never"`, `"understand_not_traded"`, or `"yes"`
`risk_tolerance`	string	Yes	`"conservative"`, `"moderate"`, or `"aggressive"`

Preset mapping

Risk tolerance	Default preset
conservative	Conservative (high PoP floor, tight delta ranges)
moderate	Balanced (standard ranges)
aggressive	Aggressive (wider ranges, lower PoP floor)

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "risk_profile",
  "message": "Risk profile set to moderate.",
  "next_step": "set_account_mode | set_broker_keys | start_broker_connection"
}

After this step, the user chooses between demo mode or broker connection.

Step 4 (option A): `activate_demo_mode`

Activate demo mode -- skip broker connection and start trading immediately.

Demo mode provides the full experience without an Alpaca account:

Run the strategy optimizer
Find iron condor candidates
Simulate trades with internally tracked positions
See mark-to-market P&L using delayed market data
$100,000 virtual starting capital

When the user is ready to trade with real money, they can connect their Alpaca account at any time via set_broker_keys.

Parameters

None.

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "demo",
  "message": "Demo mode activated. You can start trading!",
  "next_step": null
}

When next_step is null, onboarding is complete and trading tools are now available.

Step 4 (option B): `set_account_mode`

Set the preferred trading mode. "live" is a premium feature and is additionally gated by a platform-wide switch; while live trading is under test the switch is off and any request for "live" is rejected (use "paper"). "live" returns TIER_BLOCKED for non-premium users and LIVE_TRADING_DISABLED while the platform switch is off.

This does NOT complete onboarding. The user must still provide broker API keys via set_broker_keys.

Parameter	Type	Required	Description
`mode`	string	Yes	`"paper"` (or `"live"` — premium, when enabled)

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "account_mode",
  "message": "Account mode set to paper.",
  "next_step": "set_broker_keys"
}

Step 5: `set_broker_keys`

Connect a broker using API keys. Validates credentials against the broker, encrypts them, and stores them. Completes onboarding if all previous steps are done.

Pre-requisite

Before calling this tool you MUST:

Call get_legal_document(name='alpaca-authorization').
Present the full text verbatim or give the user a link: https://assistatron.com/docs/alpaca-authorization
Wait for the user to explicitly confirm they agree.
Call with authorization_confirmed=True.

Parameters

Parameter	Type	Required	Default	Description
`broker`	string	Yes	--	Broker name (currently "alpaca")
`mode`	string	Yes	--	"paper"
`api_key`	string	Yes	--	Broker API key
`api_secret`	string	Yes	--	Broker API secret
`authorization_confirmed`	bool	Yes	`false`	Must be `true` after user reads authorization disclosure
`label`	string	No	null	Optional display name

Response: `OnboardingActionResult`

{
  "ok": true,
  "step": "broker",
  "message": "Broker connected. Onboarding complete!",
  "next_step": null
}

When next_step is null, onboarding is complete and trading tools are now available.

Error codes

Code	Cause
`AUTHORIZATION_NOT_CONFIRMED`	`get_legal_document(name='alpaca-authorization')` was not called, or `authorization_confirmed` is `false`

Alternative: `start_broker_connection`

Start an OAuth2 broker connection instead of using API keys.

Pre-requisite

Same as set_broker_keys -- call get_legal_document(name='alpaca-authorization') and present it to the user first.

Parameters

Parameter	Type	Required	Default	Description
`broker`	string	Yes	--	Broker name (currently "alpaca")
`authorization_confirmed`	bool	Yes	`false`	Must be `true` after user reads authorization disclosure

Returns an authorization URL. After the user approves in their browser, a webhook completes the connection.

Error codes

Code	Cause
`AUTHORIZATION_NOT_CONFIRMED`	`get_legal_document(name='alpaca-authorization')` was not called, or `authorization_confirmed` is `false`

`get_onboarding_status`

Check what onboarding steps remain. Available at any time during the onboarding flow.

Parameters: None.

Response: `OnboardingStatusResult`

{
  "complete": false,
  "current_step": "risk",
  "steps_remaining": ["risk", "account_mode", "broker"]
}

When complete is true, all trading tools are unlocked.

Key Rules

Order matters. The EUA must be accepted before risk acknowledgement. Risk must be acknowledged before setting a risk profile. All three must be done before connecting a broker or activating demo mode.
Legal documents must be retrieved first. The agent MUST call get_legal_document and present the text before calling accept_eua, acknowledge_risk, set_broker_keys, or start_broker_connection. Calling these tools without retrieving the document first produces a DOCUMENT_NOT_READ or AUTHORIZATION_NOT_CONFIRMED error.
Onboarding is one-time. Once complete, these tools are hidden from the MCP tool list. The hub tools (account, strategy, trade, positions) replace them.
Post-onboarding changes. After onboarding, use set_risk_profile (via the account hub) to update risk tolerance, and connect_broker to add new accounts.

Cross-references

auth.md -- authentication must happen before onboarding
hub-tools.md -- tools revealed after onboarding
account.md -- post-onboarding account management
../guides/getting-started.md -- full getting started guide

Onboarding Tools

Onboarding Flow

get_legal_document

Parameters

Response

Web links

Error codes

Step 1: accept_eua

Pre-requisite

Parameters

Response: OnboardingActionResult

Error codes

Step 2: acknowledge_risk

Pre-requisite

Parameters

Response: OnboardingActionResult

Error codes

Step 3: set_risk_profile

Parameters

Preset mapping

Response: OnboardingActionResult

Step 4 (option A): activate_demo_mode

Parameters

Response: OnboardingActionResult

Step 4 (option B): set_account_mode

Response: OnboardingActionResult

Step 5: set_broker_keys

Pre-requisite

Parameters

Response: OnboardingActionResult

Error codes

Alternative: start_broker_connection

Pre-requisite

Parameters

Error codes

get_onboarding_status

Response: OnboardingStatusResult

Key Rules

Cross-references

`get_legal_document`

Step 1: `accept_eua`

Response: `OnboardingActionResult`

Step 2: `acknowledge_risk`

Response: `OnboardingActionResult`

Step 3: `set_risk_profile`

Response: `OnboardingActionResult`

Step 4 (option A): `activate_demo_mode`

Response: `OnboardingActionResult`

Step 4 (option B): `set_account_mode`

Response: `OnboardingActionResult`

Step 5: `set_broker_keys`

Response: `OnboardingActionResult`

Alternative: `start_broker_connection`

`get_onboarding_status`

Response: `OnboardingStatusResult`