MCP tool: ai_brief

Last verified2026-07-20

ai_brief answers “what’s the platform’s current risk read” and “how has that read graded out historically” in one call. It wraps AI-2’s PUBLIC verdict + history routes — GET /api/v1/ai2/verdict and GET /api/v1/ai2/history — fanned out concurrently, and returns a trimmed combination of both.

Signature

ai_brief(
  limit: int | None = None,   # recent AI-2 verdict cycles to fold into the track-record grades, 1-200. Omit for the live default (60).
) -> str                      # JSON-serialised dict

limit outside 1..200 raises ValueError before the round-trip — mirrors the backend’s Query(1, ge=1, le=200) on /ai2/history.

Returns

{
  "verdict": {
    "available": true,
    "as_of": "2026-07-20T16:15:00-04:00",
    "source": "persisted",
    "risk": { "band": "elevated" },
    "magnitude": { "expectation": "normal" },
    "regime": { "label": "CAUTIOUS" },
    "likelihood": {
      "summary": "Based on 214 broadly similar historical days (effective sample 88.4 after recency weighting) — treat this as a historical base rate, not a forecast.",
      "n_analogues": 214,
      "effective_count": 88.4
    },
    "what_flips_it": [
      { "label": "Gamma flip", "level": 552.0, "risk_direction": "risk_up", "plain": "If Gamma flip trips, today's risk reading would likely get worse. (level: 552)" }
    ],
    "uncertainty_note": "Caveats: the move-size read is an early, uncalibrated research read. This is a read of today's conditions — how risky, and how big a move to expect. No one here has a validated edge on which way the market will go."
  },
  "history": {
    "cycles_recorded": 412,
    "tracking_started": "2026-07-08",
    "grades": {
      "magnitude": { "verdict": "insufficient_data", "n_matured": 0, "n_verdicts_in_range": 60, "forward_validated": false },
      "risk_band": { "verdict": "insufficient_data", "n_verdicts_in_range": 60 },
      "direction": { "verdict": "insufficient_data", "validated": false, "n_trade_dates_graded": 0 }
    },
    "reason": null
  }
}

verdict.risk.band (low / elevated / high, or null) is the validated drawdown-composite band, mechanically passed through — never a re-judgment.
verdict.magnitude.expectation (small / normal / big, or null) is a move-SIZE read, ALWAYS “either direction” — never a validated dial (calibrated is always false on the full verdict; this projector drops that flag since it’s constant).
verdict.regime.label is the market-backdrop state (e.g. CAUTIOUS), no forecast attached.
No direction, stance, hit_rate, play, bias, or buy/sell field exists anywhere on this object — by construction, not by convention. A field that doesn’t exist cannot leak a which-way call. See app/signals/ai2_verdict.py:build_verdict’s docstring for the honesty design.
verdict.source is "persisted" (today’s scheduler-served verdict) or "computed" (a live fallback when nothing persisted today — never written back, so a popular tool call can’t manufacture a graded row).
history.grades are the DISTILLED track-record verdicts (insufficient_data / on_track / off_track for risk_band; insufficient_data / confirms / tracking / falsified for magnitude; the same four for direction) — never a bare hit-rate. Research internals (per-era breakdowns, bootstrap CIs, verdict_config_version hashes) stay behind the internal-gated /ai2/risk-grade / /ai2/magnitude-grade / /ai2/direction-grade routes.
history.grades.direction reads insufficient_data by default in most deployments — the LLM-variant direction call is gated behind ENABLE_AI2_LLM_VARIANT (default OFF), so n_trade_dates_graded stays 0 until an operator flips it on.

Unavailable verdict

{ "verdict": { "available": false, "reason": "verdict unavailable — the read could not be built" }, "history": { "cycles_recorded": 0, "tracking_started": null, "grades": { "...": "insufficient_data" }, "reason": "tracking has just begun — 0 cycles recorded" } }

/ai2/verdict and /ai2/history never 500 or 404 (DOCTRINE P0) — an unavailable read degrades to available: false / verdict: null with a plain reason, same as an honest cold start.

Behaviour

Cache TTL. CACHE_TTL_AI_BRIEF = 60s (mcp/mcp_server/config.py). AI-2’s verdict is served persisted-first (today’s scheduler-produced row) with a live-compute fallback — a minute-scale TTL is generous coverage without risking a stale read across a scheduler cycle.
Concurrent fan-out. verdict and history are fetched via asyncio.gather() — one network leg’s worth of latency for both.
Trimmed, not the full verdict object. The backend’s /ai2/verdict response also carries downturn_read (a plain relabel of risk.band) and whats_happening (AI-1’s plain-language summary, already reachable via read_report) — dropped here to avoid duplicating the same signal under two names. risk / magnitude / regime keep only their categorical field; each object’s free-text one_plain_sentence is dropped since likelihood + uncertainty_note already carry the prose an agent needs.
Public — no token. Both wrapped routes are unauthenticated; unlike the retired internal surface, ai_brief needs no INTERNAL_API_TOKEN and works on every deployment.

Examples

What’s the platform’s current risk read?

Operator: "What's the risk read right now?"
Agent: ai_brief()
  -> read verdict.risk.band, verdict.magnitude.expectation, verdict.what_flips_it

How has AI-2’s read graded out?

Operator: "Has this actually been tracking reality?"
Agent: ai_brief()
  -> read history.grades.risk_band.verdict, history.grades.magnitude.verdict

Wider track-record window

Agent: ai_brief(limit=150)

When to use

An agent or operator asking for the platform’s current risk/magnitude/regime read on SPY — never a directional call.
Checking AI-2’s track record before weighting a specific read.
Any deployment — public, no token setup required.

When NOT to use

You want a directional call on SPY — this tool structurally cannot answer that; nothing on the platform’s AI surfaces carries a validated directional edge.
You want the platform’s mechanical screener picks — use screener_board.
You want the full narrative report (macro, credit, energy, more) — use read_report.
You want live signal data rather than the platform’s synthesis of it — use market_pulse or analyze_signals.