{
  "schema_family": "ctys-agent-v1",
  "description": "Machine-readable capability declaration for the CrashTestYourStrategy agent layer: what the stress diagnostics can and cannot do, the controlled vocabularies used in responses, and the shared response envelope. Descriptive only — no recommendation or suitability assessment is made or implied.",
  "methodology_url": "https://crashtestyourstrategy.com/methodology",
  "openapi_url": "https://crashtestyourstrategy.com/api/openapi.json",
  "mcp_endpoint": "https://mcp.crashtestyourstrategy.ai/mcp",
  "html_representation": "https://crashtestyourstrategy.com/interop",
  "tool_groups": [
    {
      "group": "Portfolio stress",
      "tools": [
        {
          "signature": "portfolio_stress_test(holdings)",
          "description": "Stress a portfolio across baseline, risk-off-crisis and rate-shock regimes over the SPY/TLT/GOLD/BTC substrate. Returns per-scenario drawdown, VaR / expected shortfall, leg decomposition, a cross-asset finding (does the hedge hold or break), the full per-path drawdown distribution (quantiles p50–p95/worst), probability-weighted scenario summaries (unconditional substrate shares + a nowcast tilt from the validated regime layer), and a buy-and-hold-vs-drawdown-stop comparison."
        },
        {
          "signature": "factor_decomposition(holdings)",
          "description": "Euler risk-contribution decomposition — where the risk actually sits versus the capital weights. A 60/40 is ~83% equity risk; a 50/50 SPY/BTC is ~86% BTC risk despite equal capital."
        },
        {
          "signature": "ips_gate(holdings, max_drawdown_tolerance, time_horizon_years, liquidity_need)",
          "description": "A hard gate against an Investment Policy Statement, run before a portfolio is accepted — checked against the full drawdown distribution, not just the typical path: reports the breach probability (share of simulated paths exceeding the stated tolerance) and flags material tail risk even when the median path passes; plus horizon and liquidity checks."
        },
        {
          "signature": "portfolio_compare(holdings_a, holdings_b)",
          "description": "Paired comparison of a reference portfolio vs a candidate revision on identical simulated paths — every delta is attributable to the weights, not seed noise. Flags a candidate that deepens the worst-path drawdown or introduces a new diversification failure."
        },
        {
          "signature": "long_horizon_stress(holdings, horizon_years, monthly_contribution | monthly_withdrawal, …)",
          "description": "Multi-year wealth paths for a savings or withdrawal plan: terminal-wealth quantiles (nominal + real), ruin/shortfall probabilities, a sequence-of-returns diagnosis (same plan, bad vs good first two years) and a drift-sensitivity block. Long-run drift is a stated, overridable assumption (disclosed alongside the substrate's raw stress drift); costs on by default. No rate, allocation, or product is recommended."
        },
        {
          "signature": "regime_outlook(asset, horizon_days, as_of?)",
          "description": "Model-conditional probabilities that an asset (SPY/QQQ/GLD/TLT) is in each regime (BULL/SIDEWAYS/BEAR/CRISIS) after 5 or 21 trading days, with persistence and unconditional baselines alongside. Preregistered, out-of-sample validated; annual seasonality was tested, falsified and excluded. Descriptive probabilities of operationally defined regime classes — not a market prediction."
        }
      ]
    },
    {
      "group": "Strategy & backtest grounding",
      "tools": [
        {
          "signature": "challenge_strategy(strategy_id)",
          "description": "The full cross-regime gate for a strategy: where it degrades across the failure-mode taxonomy, plus a revision signal."
        },
        {
          "signature": "backtest_integrity(annualized_sharpe, n_trials, backtest_start, backtest_end, …)",
          "description": "Confront a backtest claim with its over-optimism: the deflated Sharpe (the maximum Sharpe reachable by chance grows with the number of configurations tried — Bailey & López de Prado) and which crisis regimes were absent from the backtest window."
        },
        {
          "signature": "run_stress_test(profile_hint)",
          "description": "Buy-and-hold diagnostic on one cached synthetic regime — a fast single-regime probe."
        }
      ]
    },
    {
      "group": "Regime discovery & feedback",
      "tools": [
        {
          "signature": "find_similar_regime(descriptors | profile_hint)",
          "description": "Nearest-neighbour search over the regime descriptor space — find the stress regimes closest to a described market."
        },
        {
          "signature": "describe_regime(profile_hint)",
          "description": "The full descriptor profile of a named regime (return, clustering, volatility, drawdown character)."
        },
        {
          "signature": "submit_feedback(...)",
          "description": "Persist structured agent feedback (observation + suggested_action) about a response — the platform learns where it is weak."
        }
      ]
    }
  ],
  "resources": [
    {
      "uri": "validation://{asset}",
      "description": "Per-asset realism evidence — the 18 daily stylized facts measured against the historical reference bands."
    },
    {
      "uri": "validation://value",
      "description": "Cross-asset value basis — regime-conditional correlation and tail dependence vs a Gauss-copula baseline, with honest caveats."
    },
    {
      "uri": "ontology://failure-modes",
      "description": "The failure-mode taxonomy — the same set as the /ontology pages."
    },
    {
      "uri": "ontology://failure-behaviors",
      "description": "The failure-behavior vocabulary used in diagnostics."
    },
    {
      "uri": "ontology://regime-descriptors",
      "description": "The 18 behavioral descriptors that form the regime embedding axes."
    },
    {
      "uri": "portfolio://universe",
      "description": "The assets a Tier-1 portfolio request can be composed from."
    },
    {
      "uri": "regimes://available",
      "description": "The profile_hints currently servable by run_stress_test."
    },
    {
      "uri": "methodology://overview",
      "description": "A brief pointer to the methodology, canonical on .com."
    },
    {
      "uri": "feedback://insights",
      "description": "Aggregated agent-feedback statistics."
    }
  ],
  "response_envelope": [
    {
      "field": "schema_version",
      "description": "e.g. ctys-agent-portfolio-v1 — the primitive’s versioned schema."
    },
    {
      "field": "request_id",
      "description": "UUID for the call, for correlation and feedback."
    },
    {
      "field": "generated_utc",
      "description": "ISO timestamp."
    },
    {
      "field": "methodology_url",
      "description": "Link back to the canonical methodology."
    },
    {
      "field": "revision_required",
      "description": "Boolean gate — true when the result warrants the agent revising its proposal before presenting it."
    },
    {
      "field": "grounding_summary",
      "description": "One factual risk sentence — the headline the agent must not omit."
    },
    {
      "field": "methodological_limitations",
      "description": "The model’s boundaries, baked into every response — not a separate disclosure."
    },
    {
      "field": "_feedback",
      "description": "How to submit structured feedback on this response."
    }
  ],
  "controlled_vocabularies": {
    "diversification_behavior": [
      {
        "value": "diversification_intact",
        "meaning": "No major holding declined materially in the scenario."
      },
      {
        "value": "hedge_holds",
        "meaning": "A leg rose while another fell — the hedge offset the loss."
      },
      {
        "value": "hedge_breaks",
        "meaning": "A usually-offsetting leg fell together with the others — the hedge failed when it was needed (the 2022 stock-bond case)."
      },
      {
        "value": "shared_drawdown",
        "meaning": "Several major legs declined together — diversification did not help."
      },
      {
        "value": "concentrated_loss",
        "meaning": "One leg drove the loss; the others were roughly flat."
      }
    ],
    "severity": [
      {
        "value": "low",
        "meaning": "Shallow, contained drawdown in the scenario."
      },
      {
        "value": "moderate",
        "meaning": "A noticeable but survivable drawdown."
      },
      {
        "value": "high",
        "meaning": "A deep drawdown a typical mandate would struggle to hold through."
      },
      {
        "value": "critical",
        "meaning": "A severe, mandate-threatening drawdown."
      }
    ],
    "behavior": [
      {
        "value": "stable",
        "meaning": "Holds up under the regime; no meaningful regime-specific weakness."
      },
      {
        "value": "sensitive",
        "meaning": "Mild underperformance versus the pool baseline."
      },
      {
        "value": "degrading",
        "meaning": "Meaningful regime-specific weakness."
      },
      {
        "value": "inactive",
        "meaning": "Too little data in the bucket to characterise behaviour."
      }
    ],
    "impact_type": [
      {
        "value": "drawdown_expansion",
        "meaning": "Tail drawdowns deepen under the regime conditions."
      },
      {
        "value": "return_instability",
        "meaning": "Mean / median returns swing widely; high variance vs the pool."
      },
      {
        "value": "volatility_amplification",
        "meaning": "Outputs amplify when realised volatility crosses the regime threshold."
      },
      {
        "value": "whipsaw_sensitivity",
        "meaning": "Frequent sign-changes consume capital through entry / exit churn."
      },
      {
        "value": "trend_dependency",
        "meaning": "Performance contingent on persistent directional moves; degrades in their absence."
      },
      {
        "value": "tail_loss_acceleration",
        "meaning": "Losses accelerate past the configured failure-drawdown threshold."
      }
    ],
    "regime_classes": [
      {
        "value": "trend_regimes",
        "buckets": [
          "TREND_UP",
          "TREND_DOWN",
          "SLOW_BEAR"
        ],
        "meaning": "Persistent directional moves."
      },
      {
        "value": "mean_reverting_regimes",
        "buckets": [
          "SIDEWAYS",
          "WHIPSAW"
        ],
        "meaning": "Range-bound or sign-changing markets without strong direction."
      },
      {
        "value": "volatility_regimes",
        "buckets": [
          "VOL_EXPANSION",
          "VOL_COMPRESSION"
        ],
        "meaning": "Realised-volatility regimes (above / below baseline)."
      },
      {
        "value": "tail_event_regimes",
        "buckets": [
          "SHARP_CRASH",
          "LIQUIDITY_STRESS"
        ],
        "meaning": "Abrupt-loss / stress-event regimes."
      }
    ]
  },
  "capability_matrix": [
    {
      "capability": "Portfolio stress (cross-asset, regime-conditional)",
      "supported": true,
      "note": "SPY/TLT/GOLD/BTC substrate; hedge-hold vs hedge-break detection."
    },
    {
      "capability": "Stock-bond hedge-break detection (the 2022 case)",
      "supported": true,
      "note": "Shared-drawdown / rate-shock scenario."
    },
    {
      "capability": "Risk-concentration decomposition (capital vs risk)",
      "supported": true,
      "note": "Euler risk contributions."
    },
    {
      "capability": "Backtest over-optimism check (deflated Sharpe)",
      "supported": true,
      "note": "Bailey & López de Prado; + crisis-coverage gaps."
    },
    {
      "capability": "Strategy failure-mode classification",
      "supported": true,
      "note": "Cross-regime gate over the taxonomy."
    },
    {
      "capability": "Realism / value validation (citable resources)",
      "supported": true,
      "note": "validation://{asset} + validation://value."
    },
    {
      "capability": "Probabilistic forecasting / price prediction",
      "supported": false,
      "note": "Scenario-based; not a distribution over futures."
    },
    {
      "capability": "Investment recommendations / suitability",
      "supported": false,
      "note": "Descriptive output only; BaFin/WpHG-aware."
    },
    {
      "capability": "Portfolio allocation / position-sizing advice",
      "supported": false,
      "note": "It stresses a portfolio; it does not tell you how to weight one."
    },
    {
      "capability": "Fundamentals / macro analysis",
      "supported": false,
      "note": "Price-stress of systematic strategies only."
    },
    {
      "capability": "Live trading / order execution",
      "supported": false,
      "note": "No broker integration; not an execution platform."
    }
  ],
  "methodological_boundaries": [
    "Outputs are descriptive — regime behaviour, failure modes, drawdown distributions, risk decomposition. They are not predictions, recommendations, or suitability assessments.",
    "The portfolio substrate is Tier-1: a fixed SPY/TLT/GOLD/BTC universe of pre-computed joint paths, re-weighted per request. Custom assets are Tier-2 and deferred.",
    "The cross-asset model adds value in regime-conditional correlation and joint-crash tail dependence; single-asset daily marginals are at parity with cheap baselines (no unique edge claimed there).",
    "Synthetic regimes impose conditions on a regime-switching simulator — they are not draws from a distribution of futures.",
    "Drawdown and tail metrics are computed over the substrate paths, not a true out-of-sample tail estimate.",
    "Scope is price-stress of systematic strategies and portfolios — not fundamentals, macro, suitability, or execution."
  ],
  "examples": {
    "request": "// what a request describes\nportfolio_stress_test({\n  holdings: [\n    { asset: \"SPY\", weight: 0.6 },\n    { asset: \"TLT\", weight: 0.4 }   // the \"safe\" 60/40\n  ]\n})",
    "response": "{\n  \"schema_version\": \"ctys-agent-portfolio-v1\",\n  \"request_id\": \"…\",\n  \"revision_required\": true,\n  \"grounding_summary\": \"In a rate shock both legs fall together — the hedge breaks.\",\n  \"universe\": [\"SPY\", \"TLT\", \"GOLD\", \"BTC\"],\n  \"portfolio\": [{ \"asset\": \"SPY\", \"weight\": 0.6 }, { \"asset\": \"TLT\", \"weight\": 0.4 }],\n  \"substrate_version\": \"substrate_v1\",\n  \"portfolio_scenarios\": [\n    { \"scenario\": \"baseline\",        \"severity\": \"low\",\n      \"cross_asset_finding\": { \"behavior\": \"diversification_intact\" } },\n    { \"scenario\": \"risk_off_crisis\", \"severity\": \"moderate\",\n      \"cross_asset_finding\": { \"behavior\": \"hedge_holds\" } },\n    { \"scenario\": \"rate_shock\",      \"severity\": \"high\",\n      \"cross_asset_finding\": { \"behavior\": \"hedge_breaks\" },\n      \"portfolio_worst_episode_drawdown\": -0.14 }\n  ],\n  \"derisk_comparison\": {\n    \"rule\": \"drawdown_stop\",\n    \"rule_detail\": \"Exit to cash at -10% drawdown; re-enter at the 50-day MA\",\n    \"full_path\": { \"buy_hold_worst\": -0.14, \"derisk_worst\": -0.10 }\n  },\n  \"realism_basis\": { \"evidence_resource\": \"validation://{asset}\" },\n  \"methodological_limitations\": [ \"…\" ]\n}"
  }
}