Tool Group · 風險

Portfolio Risk

Portfolio Risk 使用使用者提供的 column-oriented portfolio 與 factor time series 計算短期 downside risk。MCP 不會替使用者抓取或猜測私有投組資料。 Portfolio Risk tool 使用投組與自訂 factor time series 計算短期 downside risk score，協助 PM 或風控團隊檢查風險變化。data 屬於 values 容器。

Permission · standardBilling · x2Method · POSTContainer · valuesOutput · data / raw

驗證狀態：artifact-confirmed。範例與 assertions 由 validation/tool_usage_cases.json 管理。

Tool	API Path	Method	說明	Best for
calculate_portfolio_risk	/API/module4	POST	使用投組與自訂 factor time series 計算短期 downside risk score。	投組風險檢查、factor risk review

參數 Parameters

參數	型別	必填	說明
data	object	✅	欄位導向（column-oriented）的時間序列，每個 key 對應一個等長陣列。
portfolio_col	string	✅	data 中代表投組淨值的欄位名。
factor_cols	string[]	✅	factor 欄位名，1–30 個。
output_mode	string	—	data / raw（預設 data）。

資料量限制（呼叫上游前即驗證）

• 列數最多 1,500；factor 欄位最多 30；payload 最大約 1 MB。
• portfolio_col 與所有 factor_cols 必須存在於 data，且所有欄位長度一致。
• 歷史至少需要 252 列；較短輸入會在呼叫上游前回傳 INVALID_ARGUMENT。
• 超出限制或欄位不齊會回 INVALID_ARGUMENT。

calculate_portfolio_risk

• 適用：使用同長度的投組與自訂 factors 檢查 downside risk。
• 必要資訊：data、portfolio_col、factor_cols。每個欄位必須是等長 array；目前 upstream 至少需要 252 rows，最多 1,500 rows、30 factor columns。
• 不可臆測：缺少的欄位、時間序列值、factor 名稱或投組配置。

請把 portfolio=[100,101,99,102,98,103] 與 market=[50,51,49,52,48,53] 各重複 42 次，形成 252 筆對齊資料，再以 portfolio 為投組、market 為風險因子計算短期 downside risk；請說明 rolling window 造成的前段空值與方法限制。

回答應包含計算結果、使用的 portfolio / factor columns、資料列數、warnings 與方法限制。Rolling window 前段可能為 null；不得刪除、補造或描述為有效分數。

常見失敗

症狀	處理方式
Arrays 長度不同或為空	修正輸入，使所有欄位具有相同且非零列數。
少於 252 rows	補足真實且對齊的歷史資料；不得用模型臆測使用者的投組。
超過 1,500 rows 或 30 factors	在客戶端縮小資料範圍或 factor 集合。
使用者未提供投組資料	先請使用者提供資料，不可用模型記憶生成投組。
回傳 INVALID_ARGUMENT	顯示 server 的 details，指出哪個欄位或限制不符合。

結果僅供風險研究，不是投組調整、交易或保證報酬指令。

回傳格式 Response

共用 envelope 見 工具總覽。本工具的 data 為 values 容器：

欄位	說明
data.values	上游回傳的純量結果（downside risk score 等）。
data.total_count	回傳的值數量。
data.available_count	截斷前的可用數量。
warnings	配額或其他資料品質提醒；少於 252 列會直接拒絕，不會產生有效分數。

待 live 校正

values 的實際內容與排列（risk score 的位置與輔助指標）以 /API/module4 回傳為準，將以 dev 端實打結果補上。

AI 回應示意

使用者拿到的是 AI 依結果整理的風險摘要，而非原始 JSON。示意（內容依輸入資料而定）：

Portfolio Downside Risk

• 短期 downside risk score 與相對水位（偏高 / 中性 / 偏低）
• 使用的 portfolio_col 與 factor_cols
• 風險集中或異常訊號（若有）
• 資料限制與 warnings（例如歷史過短）
• ⚠️ 風險研究輔助，非投組調整指令

每段回應都會帶上 使用的欄位、資料限制 與 非投資建議聲明。