ICIR 因子候選股排名 ICIR Factor-Based Stock Candidate Ranking
此 workflow 會串聯 ICIR statistics、level returns、pool constituents、factor history 與名稱 enrichment，依最新 factor value 產生具有 evidence 的研究候選股強弱排名。若使用者要求「ICIR 候選／排名／強弱排序」，agent 應優先使用此 workflow，而不是自行拼接 low-level tools 後發明 ranking rule。
rank_icir_stock_candidates 是 GAS Quant MCP 的 workflow tool。它會自動串聯 ICIR statistics、factor returns、pool constituents 與 factor history，回傳可進入研究流程的候選排名。
此工具會出現在 public tools/list，並計入 32 個 public read-only MCP tools；但它屬於 derived workflow，不計入 19 個 core API-backed tools。計費依其底層呼叫（get_icir_statistics、get_icir_returns、list_icir_pool_stocks、get_icir_factor_history 等）累計。
驗證狀態：artifact-confirmed。範例與 assertions 由 validation/tool_usage_cases.json 管理。
rank_icir_stock_candidates
- 適用：ICIR factor-based stock candidates、top N 或 pool percentage ranking。
- 必要資訊：
market；pool_name預設mc300、date預設latest、lookback_days預設 60、selection_pct預設 10%。 top_n：使用者指定絕對數量時優先於selection_pct。factor_name：只有使用者指定 factor 時才傳入；否則由 workflow 依factor_selection選擇。
請用最新可用資料，從台股 mc50 股票池選出前 5 名 ICIR 研究候選股，附上因子選擇、近一年績效證據、實際日期範圍與風險聲明。
回答至少包含 selected pool、selected factor、selected level、requested / actual dates、ranking rule、候選表、factor selection evidence、near-one-year performance evidence、warnings 與 candidate-only disclaimer。
參數 Parameters
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
market | string | tw | 市場：tw 或 cn。 |
pool_name | string | null | mc300 | 股票池；未指定用 mc300（市值前 300）。 |
date | string | null | latest | 分析迄日，或 latest 用最新 ICIR 統計日。 |
lookback_days | integer | 60 | 未指定期間時的回看天數。 |
selection_pct | number | 0.1 | 未給 top_n 時回傳的 pool 比例；預設前 10%（mc300→30、mc50→5）。 |
top_n | integer | null | — | 指定絕對檔數時覆蓋 selection_pct。 |
factor_name | string | null | — | 指定 factor；省略時由 workflow 自動選。 |
factor_selection | string | auto | auto / fast / stat / full 因子挑選策略。 |
include_evidence | boolean | true | 是否回傳選用統計、factor 指標與候選指標。 |
output_mode | string | data | data / raw。 |
適合問題
失敗與 fallback
- Selected factor 最新值全為 null 時，workflow 可嘗試下一個可用 factor，但必須在 warnings 記錄 skipped factor、原因與 fallback factor。
- Pool constituents、factor history 或 evidence 缺失時，不得回傳看似有效的排名。
latest必須解析成 response 中的實際日期，回答不可只寫「今天」。- 結果是研究候選，不是個人化買賣建議、部位配置或未來報酬保證。
Default behavior
| 項目 | 預設 |
|---|---|
| pool | 未指定時使用 mc300 |
| date | 未指定時使用 latest |
| period | 未指定期間時使用最近 60 天 |
| selection | 未指定數量時回傳 pool top 10% |
| factor | 未指定 factor 時由 workflow 自動選 factor |
回傳格式 Response
共用 envelope 見 工具總覽。data 為 records 容器，並附 workflow 專屬欄位：
| 欄位 | 說明 |
|---|---|
data.records | 研究候選股，依最新 factor_value 由大到小排序；可含中文股名。 |
data.metadata | 選用的 pool、factor、level、date range、ranking rule 等。 |
data.evidence | include_evidence=true 時的選用 ICIR 統計、factor 指標與候選指標。 |
records 與 evidence 的實際欄位名（factor_value、level1/level10 指標、近一年表現等）以 workflow 回傳為準，將以 dev 端實打結果補上。
AI 回應示意
使用者拿到的是 AI 依候選清單整理後的研究摘要，而非原始 JSON。示意（內容依 pool / factor 與當日資料而定）：
ICIR 因子候選股排名 · mc300（top 10%）｜資料日：依回傳
data_date
- selected pool、selected factor、selected level 與 date range
- ranking rule（依最新 factor value 由大到小）
- 候選股排名（代碼＋中文股名）與 factor exposure
- 佐證指標（level1 / level10、近一年表現）
- ⚠️ 研究候選清單，非個人化買賣建議
每段回應都會標示 pool / factor / level / 期間、排序規則 與 候選清單聲明。
重要聲明
ICIR 結果是基於歷史統計與因子資料的研究候選清單，不代表未來報酬保證，也不是個人化買賣建議。