案例 1：定義一個「查詢庫存」工具

場景：電商客服需要查詢產品庫存。

{
  "name": "check_inventory",
  "description": "查詢產品的實時庫存。支援按 SKU、品名、或分類查詢。返回可售量、預留量、倉庫位置。",
  "input_schema": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "產品 SKU（如 'PROD-2024-001'）"
      },
      "warehouse": {
        "type": "string",
        "enum": ["HQ", "SG", "HK", "JP"],
        "description": "倉庫代碼。省略時查全部倉庫。"
      }
    },
    "required": ["product_id"]
  }
}

定義亮點：清楚的參數描述、列舉值、可選參數、返回數據說明。

案例 2：弱提示詞 vs 強提示詞

弱版本：

你是客服助手。你可以查詢庫存、下單、查物流。幫助用戶。

強版本：

你是電商客服助手。遵循以下流程：

【查詢流程】
1. 用戶問關於某產品 → 先用 check_inventory 查庫存
2. 返回結果後，告訴用戶「現有 X 件，倉庫 Y」
3. 如果庫存 = 0，建議替代產品

【查詢規則】
- 只查詢真實產品 SKU（不猜測不存在的產品）
- 如果用戶只提品名，用 search_product 先找 SKU
- 不要一次查詢超過 5 個產品（效率低）

【回覆原則】
- 庫存 > 10：強調「現貨充足，可立即發貨」
- 庫存 1-10：提示「限量庫存」
- 庫存 = 0：提供「預計補貨日期」或「替代產品」

案例 3：處理多工具協調

場景：用戶申請退款。流程需要：查詢訂單 → 驗證退款資格 → 執行退款 → 發送通知。

【第 1 步】Claude 調用 get_order(order_id: "ORD-001")
【返回】
{
  "order_id": "ORD-001",
  "status": "delivered",
  "amount": 1000,
  "days_since_delivery": 5
}

【第 2 步】Claude 調用 check_refund_eligibility(order_id: "ORD-001")
【返回】
{
  "eligible": true,
  "reason": "未超過 7 天退貨期限",
  "max_refund": 1000
}

【第 3 步】Claude 需要確認
"用戶要求退款 ¥1000。符合資格（5 天內）。是否執行？"

【用戶確認】"是"

【第 4 步】Claude 調用 process_refund(order_id: "ORD-001", amount: 1000)
【返回】
{
  "refund_id": "REF-001",
  "status": "processing",
  "estimated_days": 3
}

【第 5 步】Claude 調用 send_notification(user_id, "退款已提交")
【返回】
{
  "status": "sent",
  "channel": "email + SMS"
}

案例 4：優雅處理 API 超時

場景：查詢外部物流 API，通常 2 秒返回，但有時超時。

【設計】
1. 設定 3 秒超時時間
2. 如果超時，返回快取的「最後已知狀態」
3. 提示 Claude：「物流信息可能不是最新（快取於 2 小時前）」

【返回範例】
{
  "status": "timeout",
  "cached_data": {
    "status": "in_transit",
    "last_location": "上海分撥中心",
    "updated_at": "2026-04-11 08:30"
  },
  "note": "實時信息暫時不可用，顯示最後已知狀態。"
}

【Claude 的回覆】
「您的訂單目前在上海分撥中心（2 小時前的信息）。實時信息暫時無法更新，請稍後重試。」

案例 5：權限管理範例

場景：工具允許「更新用戶信息」，但不是所有人都可以更新所有用戶的信息。

【工具定義層】
{
  "name": "update_user_info",
  "description": "更新用戶信息。受權限限制。",
  "input_schema": {
    "properties": {
      "user_id": { "type": "string" },
      "field": { "enum": ["email", "phone", "address"] },
      "value": { "type": "string" }
    }
  }
}

【執行層（應用程式）】
def update_user_info(user_id, field, value, current_user):
    # 層 1：輸入驗證
    if not validate_user_id(user_id):
        return {"error": "Invalid user_id"}

    # 層 2：權限檢查
    if current_user.role == "user":
        # 普通用戶只能更新自己的信息
        if current_user.id != user_id:
            return {
              "error": "Unauthorized",
              "message": "只能更新自己的信息"
            }
    elif current_user.role == "admin":
        # 管理員可以更新任何人，但有字段限制
        if field == "status" and current_user.permissions != "full_admin":
            return {
              "error": "Forbidden",
              "message": "需要完全管理員權限才能更新狀態"
            }

    # 層 3：執行 + 日誌
    db.update_user(user_id, field, value)
    log_operation(
        actor=current_user.id,
        action="update_user_info",
        target_user=user_id,
        field=field,
        timestamp=now()
    )

    return {"status": "success"}

案例 6：電商推薦工具鏈

場景：用戶問「有什麼推薦？」系統需要：

【工具鏈】

Step 1: get_user_profile(user_id)
  → 返回：用戶偏好、購買歷史、預算

Step 2: search_products(category, budget, preferences)
  → 返回：20 個產品候選

Step 3: get_product_details(product_ids: [前 5 個])
  → 返回：詳細評分、庫存、價格

Step 4: get_similar_users(user_id)
  → 返回：相似用戶 ID 列表

Step 5: get_top_rated_by_similar(similar_users)
  → 返回：相似用戶最喜歡的產品

Step 6: rank_and_deduplicate()
  → 返回：最終推薦清單（10 個）

【提示詞約束】
- 必須執行 Step 1 → 2 → 3（基礎推薦）
- 可選執行 Step 4 → 5（協作過濾）
- 最終使用 Step 6 整合結果
- 不要並行執行 Step 2 和 Step 3（浪費 token）

案例 7：工具集成測試清單

【單元測試】
✓ check_inventory("PROD-001") → 返回有效數據
✓ check_inventory("INVALID-SKU") → 返回錯誤碼
✓ check_inventory("", warehouse="HQ") → 驗證必填參數

【集成測試】
✓ 用戶問「有庫存嗎？」→ Claude 自動調用 check_inventory
✓ Claude 結果 = 庫存 0 → 建議替代品
✓ 多個工具串聯（查庫存→查價格→推薦）

【端到端測試】
✓ 用戶對話 5+ 轉折，涉及 3+ 個工具
✓ 驗證權限檢查是否正確
✓ 驗證錯誤恢復（如 API 超時時的降級方案）