Hub Tools -- Progressive Discovery

Assistatron uses a progressive discovery model. After login and onboarding, the agent sees exactly 5 tools. Calling a hub tool reveals its sub-tools for the rest of the session. This keeps the tool list small and focused.

See MCP_GRAPH.md for the full visibility graph and implementation details.

Root Tools (always visible post-onboarding)

account

Open the account hub. Reveals profile, broker, billing, quota, and feedback tools.

Parameters: None.

Response:

{
  "hub": "account",
  "tools_revealed": [
    {"name": "whoami",              "summary": "Your profile, tier, mode, and active broker account"},
    {"name": "get_accounts",        "summary": "List connected broker accounts with balances"},
    {"name": "set_active_account",  "summary": "Switch which broker account is active for trading"},
    {"name": "connect_broker",      "summary": "Connect a new broker account (Alpaca)"},
    {"name": "set_risk_profile",    "summary": "Change your experience level and risk tolerance"},
    {"name": "get_quota_remaining", "summary": "Check daily tool usage limits before calling"},
    {"name": "submit_feedback",     "summary": "Report bugs or request features"},
    {"name": "billing",             "summary": "View fees, check subscription, or cancel"}
  ],
  "hint": "These tools are now available. Call any of them directly."
}

Behavior: Idempotent. Calling again returns the same menu without re-notifying the client. Sub-tools remain visible for the rest of the session.

See also: account.md

strategy

Open the strategy hub. Reveals optimizer, preset, saved strategies, and chain scan tools.

Parameters: None.

Response:

{
  "hub": "strategy",
  "tools_revealed": [
    {"name": "create_strategy",          "summary": "Run the optimizer to find optimal IC strategies"},
    {"name": "get_strategy_status",      "summary": "Check optimizer job progress and retrieve results"},
    {"name": "get_presets",              "summary": "View available optimizer presets"},
    {"name": "save_strategy",            "summary": "Bookmark a strategy from optimizer results"},
    {"name": "get_saved_strategies",     "summary": "List your bookmarked strategies"},
    {"name": "delete_strategy",          "summary": "Delete a saved strategy"},
    {"name": "set_active_strategy",      "summary": "Set or clear the active strategy for trading"},
    {"name": "get_optimization_history", "summary": "View past optimizer runs"},
    {"name": "find_iron_condors",        "summary": "Scan live options chain for tradeable IC candidates"},
    {"name": "get_search_status",        "summary": "Poll background candidate search for results"}
  ],
  "hint": "These tools are now available. Call any of them directly."
}

See also: create-strategy.md, find-iron-condors.md

market_data

Open the market data hub. Reveals three sub-hubs: volatility, pricing, and scoring. Each sub-hub reveals its own tools when called.

Parameters: None.

Response:

{
  "hub": "market_data",
  "tools_revealed": [
    {"name": "volatility", "summary": "Volatility analytics — HV, IV, rank, regime, GARCH, mean-reversion"},
    {"name": "pricing",    "summary": "Option pricing models — Heston stochastic vol, SABR smile [premium]"},
    {"name": "scoring",    "summary": "Portfolio scoring — Sortino and Sharpe ratios [premium]"}
  ],
  "hint": "Call any sub-hub to reveal its tools. Each stays visible for the session."
}

Sub-hub: volatility

Call volatility to reveal 10 volatility analysis tools:

Tool Summary Tier
vol_realised Yang-Zhang realised HV (30/60/252d) Free
vol_implied Latest implied vol from IV history Free
vol_ratio RV/IV ratio with directional signal Free
iv_rank IV rank (0-1) over 252-day window Free
iv_percentile IV percentile over 252-day window Free
iv_zscore IV z-score relative to 252-day mean Free
ewma_vol EWMA volatility (lambda=0.94) Free
vol_regime Regime classification (low/mid/high) Free
garch_forecast GARCH vol forecast at 5d/10d/20d horizons Premium
mean_reversion Ornstein-Uhlenbeck half-life of IV Premium

Sub-hub: pricing

Call pricing to reveal 2 option pricing model tools (premium only):

Tool Summary
heston_price Heston stochastic vol model prices
sabr_smile SABR implied volatility smile calibration

Both accept ticker (required) and expiry (optional, defaults to nearest).

Sub-hub: scoring

Call scoring to reveal 2 portfolio scoring tools (premium only):

Tool Summary
portfolio_sortino Sortino ratio from position P&L history
portfolio_sharpe Sharpe ratio from position P&L history

Both accept optional ticker filter. Omit for full portfolio.

trade

Action dispatch tool for all trading operations. Always visible at root -- no hub expansion needed.

See: trade.md for the 7 actions and their parameters.

positions

Action dispatch tool for position queries and analytics. Always visible at root -- no hub expansion needed.

See: positions.md for the 8 actions and their parameters.

How Progressive Discovery Works

Session state

The server tracks which hubs have been opened in the session:

MCPHandlers._opened_hubs: set[str]  # e.g. {"account", "strategy", "market_data"}

Tool filtering

ROOT_TOOLS = {account, strategy, market_data, trade, positions}

if onboarded:
    allowed = ROOT_TOOLS
    for hub in opened_hubs:
        allowed |= HUB_SUBTOOL_SETS[hub]
    return [t for t in all_tools if t.name in allowed]

Tool count by stage

Stage Visible tools
Root (3 hubs + trade + positions) 5
+ account hub opened 13 (+8)
+ strategy hub opened 23 (+10)
+ market_data hub opened 26 (+3 sub-hubs)
+ volatility sub-hub opened 36 (+10)
+ pricing sub-hub opened 38 (+2)
+ scoring sub-hub opened 40 (+2)

Why this matters

LLM agents perform better with fewer tools. The progressive model means the agent only sees what is relevant to the current task. An agent focused on trading sees trade and positions immediately. An agent helping with account setup calls account first to reveal the management tools. An agent doing volatility analysis calls market_data then volatility to reveal the analytics tools without cluttering the strategy or trading context.

Cross-references