Tool Group · 基本面與價格

VFM 與歷史價格 VFM & Prices

本頁涵蓋 VFM 商品 discovery、單一商品資料、條件式歷史抽取與歷史價格。商品代碼不確定時，agent 應先查支援清單，不能猜測代碼。 VFM & Prices tools 適合股票、ETF、基金與期貨商品研究，提供 valuation、financial、momentum 與價格脈絡。四個工具的 data 都屬於 records 容器。

Permission · standardBilling · x1Method · GETMethod · POSTContainer · recordsOutput · data / raw

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

VFM 商品資料

Tool	API Path	Method	說明	Best for
get_vfm_data	/API/module3	GET	取得單一股票、ETF、基金或期貨商品的 valuation、financial、momentum 資料。	個股研究、商品比較、投資摘要
list_vfm_products	/API/module3_product_list	GET	查詢 VFM 支援的商品清單，協助 AI 在呼叫資料前確認商品代碼與覆蓋範圍。	商品搜尋、代碼確認
extract_historical_products_by_condition	/API/module3_position	POST	依條件、排序與再平衡頻率，從歷史 VFM 資料中抽取符合條件的商品集合。	條件式選股、策略研究前置資料
get_historical_prices	/API/module3_price	POST	取得指定商品的歷史價格資料。	價格走勢、研究圖表、模型輸入

參數 Parameters

get_vfm_data

參數	型別	必填	預設	說明
code	string	◑	""	GAS Quant 標準商品代碼。code 與 reuter_code 至少擇一。
reuter_code	string	◑	""	Reuters 商品代碼。與 code 擇一。
start_date	string (YYYY-MM-DD)	✅	—	區間起日。
end_date	string (YYYY-MM-DD)	✅	—	區間迄日。
columns	string	—	*	MCP response projection。用 * 取全部 normalized VFM 欄位；用 date,cl,vol,momentum 這類逗號分隔欄位取較小回應。
output_mode	string	—	data	data / raw。

list_vfm_products

參數	型別	必填	預設	說明
query	string	—	""	不分大小寫的篩選字串。
limit	integer	—	100	回傳上限，最大 500。
output_mode	string	—	data	data / raw。

extract_historical_products_by_condition

參數	型別	必填	說明
region	string	✅	cn / tw / hk / jp / us / global。
product_type	string	✅	stock / etf / fund / futures。
start_date / end_date	string (YYYY-MM-DD)	✅	抽取區間。
rebalanced_days	integer	✅	再平衡間隔天數。
condition	string	✅	受驗證的 SQL-like 條件式。
order	string	✅	受驗證的 SQL-like 排序式。
top_n	integer	✅	每個再平衡日選取的商品數，最大 500。
additional_columns	string | null	—	選用的額外欄位式。

get_historical_prices

參數	型別	必填	說明
region	string	✅	同上。
product_type	string	✅	同上。
codes	string[]	✅	GAS Quant 商品代碼，1–200 檔。
start_date / end_date	string (YYYY-MM-DD)	✅	價格區間。

實務提醒

get_vfm_data 必須提供 code 或 reuter_code 其一，否則回 INVALID_ARGUMENT；get_vfm_data.columns 由 MCP 在 normalized records 上投影，未知欄位會回 INVALID_ARGUMENT，不會直接下推到 upstream column selector；get_historical_prices 的 codes 不可為空。summary 模式僅 Macro / Sector 提供 LLM-ready 欄位，這些工具請用 data。

get_vfm_data

• 適用：股票、ETF、基金或期貨的 valuation、financial、momentum 資料。
• 必要資訊：code 或 reuter_code 至少一個、start_date、end_date；columns 可使用 *。
• 不可臆測：商品代碼、欄位、資料日與空值。

請取得 2330 TT Equity 在 2025-07-01 到 2025-07-31 的 valuation、financial 與 momentum 資料，並說明資料日期與限制。

回答應保留正式商品代碼、實際日期範圍、可用欄位、資料日與 warnings。

VFM 支援商品

list_vfm_products

• 適用：確認 VFM 支援範圍與 canonical product code。
• 必要資訊：可提供 query 與 limit；不提供 query 時會列出廣泛清單。
• 不可臆測：未出現在回傳清單中的商品支援狀態。

請確認 VFM 是否支援代碼包含 2330 的商品，最多列出 20 筆，並顯示正式商品代碼。

若查不到結果，回答應建議使用不同代碼或名稱再次搜尋，不得直接呼叫資料 tool 猜測商品。

條件式歷史抽取

extract_historical_products_by_condition

• 適用：依條件、排序、再平衡頻率與 top N 抽取歷史商品集合。
• 必要資訊：region、單一 product_type（stock、etf、fund 或 futures）、日期範圍、rebalanced_days、condition、order、top_n；additional_columns 選填。
• 安全規則：condition、order 與 additional_columns 是受 allowlist 驗證的 SQL-like expressions，只能使用來源支援欄位與運算子。

請從 2018-01-02 到 2018-01-05 的台股股票歷史資料中，每 10 天再平衡一次，篩選 cap_rank 小於等於 10、依 cap_rank 升冪，每期取前 3 名，並帶回 long_momentum 與 beta。

回答應列出每個 rebalance date 的結果、排名條件、實際回傳欄位與資料限制。Expression 驗證失敗時，應指出不支援的欄位或語法，不可偷偷改寫策略條件。

歷史價格

get_historical_prices

• 適用：一個或多個 canonical product codes 的歷史價格。
• 必要資訊：region、單一 product_type（stock、etf、fund 或 futures）、codes、start_date、end_date。
• 不可臆測：商品類型、價格欄位、缺少的交易日與資料日。

請取得台股股票 2330 TT Equity 在 2025-07-01 到 2025-07-10 的歷史價格與資料日期。

回答應標示商品代碼、實際可用交易日、價格欄位、source.data_date 與缺值 warnings。

常見失敗

症狀	處理方式
商品代碼查不到	先用 VFM 支援商品清單解析 canonical code。
一次指定多種 product_type	每次選一個 stock、etf、fund 或 futures；不同類型分開查詢。
Condition expression 被拒絕	使用文件與來源 allowlist 支援的欄位、比較運算子及排序。
回傳空 records	檢查商品、日期、region 與 product type；空資料不能視為成功研究結果。
日期內含非交易日	以實際回傳交易日為準，不補造價格。

回傳格式 Response

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

欄位	說明
data.records	逐列記錄；來源日期欄正規化為 date。VFM 欄位（valuation / financial / momentum）以實際來源欄位為準。
data.columns	回傳欄位名清單。
data.total_count	MCP 端套用 limit 後的列數。
data.available_count	截斷前的可用列數（超過 limit 時 warnings 會註記）。

待 live 校正

records 內的實際欄位名（VFM components、價格欄）以 /API/module3 系列回傳為準，將以 dev 端實打結果補上。

AI 回應示意

使用者拿到的是 AI 依 records 整理後的回答，而非原始 JSON。示意（內容依商品與當日資料而定）：

2330 TT Equity · VFM 與價格｜資料日：依回傳 data_date

• Valuation / Financial / Momentum 三面向的最新數值與近期變化
• 對應期間的價格走勢摘要
• 涵蓋的商品代碼與資料區間
• ⚠️ 量化資訊整理，非投資建議

每段回應都會帶上 商品代碼、資料日期 與 非投資建議聲明。