Assistatron MCP — Agent Guide

You are connected to the Assistatron MCP server — an Iron Condor options trading platform.

CRITICAL: Always run the optimizer before trading

Do NOT call find_iron_condors without running create_strategy first. The optimizer analyses volatility regimes, compares probability-of-profit models, and scores candidates across multiple dimensions. Without it, you are using default parameters and the risk is significantly higher.

The correct workflow is always: create_strategy → get_strategy_status → save_strategy → find_iron_condors → trade.

Tool Discovery

After login and onboarding, you see 5 tools at root:

Tool Type What it does
account Hub Call to reveal profile, broker, billing, quota tools
strategy Hub Call to reveal optimizer, presets, saved strategies, chain scan
market_data Hub Call to reveal volatility analysis tools (IV rank, HV, EWMA, regime, GARCH)
trade Action Propose entry/roll/exit, confirm, cancel, list proposals
positions Action List positions, orders, risk, performance analytics

Hubs must be called first. Calling account, strategy, or market_data reveals their sub-tools for the rest of the session. trade and positions are always available.

The Workflow

1. strategy()                          → reveals strategy tools
2. create_strategy(ticker, max_capital) → returns job_id (runs in background)
3. get_strategy_status(job_id)          → poll until completed, get top_strategies
4. save_strategy(run_id, rank)          → bookmark a strategy, get saved_strategy_id
5. find_iron_condors(saved_strategy_id) → auto-loads search params, returns candidates
6. trade(action="propose_entry", ticker, candidate, qty, saved_strategy_id)
                                        → 60-second proposal, returns proposal id
7. trade(action="confirm", proposal_id) → submits order to broker

saved_strategy_id links the entire chain for audit. Pass it to both find_iron_condors and trade(propose_entry).

trade(action, ...)

Action Required params
propose_entry ticker, candidate (from find_iron_condors), qty. Optional: saved_strategy_id
propose_roll position_id, intent (full_roll or spread_roll)
propose_exit position_id
confirm proposal_id
cancel proposal_id
list Optional: status (pending/confirmed/expired/cancelled), limit

positions(action, ...)

Action Required params
list — (all open positions)
detail position_id
summary — (aggregate portfolio stats)
orders Optional: include_terminal
performance Optional: position_id (omit for aggregate)
assignment_risk position_id
autoroll_alerts Optional: limit, since
suggest_autoroll position_id

Account Hub Tools

Call account() first, then:

  • whoami — profile, tier, mode, active broker
  • get_accounts — broker accounts with balances
  • set_active_account(account_id) — switch active broker
  • connect_broker(broker, mode, ...) — add a new broker
  • set_risk_profile(...) — change risk tolerance
  • get_quota_remaining(tool_name) — check daily quota before calling
  • submit_feedback(message) — report bugs or request features
  • billing(action) — get_fees, get_subscription, or cancel_subscription

Error Handling

Errors return structured JSON:

{
  "error": "STRATEGY_NOT_CANDIDATE",
  "message": "You passed a strategy config, not a tradeable candidate.",
  "suggestion": "Call find_iron_condors first.",
  "see_tool": "find_iron_condors"
}
  • Parse error to decide what to do
  • Follow suggestion to self-correct
  • Call see_tool if provided
  • tier_upgrade_hint: true means the user needs premium

Common errors: ONBOARDING_REQUIRED, BROKER_NOT_CONNECTED, QUOTA_EXCEEDED, TIER_BLOCKED, STRATEGY_NOT_CANDIDATE.

market_data() → Volatility Tools

Call market_data to reveal vol analysis tools. Returns a summary (spot, IV rank) and unlocks:

Tool What it returns
vol_realised Yang-Zhang HV (30d/60d/252d window)
vol_implied Latest IV from history (HV proxy if no chain data)
vol_ratio RV/IV ratio + signal: iv_rich, iv_cheap, neutral
iv_rank IV rank (0–100%, 252-day lookback)
iv_percentile IV percentile (fraction of days below current)
iv_zscore Z-score of current IV vs historical distribution
ewma_vol EWMA vol (lambda=0.94, annualised)
vol_regime Regime label: low (<30%), mid (30–70%), high (>70%) based on IV rank
garch_forecast GJR-GARCH(1,1) forecast at 5/10/20d horizons — premium only
mean_reversion OU half-life of IV mean reversion — premium only

All tools take ticker as required parameter. Use vol_regime or iv_rank to decide if conditions are right for selling premium (high IV rank = good for Iron Condors).

Tier System

Free: lognormal PoP, Yang-Zhang vol, SVI surface, CRR pricer, bootstrap sim. 200 trials, 400 paths, 2 years. 10 create_strategy/day, 500 find_iron_condors/day. All vol tools except GARCH and mean-reversion.

Premium: all algorithms, 500 trials, 3000 paths, 10 years, unlimited quotas. Full vol suite including GARCH forecasts and mean-reversion analytics.

Rules

  1. Always run the optimizer first. Call create_strategy before find_iron_condors. Skipping it means trading with default parameters and no volatility analysis.
  2. Never pass strategy results to propose_entry. Call find_iron_condors first.
  3. Proposals expire in 60 seconds. Confirm or cancel promptly.
  4. Check quota before searching. Use get_quota_remaining.
  5. create_strategy is async. Returns job_id — poll with get_strategy_status.
  6. Use saved_strategy_id everywhere. Links the full audit trail.
  7. Read legal docs before onboarding steps. Call get_legal_document and give the user a link before accept_eua, acknowledge_risk, or set_broker_keys.
  8. Never call external APIs directly. All actions go through MCP tools. Do not use curl, fetch, or HTTP requests to assistatron.com or api.assistatron.com.
  9. Never expose tokens or credentials. Do not print, log, or show access tokens, refresh tokens, API keys, or secrets to the user.