risk
Compute VaR, CVaR, drawdowns, GARCH volatility, skewness, kurtosis, and tail dependence from ticker data to quantify portfolio downside and stress exposure.
Instructions
Pre-computed risk metrics (VaR incl. historic/gaussian/cornish-fisher/studentt/evt distributions, CVaR, EVaR, GARCH volatility, max drawdown, drawdown duration, drawdown recovery time, drawdown series (underwater curve, the current distance from the running high; recovery=true gives the gain needed to get back to the high instead, e.g. +25% after a 20% fall; deepest_since=true adds the last date the drawdown was as deep), drawdown table (the top= deepest drawdowns with peak, trough and recovery dates, the gain needed from the trough back to the peak and lengths in periods and in calendar days and years), Conditional Drawdown at Risk (CDaR), Tail Ratio, skewness, kurtosis, downside deviation, Variance, Volatility incl. close_to_close/parkinson/garman_klass/rogers_satchell/yang_zhang estimators, Excess Volatility). VaR, CVaR, skewness, kurtosis, CDaR, Tail Ratio, downside deviation, Variance, Volatility and Excess Volatility support rolling=N for a rolling N-period value spanning the full history instead of one value per period (e.g. period='monthly', rolling=6 for a rolling 6-month figure). Requires tickers='AAPL' — use comma-separated values for multiple tickers. Supports period='daily' for whole-series calculations; rolling and per-period outputs use weekly, monthly, quarterly, or yearly. get_copula_simulation returns 100 simulated joint draws unless n_simulations= asks for more. get_tail_dependence_coefficient pairs ticker_a= (every ticker by default) with ticker_b= (the benchmark by default). get_covar measures the tail risk of ticker= (the system, the benchmark by default) given the distress of conditioning_ticker= (every other ticker by default), so by default how much each ticker's distress adds to the benchmark's tail risk (Delta-CoVaR). get_amihud_illiquidity is the price impact per billion dollars traded (scale=1e9). get_factor_analysis: factor analysis (predictive power) of the risk metrics across tickers: do the tickers that score high on one go on to return more than those that score low? Needs tickers= with at least ten, preferably twenty or more tickers. metrics= a risk metric name, a comma-separated list, or a collection: 'anomalies' (default: volatility, maximum drawdown, skewness, Amihud illiquidity) or 'all' (adds downside deviation, kurtosis, VaR, CVaR, tail ratio, Roll spread); each is measured within every period. Returns a row per metric and horizon: the mean information coefficient (IC, the Spearman rank correlation between the metric and the later returns), its standard deviation, IC information ratio, t-statistic, p-value, share of positive periods, number of periods, the Top Minus Bottom quantile spread, quantile turnover and rank autocorrelation. detail='information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part per period (or per quantile) for a single metric. period= sets how often it is evaluated (monthly by default), horizons= the periods ahead (e.g. 12 or [1, 12]), quantiles= the number of quantiles (5). Other parameters (e.g. alpha=) pass to the metrics. The IC is reported as measured: a negative IC for the volatility is the low-volatility anomaly. get_move_significance says how unusual each move is: the return in units of the volatility of the window= returns before it, the VaR Multiple (the return divided by the size of the historic VaR at alpha=, 0.05 by default, of those returns; below -1 is a VaR exceedance), its percentile among all earlier moves and the date of the last move as large in the same direction ('the biggest fall since'); use limit=-1 for the latest day and a start_date years back for a long history.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"indicator": "<indicator>"
},
"name": "risk"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | The number of upper order statistics to use. If a float in (0, 1) it is interpreted as the fraction of the strictly positive observations to use. A period without such observations reports NaN with 0 observations used. | |
| q | No | The threshold quantile used for the "empirical" method, in (0.5, 1). | |
| dof | No | The degrees of freedom of the Student-T copula, only used when `method="student-t"`. | |
| lag | No | Number of periods to lag when computing growth rates. | |
| top | No | The number of drawdowns per asset, deepest first. | |
| lags | No | The number of lags (past periods) the test or model uses, e.g. 1 or 5. | |
| rank | No | true ranks the tickers (or countries) within every period, from the highest value (rank 1) to the lowest, and compares each with its neighbour toward the middle of the ranking: the Difference (in points for returns) and the Multiple (only when both have the same sign), so the first and last rank show how far the best and the worst stand apart, e.g. a fall more than twice as large as the next one. Needs a value per period and ticker; pick one field with show_columns where there are more. | |
| tail | No | Which tail to estimate, one of "left" (the loss tail) or "right" (the gain tail). | left |
| test | No | Which test(s) to run, one of "kupiec", "christoffersen" or "both". | both |
| alpha | No | The tail probability (e.g., 0.05 for the 95% confidence level). | |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead, and rows per ticker (an earnings calendar) are selected per ticker. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. 0 returns every row. | |
| scale | No | A multiplier applied to the resulting ratio purely for readability. Leave unset to use the default of the indicator you selected. Defaults are 1000000000 for get_amihud_illiquidity. | |
| column | No | The price column to use, e.g. 'Close' or 'Adj Close'; for get_factor_analysis the output of a metric with several, e.g. 'Signal Line'. Leave unset to use the default of the indicator you selected. Defaults are 'Return' for get_best_fitting_copula, get_component_value_at_risk, get_copula_parameters, get_copula_simulation, get_covar, get_marginal_value_at_risk, get_tail_dependence_coefficient; None for get_factor_analysis. | |
| copula | No | For get_copula_parameters: The copula family to fit, one of "gaussian", "student-t", "clayton", "gumbel" or "frank". For get_copula_simulation: The copula family to fit and simulate from, one of "gaussian", "student-t", "clayton", "gumbel" or "frank". | gaussian |
| detail | No | get_factor_analysis only: 'information_coefficient', 'quantile_returns', 'quantile_turnover' or 'rank_autocorrelation' returns that part for a single metric instead of the summary. | |
| fisher | No | Whether to use Fisher's definition of kurtosis (kurtosis = 0.0 for a normal distribution). | |
| growth | No | Return period-over-period growth rates instead of absolute values. | |
| method | No | For get_tail_dependence_coefficient: The estimation method, one of "empirical", "gaussian" or "student-t". For get_volatility: Which Volatility estimator to use, one of "close_to_close", "parkinson", "garman_klass", "rogers_satchell" or "yang_zhang". Leave unset to use the default of the indicator you selected. Defaults are 'close_to_close' for get_volatility; 'empirical' for get_tail_dependence_coefficient. | |
| period | No | Observation frequency, e.g. 'daily', 'weekly', 'monthly', 'quarterly', or 'annual' (supported values differ per method). Leave unset to use the default of the indicator you selected. Defaults differ between indicators. | |
| ticker | No | The asset whose conditional VaR is being measured (the system). | |
| window | No | The number of periods the indicator looks back over, e.g. 14 or 20. | |
| horizon | No | The number of days ahead to forecast. | |
| lambda_ | No | The decay factor. Higher values weight the past more heavily (slower to react), lower values weight recent returns more heavily (faster to react). RiskMetrics uses 0.94 for daily data. | |
| max_lag | No | The maximum lag, included, to use when estimating the exponent: the regression runs over the lags 2 up to and including `max_lag`. | |
| metrics | No | get_factor_analysis only: the metric(s) to analyse, a method name such as 'get_price_to_earnings_ratio', a comma-separated list, or a collection of the tool (see the tool description), e.g. 'profitability'. | anomalies |
| rolling | No | Rolling window size in number of periods. When set, the metric is computed over a smoothly overlapping trailing window across the full history (e.g. period='monthly' and rolling=6 gives a rolling 6-month value) instead of one value per period, or (for economics indicators) a simple moving average used to smooth the raw series. Leave unset to use the default of the indicator you selected. Defaults are None for get_conditional_drawdown_at_risk, get_conditional_value_at_risk, get_downside_deviation, get_excess_volatility, get_kurtosis, get_skewness, get_tail_ratio, get_value_at_risk, get_variance, get_volatility; 14 for get_ulcer_index. | |
| tickers | No | Comma-separated ticker symbols, e.g. 'AAPL,MSFT,GOOGL'. | |
| weights | No | Portfolio weights keyed by ticker. Normalized internally to sum to 1. | |
| end_date | No | End of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window). | |
| horizons | No | The number of periods the forward returns cover. | |
| recovery | No | Whether to return the gain needed to get back to the running peak (Recovery Needed) instead of the drawdown. | |
| ticker_a | No | The first asset. | |
| ticker_b | No | The second asset. | |
| estimator | No | How to construct the daily Realized Variance input, one of "squared_return", "parkinson", "garman_klass" or "rogers_satchell". | squared_return |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| quantiles | No | The number of quantiles the tickers are sorted into per period. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| start_date | No | Start of the date range in YYYY-MM-DD format; left empty, five years before today (or the indicator's own window). | |
| time_steps | No | Time steps to calculate GARCH for. Leave unset to use the default of the indicator you selected. Defaults are 10 for get_garch_forecast, get_gjr_garch_forecast; None for get_garch, get_gjr_garch. | |
| n_bootstrap | No | The number of bootstrap resamples used to estimate the Standard Error of Z2. | |
| standardize | No | Return the Z-Score (standard score) instead of the raw values, i.e. how many standard deviations each value is from the mean of its own series. When combined with growth=True, the growth values are standardized instead of the raw values. | |
| window_size | No | For get_acerbi_szekely_test: The rolling window size (in number of return observations) used to estimate each VaR/CVaR value. For get_var_backtest: The rolling window size (in number of return observations) used to estimate each VaR value. | |
| distribution | No | The distribution to use for the rolling VaR estimates, one of "historic", "gaussian", "studentt" or "evt". | historic |
| random_state | No | For get_acerbi_szekely_test: The seed for the bootstrap random number generator. For get_copula_simulation: The seed for the random number generator. | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| deepest_since | No | Whether to add the Deepest Since date of every period below the peak. | |
| n_simulations | No | The number of joint draws to simulate. Leave unset to use the default of the indicator you selected. Defaults are 100 for get_copula_simulation. | |
| periods_apart | No | The number of periods between the dates the quantile turnover and the rank autocorrelation compare. | |
| weekly_window | No | The trailing window (in trading days) for the weekly RV component. | |
| within_period | No | Whether to calculate GJR-GARCH within each specified period or all at once. | |
| monthly_window | No | The trailing window (in trading days) for the monthly RV component. | |
| optimization_t | No | For get_garch: Time steps to optimize GARCH for. It is only used if no weights are given. For get_garch_parameters, get_gjr_garch_parameters: Time steps of the returns series to use for the optimization. For get_gjr_garch: Time steps to optimize GJR-GARCH for. It is only used if no weights are given. | |
| risk_free_rate | No | The US Treasury yield used as the risk-free rate: '13w' (the 13-week bill), '5y', '10y' (default) or '30y'. | 10y |
| benchmark_ticker | No | Ticker used as the market benchmark, e.g. 'SPY' or '^GSPC'; 'None' for no benchmark. | SPY |
| empirical_margins | No | Whether to map the simulated pseudo-observations back to realistic returns via each asset's own empirical (historical) quantile function. When False, the raw pseudo-observations (each in (0, 1)) are returned instead. | |
| show_full_results | No | Only relevant when neither ticker is given. When False (the default), returns a square ticker-by-ticker grid of just the winning copula family per pair. When True, returns one row per pair instead, with the winning family's fitted parameter(s), Lower and Upper Tail Dependence, Log-Likelihood,... | |
| conditioning_ticker | No | The asset whose distress `ticker` is conditioned on. | |
| threshold_percentile | No | Only used when distribution='evt'. The percentile of losses above which the Generalized Pareto Distribution is fitted, e.g. 0.95 fits on the worst 5% of losses. | |
| minimum_acceptable_return | No | The minimum acceptable return (MAR) threshold below which returns are considered downside, e.g. 0.0 for downside relative to a zero return. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |