Skip to main content
Glama
Finance Toolkit

Finance Toolkit

portfolio

Read-onlyIdempotent

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

NameRequiredDescriptionDefault
byNoWhat to look through to: "sector", "country" or "holdings".sector
tauNoThe uncertainty of the implied returns relative to the covariance matrix.
rankNotrue 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.
seedNoThe seed of the random draws; the same seed gives the same weights.
limitNoThe 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.
viewsNoThe annualized views, absolute views as total returns.
methodNoFor 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.
outputNo"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
periodNoObservation frequency, e.g. 'daily', 'weekly', 'monthly', 'quarterly', or 'annual' (supported values differ per method).daily
pointsNoThe number of portfolios on the frontier.
measureNoSub-measure selector, e.g. 'M1', 'M2', or 'M3' for money supply.cdar
methodsNoThe 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...
tickersNoComma-separated ticker symbols, e.g. 'AAPL,MSFT,GOOGL'.
weightsNoFor 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.
clustersNoThe number of clusters.
end_dateNoEnd of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window).
fractionNoThe share of the growth optimal portfolio to hold, e.g. 0.5 for half Kelly; the rest is cash.
lookbackNoThe number of daily returns each estimation uses. The backtest starts on the first rebalancing date with that many returns up to and including it.
indicatorYesName 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.
objectiveNoFor 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.
quarterlyNoReturn quarterly data instead of annual when True.
resamplesNoThe 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.
scenariosNoCustom scenarios as {"name": ("start date", "end date")}.
covarianceNoThe 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.
resamplingNoHow 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_dateNoStart of the date range in YYYY-MM-DD format; left empty, five years before today (or the indicator's own window).
rebalancingNoHow often the weights are set anew: "monthly", "quarterly" or "yearly".monthly
risk_budgetNoThe share of the risk per asset, e.g. {"AAPL": 0.4, "MSFT": 0.2, ...}; it is scaled to sum to one.
codependenceNoThe 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_exposureNoThe sum of the weights: 1 for a fully invested portfolio, 0 for a market neutral one.
risk_measureNo"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_columnsNoComma-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_aversionNoFor 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_boundsNoThe minimum and maximum total weight per sector, e.g. {"Technology": (0, 0.4)}, with the sector of each asset from its company profile.
target_returnNoThe annualized return the portfolio must expect, e.g. 0.12 for 12%.
country_boundsNoThe 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_exposureNoThe 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_methodNoThe 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_weightsNoThe market weight per asset.
maximum_weightNoFor 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_weightNoFor 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_rateNoThe US Treasury yield used as the risk-free rate: '13w' (the 13-week bill), '5y', '10y' (default) or '30y'.10y
covariance_spanNoThe span in periods of the "exponential" covariance; the weight of a period halves after about span / 2.9 periods.
current_weightsNoThe 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_valueNoThe amount to invest, in the currency of the prices.
benchmark_tickerNoTicker used as the market benchmark, e.g. 'SPY' or '^GSPC'; 'None' for no benchmark.SPY
confidence_levelNoThe confidence level of the CVaR, e.g. 0.95 for the average of the worst 5% of periods.
expected_returnsNoFor 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_turnoverNoFor 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_costNoFor 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_confidencesNoThe confidence per view, between 0 and 1.
include_benchmarkNoWhether to include the benchmark as an asset.
target_volatilityNoThe 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_spanNoThe span in periods of the "exponential" expected returns.
minimum_acceptable_returnNoThe minimum acceptable return (MAR) threshold below which returns are considered downside, e.g. 0.0 for downside relative to a zero return.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.3.4
    • addedInput schema / properties / rank
      Added value: +{
      +  "default": false,
      +  "description": "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.",
      +  "type": "boolean"
      +}
  2. Changed46 schema fields changedv2.3.3
    • addedInput schema / properties / clusters
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The number of clusters."
      +}
    • addedInput schema / properties / codependence
      Added value: +{
      +  "default": "pearson",
      +  "description": "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...",
      +  "type": "string"
      +}
    • addedInput schema / properties / country_bounds
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / covariance / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / covariance / default
      Previous value: -"sample"New value: +null
    • changedInput schema / properties / covariance / description
      Previous value: -"The estimator of the covariance matrix: \"sample\" (ddof=1), \"ledoit_wolf\" (Ledoit and Wolf, 2004), \"oas\" (Chen et al., 2010), \"semicovariance\" (the co-movement below a zero return, Estrada, 2007) or \"exponential\" (recent periods weigh most, RiskMetrics). The shrinkage estimators stabilize the..."New value: +"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."
    • removedInput schema / properties / covariance / type
      Removed value: -"string"
    • addedInput schema / properties / current_weights
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "type": "number"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / expected_returns
      Added value: +{
      +  "default": "mean",
      +  "description": "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,...",
      +  "type": "string"
      +}
    • addedInput schema / properties / expected_returns_span
      Added value: +{
      +  "default": 180,
      +  "description": "The span in periods of the \"exponential\" expected returns.",
      +  "type": "integer"
      +}
    • addedInput schema / properties / fraction
      Added value: +{
      +  "default": 1,
      +  "description": "The share of the growth optimal portfolio to hold, e.g. 0.5 for half Kelly; the rest is cash.",
      +  "type": "number"
      +}
    • addedInput schema / properties / gross_exposure
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • changedInput schema / properties / indicator / enum
      Previous value: -[
      -  "get_black_litterman_weights",
      -  "get_brinson_attribution",
      -  "get_efficient_frontier",
      -  "get_hierarchical_risk_parity_weights",
      -  "get_inverse_volatility_weights",
      -  "get_look_through_exposure",
      -  "get_maximum_sharpe_weights",
      -  "get_mean_variance_weights",
      -  "get_minimum_cvar_weights",
      -  "get_minimum_variance_weights",
      -  "get_risk_contributions",
      -  "get_risk_parity_weights",
      -  "get_stress_test"
      -]New value: +[
      +  "get_black_litterman_weights",
      +  "get_brinson_attribution",
      +  "get_discrete_allocation",
      +  "get_diversification_metrics",
      +  "get_efficient_frontier",
      +  "get_growth_optimal_weights",
      +  "get_hierarchical_equal_risk_contribution_weights",
      +  "get_hierarchical_risk_parity_weights",
      +  "get_inverse_volatility_weights",
      +  "get_look_through_exposure",
      +  "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_nested_clustered_optimization_weights",
      +  "get_optimization_backtest",
      +  "get_portfolio_risk_metrics",
      +  "get_resampled_efficient_weights",
      +  "get_risk_contributions",
      +  "get_risk_parity_weights",
      +  "get_stress_test"
      +]
    • addedInput schema / properties / linkage_method / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / linkage_method / default
      Previous value: -"single"New value: +null
    • changedInput schema / properties / linkage_method / description
      Previous value: -"The linkage of the hierarchical clustering: \"single\", \"complete\", \"average\" or \"ward\"."New value: +"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."
    • removedInput schema / properties / linkage_method / type
      Removed value: -"string"
    • addedInput schema / properties / lookback
      Added value: +{
      +  "default": 252,
      +  "description": "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.",
      +  "type": "integer"
      +}
    • addedInput schema / properties / maximum_turnover
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / maximum_weight / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "additionalProperties": {
      +      "type": "number"
      +    },
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / maximum_weight / description
      Previous value: -"The highest weight an asset may have."New value: +"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."
    • removedInput schema / properties / maximum_weight / type
      Removed value: -"number"
    • addedInput schema / properties / measure
      Added value: +{
      +  "default": "cdar",
      +  "description": "Sub-measure selector, e.g. 'M1', 'M2', or 'M3' for money supply.",
      +  "type": "string"
      +}
    • addedInput schema / properties / method
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / methods
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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..."
      +}
    • addedInput schema / properties / minimum_acceptable_return
      Added value: +{
      +  "default": 0,
      +  "description": "The minimum acceptable return (MAR) threshold below which returns are considered downside, e.g. 0.0 for downside relative to a zero return.",
      +  "type": "number"
      +}
    • addedInput schema / properties / minimum_weight / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "additionalProperties": {
      +      "type": "number"
      +    },
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / minimum_weight / description
      Previous value: -"For get_black_litterman_weights, get_efficient_frontier, get_mean_variance_weights, get_minimum_cvar_weights: The lowest weight an asset may have. For get_maximum_sharpe_weights, get_minimum_variance_weights: The lowest weight an asset may have; a negative value allows short positions."New value: +"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)."
    • removedInput schema / properties / minimum_weight / type
      Removed value: -"number"
    • addedInput schema / properties / net_exposure
      Added value: +{
      +  "default": 1,
      +  "description": "The sum of the weights: 1 for a fully invested portfolio, 0 for a market neutral one.",
      +  "type": "number"
      +}
    • addedInput schema / properties / objective
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / output
      Added value: +{
      +  "default": "summary",
      +  "description": "\"summary\" for the performance of each portfolio, \"returns\" for the daily returns after costs, or \"weights\" for the weights set on each rebalancing date.",
      +  "type": "string"
      +}
    • addedInput schema / properties / portfolio_value
      Added value: +{
      +  "default": 10000,
      +  "description": "The amount to invest, in the currency of the prices.",
      +  "type": "number"
      +}
    • addedInput schema / properties / rebalancing
      Added value: +{
      +  "default": "monthly",
      +  "description": "How often the weights are set anew: \"monthly\", \"quarterly\" or \"yearly\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / resamples
      Added value: +{
      +  "default": 500,
      +  "description": "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.",
      +  "type": "integer"
      +}
    • addedInput schema / properties / resampling
      Added value: +{
      +  "default": "parametric",
      +  "description": "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).",
      +  "type": "string"
      +}
    • addedInput schema / properties / risk_aversion / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "string"
      +  }
      +]
    • changedInput schema / properties / risk_aversion / description
      Previous value: -"For get_black_litterman_weights: The risk aversion δ of the market. For get_mean_variance_weights: The investor's risk aversion λ; higher values give less risky portfolios."New value: +"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."
    • removedInput schema / properties / risk_aversion / type
      Removed value: -"number"
    • addedInput schema / properties / risk_free_rate
      Added value: +{
      +  "default": "10y",
      +  "description": "The US Treasury yield used as the risk-free rate: '13w' (the 13-week bill), '5y', '10y' (default) or '30y'.",
      +  "enum": [
      +    "13w",
      +    "5y",
      +    "10y",
      +    "30y"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / risk_measure
      Added value: +{
      +  "default": "volatility",
      +  "description": "\"volatility\", \"cvar\" (the expected shortfall), \"semideviation\" (below a return of zero), \"mad\" (the mean absolute deviation) or \"cdar\" (the Conditional Drawdown at Risk).",
      +  "type": "string"
      +}
    • addedInput schema / properties / sector_bounds
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "number"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The minimum and maximum total weight per sector, e.g. {\"Technology\": (0, 0.4)}, with the sector of each asset from its company profile."
      +}
    • addedInput schema / properties / seed
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": 0,
      +  "description": "The seed of the random draws; the same seed gives the same weights."
      +}
    • addedInput schema / properties / target_volatility
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "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."
      +}
    • addedInput schema / properties / transaction_cost
      Added value: +{
      +  "default": 0,
      +  "description": "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.",
      +  "type": "number"
      +}
    • changedInput schema / properties / weights / description
      Previous value: -"For get_brinson_attribution: The weight per asset at the start of the date range. For get_look_through_exposure, get_risk_contributions, get_stress_test: The weight per asset."New value: +"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."
  3. Changed3 schema fields changedv2.3.2
    • addedInput schema / properties / covariance
      Added value: +{
      +  "default": "sample",
      +  "description": "The estimator of the covariance matrix: \"sample\" (ddof=1), \"ledoit_wolf\" (Ledoit and Wolf, 2004), \"oas\" (Chen et al., 2010), \"semicovariance\" (the co-movement below a zero return, Estrada, 2007) or \"exponential\" (recent periods weigh most, RiskMetrics). The shrinkage estimators stabilize the...",
      +  "type": "string"
      +}
    • addedInput schema / properties / covariance_span
      Added value: +{
      +  "default": 180,
      +  "description": "The span in periods of the \"exponential\" covariance; the weight of a period halves after about span / 2.9 periods.",
      +  "type": "integer"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"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. 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."New value: +"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."
  4. Changed6 schema fields changedv2.3.1
    • changedInput schema / properties / benchmark_ticker / description
      Previous value: -"Ticker used as the market benchmark, e.g. 'SPY' or '^GSPC'."New value: +"Ticker used as the market benchmark, e.g. 'SPY' or '^GSPC'; 'None' for no benchmark."
    • changedInput schema / properties / end_date / default
      Previous value: -"2026-10-27"New value: +""
    • changedInput schema / properties / end_date / description
      Previous value: -"End of the date range in YYYY-MM-DD format."New value: +"End of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window)."
    • changedInput schema / properties / limit / description
      Previous value: -"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. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length."New value: +"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. 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."
    • changedInput schema / properties / start_date / default
      Previous value: -"2021-10-28"New value: +""
    • changedInput schema / properties / start_date / description
      Previous value: -"Start of the date range in YYYY-MM-DD format."New value: +"Start of the date range in YYYY-MM-DD format; left empty, five years before today (or the indicator's own window)."
  5. Addedv2.3.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish that the tool is read-only, idempotent, and open-world, so the safety profile is covered. The description adds useful behavior beyond that: infeasible constraints produce an explanatory error, each optimizer returns named columns, and several indicators add specific output fields such as Turnover or Cluster. It does not discuss data freshness or rate limits, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely dense and largely a single run-on enumeration of 26 indicators. It is front-loaded with purpose, but the middle is difficult to scan and would benefit from clearer structure or bullets, even though most details are relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity, 26 selectable indicators, 55 parameters, and an output schema, the description is complete enough for correct invocation. It covers indicator behavior, shared constraints, output additions, error behavior, and the sibling alternative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the 55 parameters in detail. The description still adds cross-parameter meaning by stating which optimizers accept net_exposure, gross_exposure, sector_bounds, country_bounds, and minimum_weight/maximum_weight, and by explaining turnover and transaction-cost behavior across indicators.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Portfolio construction and analysis for the given tickers (at least two)." It then names every supported indicator and distinguishes the tool from portfolio_performance at the end, so an agent can identify its scope immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes an agent away from this tool when the task is following an existing portfolio: "To follow a portfolio you hold ... use portfolio_performance." It also explains which indicator to choose for each optimization or analysis goal and where constraints apply, leaving little ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.