🔍 統一的工具發現入口 (High-Level)

幫助 Agent 找到合適的醫學計算器。支援多種發現模式。

Args: by: 發現模式 - "all": 列出所有分類 (專科和臨床情境) - 預設 - "specialty": 依專科篩選工具 - "context": 依臨床情境篩選工具 - "keyword": 關鍵字搜尋 - "tools": 列出所有工具 value: 篩選值 (當 by 不是 "all" 或 "tools" 時必填) limit: 最多回傳幾個結果

Returns: 根據模式返回不同內容: - all: 可用的專科和情境清單 - specialty/context: 該分類下的工具清單 - keyword: 匹配的工具清單 - tools: 所有工具清單

Examples:

# 弱模型安全流程: 先 discover，再 get_tool_schema
discover(by="keyword", value="sepsis")
# → 取得候選 tool_id 之後再呼叫 get_tool_schema("qsofa_score")

# 查看所有分類 (起點)
discover()
# → {"specialties": [...], "contexts": [...]}

# 依專科篩選
discover(by="specialty", value="critical_care")
# → {"tools": [{"tool_id": "sofa_score", ...}, ...]}

# 依臨床情境篩選
discover(by="context", value="preoperative_assessment")
# → {"tools": [{"tool_id": "rcri", ...}, ...]}

# 關鍵字搜尋
discover(by="keyword", value="sepsis")
# → {"tools": [{"tool_id": "qsofa_score", ...}, ...]}

# 列出所有工具
discover(by="tools", limit=50)
# → {"tools": [...], "count": 75}

規則:

• 不要根據記憶猜 tool_id，先用 discover() 拿 canonical id

• 不要直接 calculate，先用 get_tool_schema(tool_id)

⏭️ 下一步: 找到工具後，使用 get_tool_schema(tool_id) 查看參數

🔗 取得相關工具 (High-Level 語義發現)

基於共享參數和專科自動發現相關工具。 純 Python 算法，無 ML 依賴。

Args: tool_id: 工具 ID limit: 最多回傳幾個相關工具

Returns: 相關工具清單及相似度分數

Example:

get_related_tools("sofa_score")
# → {"related_tools": [
#      {"tool_id": "qsofa_score", "similarity": 0.85},
#      {"tool_id": "apache_ii", "similarity": 0.72},
#      ...
#    ]}

💡 相關性基於: 共享參數、相同專科、相同臨床情境

🔍 根據已有參數找工具 (High-Level 反向查找)

「我有這些數值，可以計算什麼？」

Args: params: 參數名稱列表 Examples: ["creatinine", "age", "weight"] ["gcs", "pupil", "motor"] ["bilirubin", "inr", "ascites"]

Returns: 可使用這些參數的工具清單

Example:

find_tools_by_params(["age", "creatinine", "bilirubin"])
# → {"tools": [
#      {"tool_id": "meld_score", "input_params": [...]},
#      {"tool_id": "ckd_epi_2021", "input_params": [...]},
#      ...
#    ]}

💡 適合場景: 已有病患數據，想知道能計算哪些評分

🧮 通用醫學計算工具

使用指定的計算器執行計算。支援所有 75+ 種醫學計算器。

使用流程:

1. 先用 discover(by="keyword" | "specialty" | "context") 找工具

2. 用 get_tool_schema(tool_id) 查看需要的參數

3. 呼叫 calculate(tool_id, params) 執行計算

嚴格規則:

• 不要猜參數名稱，必須以 get_tool_schema() 回傳為準

• 不要把 calculate 當搜尋工具；tool_id 不確定時先用 discover()

• 如果回傳 guidance 或 param_template，先依該內容修正後再重試

Args: tool_id: 計算器 ID (例如: "sofa", "apache_ii", "ckd_epi_2021") params: 計算參數字典 (從 get_tool_schema 取得參數名稱)

Returns: 計算結果，包含: - success: 是否成功 - score_name: 評分名稱 - result: 計算結果 (分數或數值) - unit: 單位 - interpretation: 臨床解讀 - references: 參考文獻

Examples:

Example 1 - SOFA Score:

calculate("sofa_score", {
    "pao2_fio2_ratio": 300,
    "is_mechanically_ventilated": False,
    "platelets": 150,
    "bilirubin": 1.2,
    "map_value": 70,
    "gcs_score": 15,
    "creatinine": 1.0,
    "urine_output_24h": 1500
})

Example 2 - CKD-EPI 2021:

calculate("ckd_epi_2021", {
    "serum_creatinine": 1.2,
    "age": 65,
    "sex": "male"
})

Example 3 - RCRI (Revised Cardiac Risk Index):

calculate("rcri", {
    "high_risk_surgery": True,
    "ischemic_heart_disease": False,
    "heart_failure": False,
    "cerebrovascular_disease": False,
    "insulin_therapy": True,
    "creatinine_above_2": False
})

常用計算器:

• Critical Care: sofa_score, apache_ii, news2_score, qsofa_score, glasgow_coma_scale

• Cardiology: chads2_vasc, heart_score, rcri

• Nephrology: ckd_epi_2021, kdigo_aki

• Anesthesiology: asa_physical_status, mallampati_score, stop_bang

• Hepatology: meld_score, child_pugh

⏮️ 上一步: get_tool_schema(tool_id) 查看完整參數說明

🧮 批次計算多個工具 - 減少 round-trip，提高效率

一次執行多個計算，並提供結果間的事實關係分析。 適合需要同時評估多個指標的臨床情境。

Args: calculations: 計算請求列表，每個元素包含: - tool_id: 計算器 ID - params: 參數字典

Returns: - results: 各計算的結果 - summary: 結果摘要 - cross_analysis: 結果間的事實關係 (非臨床推理) - all_success: 是否全部成功

Example - Sepsis 評估:

calculate_batch([
    {"tool_id": "qsofa_score", "params": {
        "respiratory_rate": 24,
        "systolic_bp": 95,
        "altered_mentation": True
    }},
    {"tool_id": "sofa_score", "params": {
        "pao2_fio2_ratio": 200,
        "platelets": 80,
        "bilirubin": 2.5,
        "gcs_score": 13,
        "creatinine": 2.0
    }}
])

Cross-analysis 提供的事實判斷 (非推理):

• "qSOFA ≥ 2 且 SOFA ≥ 2: 符合 Sepsis-3 定義標準"

• "RCRI ≥ 2: 符合高心臟風險標準"

💡 這不是臨床建議，只是根據指引標準的事實陳述

📋 取得工具完整資訊 + 參數 Schema + 來源提示 (Low-Level)

整併了原本的 get_calculator_info 和 get_calculation_schema， 提供 Agent 執行計算所需的所有資訊:

1. 工具基本資訊: 名稱、用途、專科、情境

2. 參數 Schema: 每個參數的類型、單位、正常範圍

3. 來源提示: 參數通常從哪裡取得 (Parameter Provenance)

4. 參考文獻: PMID/DOI (100% 覆蓋率，Vancouver style)

Args: tool_id: 計算器 ID (從 discover() 取得) include_references: 是否包含參考文獻 (預設 True) - True: 包含完整參考文獻 (citation, PMID, DOI) - False: 省略以節省 tokens include_param_sources: 是否包含參數來源提示 (預設 True) - True: 包含 clinical_hint, common_sources, normal_range - False: 只返回基本 type/unit

Returns: 完整的工具資訊，包含: - tool_id, name, purpose - specialties, contexts (High-Level 分類) - required_params (必要參數列表) - param_schemas (每個參數的詳細 Schema) - references (參考文獻，若 include_references=True)

Example:

# 完整資訊 (預設)
get_tool_schema("ckd_epi_2021")

# 只要基本資訊 (節省 tokens)
get_tool_schema("ckd_epi_2021", include_references=False, include_param_sources=False)

⏭️ 下一步: calculate(tool_id, params) 執行計算