portfolio
Builds and analyzes multi-asset portfolios: computes optimal weights for minimum variance, maximum Sharpe ratio, risk parity, CVaR and other objectives, then measures risk and stress.
Instructions
Portfolio construction and analysis for the given tickers (at least two). Optimal weights: get_minimum_variance_weights, get_maximum_sharpe_weights, get_mean_variance_weights (target_return=, target_volatility= for the highest return at that annualized volatility, or risk_aversion=), get_risk_parity_weights (risk_budget={'AAPL': 0.5, ...} optional), get_hierarchical_risk_parity_weights (codependence='pearson'|'spearman'|'kendall' sets the correlation that is clustered, also on HERC and NCO), get_hierarchical_equal_risk_contribution_weights (HERC; clusters= or chosen automatically, linkage_method='ward'; adds the Cluster of each ticker), get_nested_clustered_optimization_weights (NCO: objective='minimum_variance'|'maximum_sharpe'|'risk_parity' within and across clusters, denoised covariance by default; adds the Cluster), get_inverse_volatility_weights, get_minimum_cvar_weights (confidence_level=), get_minimum_drawdown_weights (measure='cdar'|'maximum'|'average', confidence_level= for the CDaR; drawdowns of uncompounded returns, added as a column), get_maximum_omega_weights (minimum_acceptable_return= per period, 0 by default; adds the Omega Ratio), get_maximum_cvar_ratio_weights (confidence_level=; the excess return per period over the CVaR, adds CVaR and CVaR Ratio), get_black_litterman_weights (views={'AAPL': 0.10, 'AAPL-MSFT': 0.02}, optional view_confidences= and market_weights=; market capitalizations by default; risk_aversion=2.5 by default or 'market' for the benchmark's excess return over its variance; adds the Posterior Volatility), get_maximum_diversification_weights (adds the Diversification Ratio), get_minimum_tracking_error_weights (against the benchmark; objective='information_ratio' for the highest information ratio; adds Active Return, Tracking Error and Information Ratio) and get_growth_optimal_weights (Kelly: method='exact'|'approximate', fraction=0.5 for half Kelly with the rest in cash; adds Log Growth) and get_resampled_efficient_weights (Michaud: the average of the optimal weights over resamples=500 return histories drawn with resampling='parametric'|'bootstrap' and seed=0; objective='maximum_sharpe'|'minimum_variance'|'mean_variance'; adds the Weight Standard Deviation over the histories). Each returns per ticker and for the Portfolio the Weight, annualized Expected Return, Volatility, Sharpe Ratio and Risk Contribution. minimum_weight=/maximum_weight= bound the weights, as one number or per ticker ({'AAPL': 0.3}, the others keep 0 and 1; a negative minimum allows shorting). sector_bounds={'Technology': [0, 0.4]} and country_bounds={'United States': [0, 0.6]} bound the total weight per sector or country of the company profiles. net_exposure= sets the sum of the weights (1 by default, 0 for market neutral) and gross_exposure= caps the sum of absolute weights for long-short portfolios (1.6 for 130/30). Every optimizer and the frontier take these; risk parity and HERC take the weight, sector and country bounds, HRP only minimum_weight=/maximum_weight= (all three long only), NCO none (long only within and across clusters) and get_inverse_volatility_weights none of them. Constraints no portfolio can meet return an error that says why. current_weights={'AAPL': 0.5, 'MSFT': 0.5} (the weights held now) adds a Turnover column and, with maximum_turnover=0.2, caps the sum of absolute weight changes; get_maximum_sharpe_weights and get_mean_variance_weights also take transaction_cost=0.001 (cost per unit traded, taken from the expected return). Optimizers that use expected returns take expected_returns='mean' (default) | 'exponential' (expected_returns_span=) | 'capm' (beta to the benchmark) | 'james_stein' (Bayes-Stein shrinkage). get_efficient_frontier (points=) returns portfolios from the lowest risk to the highest return. get_optimization_backtest: a walk-forward out-of-sample backtest of the optimizers (methods='minimum_variance,maximum_sharpe,...', from minimum_variance, maximum_sharpe, mean_variance, risk_parity, hierarchical_risk_parity, hierarchical_equal_risk_contribution, nested_clustered_optimization, inverse_volatility, maximum_diversification, minimum_cvar, minimum_drawdown, maximum_omega and maximum_cvar_ratio; rebalancing='monthly'|'quarterly'|'yearly', lookback= daily returns per estimate, 252 by default, transaction_cost=, maximum_turnover=) against equal weights (1/N) and the benchmark: annualized return, volatility, Sharpe ratio, maximum drawdown, average turnover and costs (output='returns' or 'weights' for the details). For given weights (weights={'AAPL': 0.6, 'MSFT': 0.4}, equal weights when omitted): get_risk_contributions (risk_measure='volatility'|'cvar' (expected shortfall)|'semideviation' (below a zero return)|'mad' (mean absolute deviation)|'cdar' (Conditional Drawdown at Risk of uncompounded returns); contributions add up to the portfolio's measure, per period except volatility), get_portfolio_risk_metrics (annualized return and volatility, Sharpe and Sortino ratios, maximum drawdown, historical VaR and CVaR at confidence_level= of the weighted returns next to the benchmark), get_discrete_allocation (whole shares per ticker at the latest close for portfolio_value=10000, method='integer' (closest to the target amounts) | 'greedy'; Shares, Amount, Target Weight, Weight held and the Leftover Cash; short weights become short shares), get_diversification_metrics (Herfindahl-Hirschman index, effective number of assets, diversification ratio, effective number of bets), get_stress_test (returns in the Dot-com Crash, Global Financial Crisis, Euro Area Debt Crisis, 2015-2016 and 2018 Q4 sell-offs, COVID-19 Crash and 2022 Rate Shock next to the benchmark, or scenarios={'name': ['start', 'end']}), get_look_through_exposure (by='sector'|'country'|'holdings', looks through ETFs to their holdings, with the benchmark's exposure next to it) and get_brinson_attribution (allocation, selection and interaction effects by sector against the benchmark over start_date/end_date). Expected returns are historical averages unless expected_returns= says otherwise; period= sets the return frequency (daily by default). covariance= sets the covariance estimator of the weights and risk contributions: 'sample' (default), 'ledoit_wolf', 'ledoit_wolf_constant_correlation', 'ledoit_wolf_single_factor' (benchmark as the factor) or 'oas' (shrinkage, steadier weights for many tickers), 'semicovariance' (downside only), 'exponential' (recent periods weigh most; covariance_span= in periods, 180 by default) or 'denoised' (Marcenko-Pastur random matrix noise removed, steadier weights for many tickers). Weights, returns and volatilities are decimals. To follow a portfolio you hold (its trades, holdings or weights over time), use portfolio_performance.
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": "portfolio"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | What to look through to: "sector", "country" or "holdings". | sector |
| tau | No | The uncertainty of the implied returns relative to the covariance matrix. | |
| 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. | |
| seed | No | The seed of the random draws; the same seed gives the same weights. | |
| 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. | |
| views | No | The annualized views, absolute views as total returns. | |
| method | No | For get_discrete_allocation: "integer" or "greedy". For get_growth_optimal_weights: "exact" (the historical log returns) or "approximate" (the mean-variance approximation). Leave unset to use the default of the indicator you selected. Defaults are 'exact' for get_growth_optimal_weights; 'integer' for get_discrete_allocation. | |
| output | No | "summary" for the performance of each portfolio, "returns" for the daily returns after costs, or "weights" for the weights set on each rebalancing date. | summary |
| period | No | Observation frequency, e.g. 'daily', 'weekly', 'monthly', 'quarterly', or 'annual' (supported values differ per method). | daily |
| points | No | The number of portfolios on the frontier. | |
| measure | No | Sub-measure selector, e.g. 'M1', 'M2', or 'M3' for money supply. | cdar |
| methods | No | The optimizers to backtest, as a list or comma separated: "minimum_variance", "maximum_sharpe", "mean_variance" (a risk aversion of 2.5), "risk_parity", "hierarchical_risk_parity", "hierarchical_equal_risk_contribution", "nested_clustered_optimization" (minimum variance within and across the... | |
| tickers | No | Comma-separated ticker symbols, e.g. 'AAPL,MSFT,GOOGL'. | |
| weights | No | For get_brinson_attribution: The weight per asset at the start of the date range. For get_discrete_allocation: The weight per asset, e.g. those of one of the optimizers. For get_diversification_metrics, get_look_through_exposure, get_portfolio_risk_metrics, get_risk_contributions, get_stress_test: The weight per asset. | |
| clusters | No | The number of clusters. | |
| end_date | No | End of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window). | |
| fraction | No | The share of the growth optimal portfolio to hold, e.g. 0.5 for half Kelly; the rest is cash. | |
| lookback | No | The number of daily returns each estimation uses. The backtest starts on the first rebalancing date with that many returns up to and including it. | |
| 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. | |
| objective | No | For get_minimum_tracking_error_weights: "tracking_error" for the lowest tracking error or "information_ratio" for the highest information ratio. For get_nested_clustered_optimization_weights: The objective at both levels: "minimum_variance", "maximum_sharpe" or "risk_parity" (equal risk contribution). For get_resampled_efficient_weights: The portfolio optimized in every draw: "maximum_sharpe", "minimum_variance" or "mean_variance" (with the risk aversion). Leave unset to use the default of the indicator you selected. Defaults are 'maximum_sharpe' for get_resampled_efficient_weights; 'minimum_variance' for get_nested_clustered_optimization_weights; 'tracking_error' for get_minimum_tracking_error_weights. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| resamples | No | The number of resampled return histories. The average settles as their number grows; 500 keeps the weights within about a percentage point of their limit for a handful of assets. | |
| scenarios | No | Custom scenarios as {"name": ("start date", "end date")}. | |
| covariance | No | The estimator of the covariance matrix, which also gives the correlations that are clustered: "sample" (ddof=1), "ledoit_wolf" (towards the scaled identity, Ledoit and Wolf, 2004), "ledoit_wolf_constant_correlation" (towards the average correlation, Ledoit and Wolf, 2004),... Leave unset to use the default of the indicator you selected. Defaults differ between indicators. | |
| resampling | No | How the histories are drawn: "parametric" (a multivariate normal distribution with the estimated expected returns and covariance) or "bootstrap" (the actual periods, drawn with replacement). | parametric |
| 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). | |
| rebalancing | No | How often the weights are set anew: "monthly", "quarterly" or "yearly". | monthly |
| risk_budget | No | The share of the risk per asset, e.g. {"AAPL": 0.4, "MSFT": 0.2, ...}; it is scaled to sum to one. | |
| codependence | No | The correlation the assets are clustered on, through the distance √((1 - ρ) / 2): "pearson" (the linear correlation of the covariance matrix), "spearman" (the rank correlation of the returns, Spearman, 1904) or "kendall" (the rank correlation τ_b of the returns, Kendall, 1938). The rank... | pearson |
| net_exposure | No | The sum of the weights: 1 for a fully invested portfolio, 0 for a market neutral one. | |
| risk_measure | No | "volatility", "cvar" (the expected shortfall), "semideviation" (below a return of zero), "mad" (the mean absolute deviation) or "cdar" (the Conditional Drawdown at Risk). | volatility |
| 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. | |
| risk_aversion | No | For get_black_litterman_weights: The risk aversion δ of the market, or "market" for the one the benchmark implies, (E[r_m] - r_f) / σ²_m, with the benchmark's arithmetic average return and variance (ddof=1) per period both annualized by the number of periods in a year. For get_mean_variance_weights: The investor's risk aversion λ; higher values give less risky portfolios. Not used with a target return or target volatility. For get_resampled_efficient_weights: The risk aversion of the "mean_variance" objective. | |
| sector_bounds | No | The minimum and maximum total weight per sector, e.g. {"Technology": (0, 0.4)}, with the sector of each asset from its company profile. | |
| target_return | No | The annualized return the portfolio must expect, e.g. 0.12 for 12%. | |
| country_bounds | No | The minimum and maximum total weight per country, named in full or by its two-letter code, e.g. {"United States": (0, 0.6)}, with the country of each asset from its company profile. | |
| gross_exposure | No | The highest sum of the absolute weights, which limits the leverage of a long-short portfolio, e.g. 1.6 for a 130/30 portfolio. | |
| linkage_method | No | The linkage of the hierarchical clustering: "single", "complete", "average" or "ward". Leave unset to use the default of the indicator you selected. Defaults are 'ward' for get_hierarchical_equal_risk_contribution_weights, get_nested_clustered_optimization_weights; 'single' for get_hierarchical_risk_parity_weights. | |
| market_weights | No | The market weight per asset. | |
| maximum_weight | No | For get_black_litterman_weights, get_efficient_frontier, get_growth_optimal_weights, get_hierarchical_equal_risk_contribution_weights, get_hierarchical_risk_parity_weights, get_maximum_cvar_ratio_weights, get_maximum_diversification_weights, get_maximum_omega_weights, get_maximum_sharpe_weights, get_mean_variance_weights, get_minimum_cvar_weights, get_minimum_drawdown_weights, get_minimum_tracking_error_weights, get_minimum_variance_weights, get_resampled_efficient_weights, get_risk_parity_weights: The highest weight of every asset, or per asset, e.g. {"AAPL": 0.3} (the others keep 1). For get_optimization_backtest: The highest weight of every asset, or per asset, for the optimizers that take weight bounds. | |
| minimum_weight | No | For get_black_litterman_weights, get_efficient_frontier, get_growth_optimal_weights, get_maximum_cvar_ratio_weights, get_maximum_diversification_weights, get_maximum_omega_weights, get_maximum_sharpe_weights, get_mean_variance_weights, get_minimum_cvar_weights, get_minimum_drawdown_weights, get_minimum_tracking_error_weights, get_minimum_variance_weights, get_resampled_efficient_weights: The lowest weight of every asset, or per asset, e.g. {"AAPL": 0.05} (the others keep 0); a negative value allows short positions. For get_hierarchical_equal_risk_contribution_weights, get_hierarchical_risk_parity_weights, get_risk_parity_weights: The lowest weight of every asset, or per asset, e.g. {"AAPL": 0.05} (the others keep 0); it cannot be negative. For get_optimization_backtest: The lowest weight of every asset, or per asset, for the optimizers that take weight bounds (all but inverse volatility and nested clustered optimization). | |
| 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 |
| covariance_span | No | The span in periods of the "exponential" covariance; the weight of a period halves after about span / 2.9 periods. | |
| current_weights | No | The weights held now, e.g. {"AAPL": 0.5, "MSFT": 0.5} (an asset left out is not held), which the turnover is measured from; they add a Turnover column, |w_i - w0_i| per asset and its sum for the portfolio. | |
| portfolio_value | No | The amount to invest, in the currency of the prices. | |
| benchmark_ticker | No | Ticker used as the market benchmark, e.g. 'SPY' or '^GSPC'; 'None' for no benchmark. | SPY |
| confidence_level | No | The confidence level of the CVaR, e.g. 0.95 for the average of the worst 5% of periods. | |
| expected_returns | No | For get_efficient_frontier, get_growth_optimal_weights, get_maximum_cvar_ratio_weights, get_maximum_omega_weights, get_maximum_sharpe_weights, get_mean_variance_weights, get_minimum_tracking_error_weights, get_optimization_backtest: The estimator of the expected returns: "mean" (the historical average), "exponential" (the exponentially weighted average, recent periods weigh most), "capm" (the returns the Capital Asset Pricing Model implies from each asset's beta to the benchmark, Sharpe, 1964) or "james_stein" (the averages... For get_nested_clustered_optimization_weights: The estimator of the expected returns of the "maximum_sharpe" objective: "mean" (the historical average), "exponential" (the exponentially weighted average, recent periods weigh most), "capm" (the returns the Capital Asset Pricing Model implies from each asset's beta to the benchmark, Sharpe,... For get_resampled_efficient_weights: The estimator of the expected returns the "parametric" draws are centred on: "mean" (the historical average), "exponential" (the exponentially weighted average, recent periods weigh most), "capm" (the returns the Capital Asset Pricing Model implies from each asset's beta to the benchmark,... | mean |
| maximum_turnover | No | For get_efficient_frontier, get_maximum_cvar_ratio_weights, get_maximum_diversification_weights, get_maximum_omega_weights, get_maximum_sharpe_weights, get_mean_variance_weights, get_minimum_cvar_weights, get_minimum_drawdown_weights, get_minimum_tracking_error_weights, get_minimum_variance_weights, get_resampled_efficient_weights: The highest turnover Σ |w_i - w0_i| from the current weights, e.g. 0.2 to trade at most 10% of the portfolio each way. For get_optimization_backtest: The highest turnover of a rebalancing, e.g. 0.2. | |
| transaction_cost | No | For get_maximum_sharpe_weights, get_mean_variance_weights: The cost per unit of weight traded from the current weights, e.g. 0.001 for 10 basis points, subtracted once from the portfolio's annualized expected return. For get_optimization_backtest: The cost per unit of weight traded, e.g. 0.001 for 10 basis points. The first investment is free, so every portfolio starts from the same value. | |
| view_confidences | No | The confidence per view, between 0 and 1. | |
| include_benchmark | No | Whether to include the benchmark as an asset. | |
| target_volatility | No | The highest annualized volatility of the portfolio (the volatility per period times the square root of the number of periods in a year), e.g. 0.15 for 15%. Cannot be combined with a target return. | |
| expected_returns_span | No | The span in periods of the "exponential" expected returns. | |
| 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 |