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 resources 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

accept_eua
    |
    v
acknowledge_risk
    |
    v
set_risk_profile
    |
    v
set_account_mode  --->  set_broker_keys
                            |
                            v
                        ONBOARDING COMPLETE
                            |
                            v
                        Trading tools unlocked
                        (account, strategy, trade, positions)

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

Read the legal://eua MCP resource to get the full EUA text, then present it to the user.

Parameters

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

Response: OnboardingActionResult

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

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

Read the legal://risk-disclosure MCP resource, 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-04-draft" Version of the risk disclosure

Response: OnboardingActionResult

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

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

Step 4a: set_account_mode

Set the preferred trading mode (paper or live).

This does NOT complete onboarding. The user must still provide broker API keys via set_broker_keys, even for paper mode.

Parameter Type Required Description
mode string Yes "paper" or "live"

Response: OnboardingActionResult

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

Step 4b: 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.

Parameter Type Required Default Description
broker string Yes -- Broker name (currently "alpaca")
mode string Yes -- "paper" or "live"
api_key string Yes -- Broker API key
api_secret string Yes -- Broker API secret
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.

Alternative: start_broker_connection

Start an OAuth2 broker connection instead of using API keys.

Parameter Type Required Description
broker string Yes Broker name (currently "alpaca")

Returns an authorization URL. The agent must present DDQ-required disclosure text before giving the user the URL. After the user approves in their browser, a webhook completes the connection.

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

  1. 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.

  2. Legal resources must be presented first. The agent MUST read and present legal://eua and legal://risk-disclosure resources before calling accept_eua and acknowledge_risk. Calling these tools without presenting the legal text first is a compliance violation.

  3. Onboarding is one-time. Once complete, these tools are hidden from the MCP tool list. The hub tools (account, strategy, trade, positions) replace them.

  4. 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