KB / mcp

MCP tool: market_pulse

Last verified 2026-05-26

market_pulse is the single-call session opener. One round-trip returns the current regime label, the 0–100 health score, active alert counts by severity, the “what changed since the last report” delta, and a curated key-numbers block (SPY, VIX, DIX, GEX, breadth). It wraps GET /api/v1/agents/pulse — the same surface the dashboard and the rendered report read — so the agent’s read cannot drift from what a human sees.

Signature

market_pulse() -> str   # JSON-serialised dict

No parameters. The tool reads the cache first; on miss it calls GET /api/v1/agents/pulse and caches the result for 15 seconds.

Returns

The payload is the /agents/pulse response verbatim. Headline keys:

{
  "headline": "RISK-ON regime, health 68/100, breadth firming",
  "summary": "DIX recovered to 0.46 from yesterday's 0.41 ...",
  "regime": "RISK-ON",
  "health_score": 68,
  "active_alerts": {
    "critical": 0,
    "warning": 2,
    "info": 5
  },
  "what_changed_since_last_report": [
    "DIX crossed 0.45 threshold (was 0.41)",
    "VIX term structure flipped to contango",
    "Energy regime moved STABLE -> FALLING"
  ],
  "key_numbers": {
    "spy_close": 538.20,
    "vix_close": 16.4,
    "dix": 0.46,
    "gex": 2.1,
    "pct_above_50sma": 58
  },
  "generated_at": "2026-05-26T10:14:33-04:00"
}

generated_at is ET ISO 8601 with offset per Law 1. The headline and summary strings are platform-generated narrative — they pull from the same helpers that render the report’s lead.

Behaviour

Cache TTL. CACHE_TTL_PULSE = 15s (mcp/mcp_server/config.py). Repeated calls within the window return the cached payload without a backend round-trip. The backend’s cache_control_middleware also tags the route as a live snapshot — 30s + 60s SWR — so even on a cache miss the round-trip is cheap.
Read-only. No mutation. Does not require TRADING_TOKEN.
Source of truth. The route reuses the same helpers as /api/v1/signals/latest and the rendered Markdown report. Narrative drift between the dashboard, the report, and the agent’s read is structurally impossible.
Empty / degraded payloads. If the backend is mid-cycle and a field is unavailable, the route returns the field as null (loud, never silent — DOCTRINE P0). active_alerts always carries the three severity counters even when zero.

Examples

Session opener

Operator: "What's happening in the market right now?"
Agent: market_pulse()

Returns the headline payload. The agent reads regime, health_score, and what_changed_since_last_report and replies in one paragraph without further tool calls.

Pre-trade context

Operator: "I'm thinking about adding to SPY here."
Agent: market_pulse()  -> check regime + active_alerts.critical
       portfolio_status()  -> check available cash + existing SPY exposure

market_pulse confirms regime and any critical alerts before the agent considers a trade. If active_alerts.critical > 0 the agent surfaces them before quoting a price.

When to use

Beginning of any conversation about the market.
Before any trading-tool call (plan_trade / execute_trade).
Periodic checks during a long session when conditions might have shifted.

When NOT to use

You already called it within the last ~15 seconds and conditions haven’t changed.
You need a specific deep-dive (use analyze_signals with the right aspect).
You need a live price for a specific ticker (use get_quote).