工具總覽 Tool Overview

GAS Quant MCP 的工具定位是 read-only market data and calculation tools。目前 public tools/list 會列出 32 個 read-only MCP tools。工具可以查資料、整理分數、計算風險與產生研究候選清單，但不執行交易、不修改投組，也不提供保證報酬。

工具清單證據：artifact-confirmed，於 2026-07-14 Asia/Taipei 對照 src/gas_quant_mcp/server.py 與 runtime tool catalog。Production 預設公開 32 個 tools；另有 9 個只有 operator 啟用 GAS_QUANT_MCP_EXPOSE_HELPER_TOOLS=1 才出現的 helpers，不列入客戶使用文件。

Tool surface

類別	工具數	說明
Core API-backed tools	19	對應 GAS Quant API Interface 的核心資料與計算 endpoints。
Report tools	2	取得 Daily Market Brief spec 與 report-ready context。
ICIR workflow tool	1	產生具有 factor 與 performance evidence 的候選排名。
ONE10 research tools	10	補充概念族群、指標、評論與市場風險訊號。
Production public total	32	`tools/list` 預設應完整公開此 surface。

32-tool coverage index

Domain	Tools	使用文件
Macro、Sector、Reports	4	Macro & Sector Rotation
VFM、Historical Prices	4	VFM 與歷史價格
Portfolio Risk	1	Portfolio Risk
Cross-Asset Forecast	2	Cross-Asset Forecast
Taiwan Revenue	3	Taiwan Revenue
ICIR Factor Research	7	ICIR 因子研究
ICIR Candidate Ranking	1	ICIR 因子候選股排名
ONE10 Research	10	ONE10 研究工具
Total	32	每個 tool 都有 machine-readable case 與繁中自然語言範例。

回傳格式

核心工具使用一致的 response envelope，方便 AI、前端與資料管線穩定處理結果。

{
  "request_id": "...",
  "tool_id": "get_quantified_macro_score",
  "source": {
    "api_path": "/API/module1",
    "method": "GET",
    "data_date": "2026-06-04",
    "retrieved_at": "2026-06-05T01:23:45.678Z"
  },
  "output_mode": "data",
  "data": {},
  "summary": {},
  "warnings": []
}

source.data_date 是回傳內容實際涵蓋的最新資料日期；靜態字典、無版本日期的目錄及空結果會是 null。
source.retrieved_at 是 MCP server 取得或組裝回應的 UTC 時間，不能當成市場資料日期。

Output modes

Mode	適合情境
`data`	預設模式。適合圖表、資料管線、agent 後續分析，回傳 normalized structured data。
`summary`	適合 AI 報告與快速解讀。可支援的工具會提供 LLM-ready summary fields。
`raw`	適合研究驗證、除錯與 audit。正式部署時建議只開放給有權限的使用者。

使用原則

需要數字、日期、商品清單、因子或排名時，AI 應使用 MCP tools。
使用者問 latest / current 時，回答需標示資料日期。
ICIR 選股結果是研究候選清單，不是買賣建議。
客戶不需要自行部署 MCP server，也不需要取得 repo 原始碼。
使用者可直接複製各 domain 頁面的繁中 prompt；不需要輸入 tool ID 或 tools/call JSON。
空資料、missing fields、stale 或 mismatched dates 必須明確回報，不能產生看似有效的結論。

驗證方式

Repo 內的 validation/tool_usage_cases.json 是 tool coverage、三語 prompts、smoke arguments 與 semantic assertions 的 machine-readable source。執行：

python scripts/validate_tool_usage_coverage.py

此檢查會確認 manifest、runtime public surface、9 個 opt-in helpers、input schemas 與本文件 markers 一致。Remote MCP 與 agent live matrix 必須另以受保護 credentials 執行；不得把 token 或完整敏感 response 寫入文件。

Tool surface​

32-tool coverage index​

回傳格式​

Output modes​

使用原則​

驗證方式​