MCP tool: plays_state

What this tool does

plays_state answers one question per locked trading play: is it armed right now, and what is the evidence? It replaces reading state out of journal prose with a single structured call.

For each play it returns:

• armed — the one boolean (armed.value) plus its evidence: abstained (a required input was NULL — an honest “cannot decide”, never a silent false), reasons[] (each SEE gate restated with its live value and threshold), last_armed_trade_date (the most recent session it fired), and the raw inputs.
• gauntlet — the play’s last backtest verdict: state (graded / no_run_yet), top_level_verdict, sealed (a full run against a held-out window), and per-lens verdicts (never pooled across horizons).
• book — the play’s own fill ledger from the trading tag: fills_total, first/last fill dates, a coarse paper / real split (by_account), and open_pending. Counts and dates only — never a balance, never a P&L.

The envelope carries session_state (fresh / stale / unknown) so a stale read announces itself.

How an agent uses it

Read armed.value per play as your one boolean, with the evidence beside it. Then apply your own governance:

• A draft is not tradeable. spec_status: "draft" or gauntlet.state: "no_run_yet" means the play has not passed its backtest gate — it is shown for visibility only. Only a gauntlet-passed play is a tradeable paper play.
• Treat session_state: "stale" as “do not act on armed.” The platform missed a trading session; the armed read is not current.
• abstained: true is not false. A required input was missing; the gate could not decide. Do not read it as a no-fire.

What it never does

This surface reports state and evidence — it never decides.

• No buy / sell / enter / exit field, no target, no direction-to-act. direction is static hedge/long/short metadata, not an instruction.
• No sizing — no fraction, ticket, or dollar figure.
• No auto-graduation. Whether a play has earned real money is your governance’s call, computed from book + the gauntlet verdict — the tool supplies the counts, not the decision.
• No account balances or P&L.

Auth

The tool wraps the internal-token-gated GET /api/v1/plays/state. It forwards X-Internal-Token from the MCP server’s own environment — set INTERNAL_API_TOKEN on the finance-report-mcp container. It is a thin wrapper: no gate logic lives in the tool, so it inherits the route’s behaviour (including the never-500/never-404 degrade — every missing piece comes back as a reason at HTTP 200).