fix(api): tolerate column aliases (procedure_name → procedure) + Spanish value mappings

El LLM de watsonx Orchestrate estaba alucinando nombres de columnas
(procedure_name en lugar de procedure) y los valores de procedimientos
en español sin traducir. Dos fixes:

1. Backend (benefits_api.py): mapas _COLUMN_ALIASES y _VALUE_ALIASES
   resuelven aliases comunes (procedure_name, name, plan, etc.) y
   traducciones ES→EN (radiografía → X Ray, resonancia → MRI, etc.)
   antes de aplicar el filtro. Mensajes de error ahora listan columnas
   válidas para que el agente se corrija solo.

2. OpenAPI spec (yaml + json): description de cada operación ahora
   enumera explícitamente las columnas válidas y los valores válidos
   del campo procedure, más una sección VALUE MAPPING ES→EN para que
   el LLM no tenga que adivinar.

app/benefits_api.py

@@ -27,6 +27,79 @@ _OPS = {
     "le": lambda s, v: s <= v,
 }
 
+_COLUMN_ALIASES = {
+    "procedure_name": "procedure",
+    "procedurename": "procedure",
+    "proc": "procedure",
+    "name": "member_name",
+    "member": "member_name",
+    "membername": "member_name",
+    "location_name": "location",
+    "provider": "location",
+    "facility": "location",
+    "rating": "facility_rating",
+    "facilityrating": "facility_rating",
+    "distance": "distance_miles",
+    "plan": "member_plan",
+    "memberplan": "member_plan",
+    "type": "procedure_type",
+    "proceduretype": "procedure_type",
+    "cost": "total_cost",
+    "totalcost": "total_cost",
+    "price": "total_cost",
+    "in_network_only": "in_network",
+    "innetwork": "in_network",
+}
+
+_VALUE_ALIASES = {
+    "xray": "X Ray",
+    "x-ray": "X Ray",
+    "radiografia": "X Ray",
+    "radiografía": "X Ray",
+    "radiografias": "X Ray",
+    "radiografías": "X Ray",
+    "resonancia": "MRI",
+    "resonancia magnetica": "MRI",
+    "resonancia magnética": "MRI",
+    "tomografia": "CT Scan",
+    "tomografía": "CT Scan",
+    "ct": "CT Scan",
+    "limpieza dental": "Dental Cleaning",
+    "limpieza": "Dental Cleaning",
+    "examen visual": "Vision Exam",
+    "examen de la vista": "Vision Exam",
+    "vision": "Vision Exam",
+    "chequeo anual": "Annual Physical Exam",
+    "examen anual": "Annual Physical Exam",
+    "fisico anual": "Annual Physical Exam",
+    "apendicectomia": "Appendectomy",
+    "apendicectomía": "Appendectomy",
+    "analisis de sangre": "Blood Test",
+    "análisis de sangre": "Blood Test",
+}
+
+
+def _normalize_column(col: str, valid_cols: list[str]) -> str | None:
+    if col is None:
+        return None
+    if col in valid_cols:
+        return col
+    lower = col.lower().replace(" ", "").replace("-", "_")
+    if lower in _COLUMN_ALIASES:
+        candidate = _COLUMN_ALIASES[lower]
+        if candidate in valid_cols:
+            return candidate
+    return None
+
+
+def _normalize_value(val):
+    if not isinstance(val, str):
+        return val
+    lower = val.lower().strip()
+    if lower in _VALUE_ALIASES:
+        return _VALUE_ALIASES[lower]
+    return val
+
 
 def _apply_filters_and_group(df: pd.DataFrame, filters_raw, group_by_raw) -> list[dict]:
     try:
@@ -35,21 +108,34 @@ def _apply_filters_and_group(df: pd.DataFrame, filters_raw, group_by_raw) -> lis
     except json.JSONDecodeError as exc:
         raise HTTPException(status_code=400, detail=f"Invalid JSON in filters or group_by: {exc}")
 
+    valid_cols = list(df.columns)
     result = df.copy()
     for f in filters:
-        col, op, val = f.get("column"), f.get("operator"), f.get("value")
+        raw_col, op, val = f.get("column"), f.get("operator"), f.get("value")
-        if col not in result.columns:
+        col = _normalize_column(raw_col, valid_cols)
-            raise HTTPException(status_code=400, detail=f"Unknown column: {col}")
+        if col is None:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unknown column: {raw_col}. Valid columns: {valid_cols}",
+            )
         if op not in _OPS:
-            raise HTTPException(status_code=400, detail=f"Unsupported operator: {op}")
+            raise HTTPException(
-        result = result[_OPS[op](result[col], val)]
+                status_code=400,
+                detail=f"Unsupported operator: {op}. Valid operators: {list(_OPS.keys())}",
+            )
+        norm_val = _normalize_value(val)
+        result = result[_OPS[op](result[col], norm_val)]
 
     if group_by:
-        missing = [c for c in group_by if c not in result.columns]
+        norm_group = [_normalize_column(c, valid_cols) for c in group_by]
+        missing = [orig for orig, n in zip(group_by, norm_group) if n is None]
         if missing:
-            raise HTTPException(status_code=400, detail=f"Unknown group_by columns: {missing}")
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unknown group_by columns: {missing}. Valid columns: {valid_cols}",
+            )
         numeric_cols = result.select_dtypes(include="number").columns.tolist()
-        result = result.groupby(group_by)[numeric_cols].mean().reset_index()
+        result = result.groupby(norm_group)[numeric_cols].mean().reset_index()
 
     return result.to_dict(orient="records")
 

material/openapi-tools-spec.json

@@ -2,41 +2,67 @@
   "openapi": "3.0.3",
   "info": {
     "title": "BenefitsAgent Tools",
-    "version": "1.0.0"
+    "version": "1.1.0",
+    "description": "Tools for AskBenefits \u2014 a healthcare plan member assistant."
   },
   "servers": [
     {
-      "url": "https://taller-wox.fitlabs.dev/api/",
+      "url": "https://taller-wox.fitlabs.dev/api"
-      "description": "Local development server"
     }
   ],
   "paths": {
     "/historical-procedures": {
       "post": {
-        "summary": "This tool enables intelligent analysis and summarization of the historical procedures dataset.",
+        "operationId": "query_historical_procedures",
-        "description": "This tool enables intelligent analysis and summarization of the historical procedures dataset.\n### Key Features\n- Filtering on any combination of columns\n- Grouping and aggregation of results\n### Dataset Overview\nDetected columns:\n- **member_name**: e.g., Alice, Bob, Charlie...\n- **relationship**: e.g., Mother, Father, Son...\n- **age**: e.g., 42, 45, 12...\n- **gender**: e.g., Female, Male\n- **procedure**: e.g., Annual Physical Exam, Appendectomy, CT Scan...\n- **procedure_type**: e.g., preventive, surgery, diagnostic...\n- **location**: e.g., City Hospital, Green Valley Clinic, Sunrise Health...\n- **date**: e.g., 2024-04-28, 2023-05-02, 2022-05-11...\n- **in_network**: e.g., True, False\n- **member_plan**: e.g., Gold PPO, Family Plan - Silver EPO\n- **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Gold PPO, Family Plan - Silver EPO, Family Plan - Silver EPO, Medicare Advantage...\n- **cost_facility**: e.g., 29.4, 48.02, 30.8...\n- **cost_physician**: e.g., 199.09, 189.75, 128.9...\n- **cost_anesthesia**: e.g., 0.0, 2024.21, 2257.4...\n- **cost_medication**: e.g., 4.19, 5.53, 7.15...\n- **total_cost**: e.g., 232.68, 243.3, 166.85...\n- **facility_rating**: e.g., 4.7, 4.5, 4.6...\n- **notes**: e.g., Annual Physical Exam performed at City Hospital., Appendectomy performed at City Hospital., CT Scan performed at Green Valley Clinic....\n### Example Input:\n```json\n{\"filters\": [{\"column\": \"member_name\", \"operator\": \"equals\", \"value\": \"Alice\"}]}\n```\nExample Questions:\n- \"What rows match member_name = Alice?\" \u2192 `{\"filters\": [{\"column\": \"member_name\", \"operator\": \"equals\", \"value\": \"Alice\"}]}`",
+        "summary": "Query the member's past medical procedures",
+        "description": "Retrieves the member's historical medical procedures with optional\nfiltering and aggregation. Use this tool when the user asks about\npast procedures, what they paid for previous treatments, or wants\na summary of their medical history.\n\nExample questions this tool answers:\n- \"What procedures have I had this year?\"\n- \"How much did I pay for my last X-ray?\"\n- \"Show me all procedures at City Hospital.\"\n- \"What did I spend on diagnostic procedures?\"\n\nVALID COLUMN NAMES for filters and group_by:\n- member_name (string)\n- relationship (string: Self, Spouse, Mother, Father, Son, Daughter)\n- age (integer)\n- gender (string: Female, Male)\n- procedure (string: \"Annual Physical Exam\", \"MRI\", \"CT Scan\", \"X Ray\",\n  \"Dental Cleaning\", \"Vision Exam\", \"Blood Test\", \"Appendectomy\")\n- procedure_type (string: preventive, surgery, diagnostic)\n- location (string: City Hospital, Green Valley Clinic, Sunrise Health,\n  Regional Medical Center)\n- date (string: YYYY-MM-DD)\n- in_network (boolean: true, false)\n- member_plan (string: Gold PPO, Family Plan - Silver EPO, Bronze HDHP)\n- accepted_plans (string)\n- cost_facility, cost_physician, cost_anesthesia, cost_medication,\n  total_cost (number)\n- facility_rating (number)\n- notes (string)\n\nIMPORTANT: Use exactly these column names. Do NOT use \"procedure_name\",\n\"name\", or other variants. Both filters and group_by must be passed\nas JSON-encoded strings (not arrays).\nSupported operators: equals, ne, contains, gt, lt, ge, le.\n",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ProcedureQuery"
+              },
+              "examples": {
+                "filter_xray": {
+                  "summary": "Find the member's X-Ray history",
+                  "value": {
+                    "filters": "[{\"column\":\"procedure\",\"operator\":\"equals\",\"value\":\"X Ray\"}]",
+                    "group_by": "[]"
+                  }
+                },
+                "filter_by_member": {
+                  "summary": "Filter rows by member name",
+                  "value": {
+                    "filters": "[{\"column\":\"member_name\",\"operator\":\"equals\",\"value\":\"Charlie Smith\"}]",
+                    "group_by": "[]"
+                  }
+                },
+                "filter_contains": {
+                  "summary": "Filter by partial match",
+                  "value": {
+                    "filters": "[{\"column\":\"procedure\",\"operator\":\"contains\",\"value\":\"MRI\"}]",
+                    "group_by": "[]"
+                  }
+                },
+                "group_by_relationship": {
+                  "summary": "Aggregate costs by family relationship",
+                  "value": {
+                    "filters": "[]",
+                    "group_by": "[\"relationship\"]"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Successful result",
+            "description": "List of matching procedure records",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
+                  "$ref": "#/components/schemas/ResultArray"
-                  "properties": {
-                    "result": {
-                      "type": "object"
-                    }
-                  }
                 }
               }
             }
@@ -46,30 +72,56 @@
     },
     "/available-procedures": {
       "post": {
-        "summary": "This tool enables intelligent analysis and summarization of the available procedures dataset.",
+        "operationId": "query_available_procedures",
-        "description": "This tool enables intelligent analysis and summarization of the available procedures dataset.\n### Key Features\n- Filtering on any combination of columns\n- Grouping and aggregation of results\n### Dataset Overview\nDetected columns:\n- **procedure**: e.g., Angioplasty, Annual Physical Exam, Appendectomy...",
+        "summary": "Query available procedures and costs by provider",
+        "description": "Searches the catalog of medical procedures available at in-network\nand out-of-network providers, with cost, location, distance and\nplan acceptance. Use this tool when the user asks where to get a\nprocedure, how much it costs, or wants to compare providers.\n\nExample questions this tool answers:\n- \"How much does an MRI cost?\"\n- \"Where can I get a dental cleaning near me?\"\n- \"Which hospital has the cheapest CT scan?\"\n- \"Is X-ray covered by my Gold PPO plan?\"\n\nVALID COLUMN NAMES for filters and group_by:\n- procedure (string: \"MRI\", \"CT Scan\", \"X Ray\", \"Annual Physical Exam\",\n  \"Appendectomy\", \"Dental Cleaning\", \"Vision Exam\", \"Blood Test\",\n  \"Angioplasty\", \"Ultrasound\")\n- location (string: City Hospital, Green Valley Clinic, Sunrise Health,\n  Regional Medical Center)\n- facility_rating (number)\n- distance_miles (number)\n- gold_ppo_plan_accepted (boolean)\n- silver_epo_plan_accepted (boolean)\n- accepted_plans (string)\n- cost_facility, cost_physician, cost_anesthesia, cost_medication,\n  total_cost (number)\n\nIMPORTANT: Use exactly these column names. Do NOT use \"procedure_name\",\n\"name\", or other variants. Both filters and group_by must be passed\nas JSON-encoded strings (not arrays).\nSupported operators: equals, ne, contains, gt, lt, ge, le.\n\nVALUE MAPPING \u2014 when the user asks in Spanish, translate to the exact\nEnglish value the dataset uses BEFORE calling the tool:\n- radiograf\u00eda / rayos X \u2192 \"X Ray\"\n- resonancia / resonancia magn\u00e9tica \u2192 \"MRI\"\n- tomograf\u00eda \u2192 \"CT Scan\"\n- limpieza dental \u2192 \"Dental Cleaning\"\n- examen visual / de la vista \u2192 \"Vision Exam\"\n- examen anual / chequeo anual \u2192 \"Annual Physical Exam\"\n- apendicectom\u00eda \u2192 \"Appendectomy\"\n- an\u00e1lisis de sangre \u2192 \"Blood Test\"\n",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ProcedureQuery"
+              },
+              "examples": {
+                "filter_xray": {
+                  "summary": "Find X-Ray providers (use \"X Ray\" not \"radiografia\")",
+                  "value": {
+                    "filters": "[{\"column\":\"procedure\",\"operator\":\"equals\",\"value\":\"X Ray\"}]",
+                    "group_by": "[]"
+                  }
+                },
+                "filter_by_procedure": {
+                  "summary": "Find all MRI options",
+                  "value": {
+                    "filters": "[{\"column\":\"procedure\",\"operator\":\"equals\",\"value\":\"MRI\"}]",
+                    "group_by": "[]"
+                  }
+                },
+                "filter_cheap": {
+                  "summary": "Find procedures under $500",
+                  "value": {
+                    "filters": "[{\"column\":\"total_cost\",\"operator\":\"lt\",\"value\":500}]",
+                    "group_by": "[]"
+                  }
+                },
+                "group_avg_cost": {
+                  "summary": "Average cost by procedure",
+                  "value": {
+                    "filters": "[]",
+                    "group_by": "[\"procedure\"]"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Successful result",
+            "description": "List of matching available-procedure records",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
+                  "$ref": "#/components/schemas/ResultArray"
-                  "properties": {
-                    "result": {
-                      "type": "object"
-                    }
-                  }
                 }
               }
             }
@@ -79,20 +131,16 @@
     },
     "/member-insights": {
       "get": {
-        "summary": "Returns member data including plan information and overdue procedures.",
+        "operationId": "get_member_insights",
-        "description": "Returns member data including:\n- Plan information (medical, pharmacy, mental health, wellness, tax documents)\n- Overdue preventive procedures",
+        "summary": "Get the member's plan profile and overdue procedures",
+        "description": "Returns the member's full plan profile including medical plan\n(deductible, copays, coinsurance), pharmacy plan, mental health\ncoverage, wellness benefits, tax documents, and a list of\npreventive procedures the member is overdue for.\n\nUse this tool when the user asks about their plan details,\ndeductible status, what their plan covers, or whether they are\noverdue on any preventive checkups.\n\nExample questions this tool answers:\n- \"What's my plan?\"\n- \"How much have I met of my deductible?\"\n- \"Am I overdue on any checkups?\"\n- \"What's my copay for a specialist visit?\"\n",
         "responses": {
           "200": {
-            "description": "Member profile and plan data",
+            "description": "Member profile, plan data, and overdue procedures",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
+                  "$ref": "#/components/schemas/MemberInsightsResponse"
-                  "properties": {
-                    "result": {
-                      "type": "object"
-                    }
-                  }
                 }
               }
             }
@@ -102,20 +150,16 @@
     },
     "/schedule": {
       "get": {
-        "summary": "Provides appointment scheduling guidance.",
+        "operationId": "get_scheduling_guidance",
-        "description": "Provides appointment scheduling guidelines to help users arrange medical visits through a live scheduling system.",
+        "summary": "Get instructions for scheduling a medical appointment",
+        "description": "Returns step-by-step guidance for scheduling a medical appointment,\nincluding which provider to call, what information to confirm, and\nhow to handle pre-authorizations.\n\nUse this tool when the user asks to book, schedule, or arrange a\nmedical appointment.\n\nExample questions this tool answers:\n- \"Schedule me an appointment.\"\n- \"How do I book a visit with a specialist?\"\n- \"Can you set up my MRI?\"\n",
         "responses": {
           "200": {
-            "description": "Synthetic appointment instructions",
+            "description": "Scheduling guidance text",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
+                  "$ref": "#/components/schemas/ScheduleResponse"
-                  "properties": {
-                    "result": {
-                      "type": "string"
-                    }
-                  }
                 }
               }
             }
@@ -128,19 +172,108 @@
     "schemas": {
       "ProcedureQuery": {
         "type": "object",
+        "required": [
+          "filters",
+          "group_by"
+        ],
         "properties": {
           "filters": {
             "type": "string",
-            "description": "JSON-encoded list of filter objects",
+            "description": "JSON-encoded array of filter objects. Each filter has shape\n{\"column\": \"<name>\", \"operator\": \"<op>\", \"value\": <value>}.\nOperators: equals, ne, contains, gt, lt, ge, le.\nPass \"[]\" (empty string-encoded array) for no filters.\n",
-            "example": "[{\"column\": \"procedure\", \"operator\": \"equals\", \"value\": \"X ray\"}]"
+            "example": "[{\"column\":\"member_name\",\"operator\":\"equals\",\"value\":\"Charlie Smith\"}]"
           },
           "group_by": {
             "type": "string",
-            "description": "JSON-encoded list of columns to group by",
+            "description": "JSON-encoded array of column names to aggregate by. Numeric\ncolumns are averaged. Pass \"[]\" for no grouping.\n",
-            "example": "[\"facility_rating\"]"
+            "example": "[\"relationship\"]"
+          }
+        }
+      },
+      "ResultArray": {
+        "type": "object",
+        "properties": {
+          "result": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "MemberInsightsResponse": {
+        "type": "object",
+        "properties": {
+          "result": {
+            "type": "object",
+            "properties": {
+              "member": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "date_of_birth": {
+                    "type": "string"
+                  },
+                  "plan": {
+                    "type": "string"
+                  },
+                  "member_id": {
+                    "type": "string"
+                  }
+                }
+              },
+              "medical_plan": {
+                "type": "object"
+              },
+              "pharmacy_plan": {
+                "type": "object"
+              },
+              "mental_health": {
+                "type": "object"
+              },
+              "wellness": {
+                "type": "object"
+              },
+              "tax_documents": {
+                "type": "object"
+              },
+              "overdue_procedures": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "procedure": {
+                      "type": "string"
+                    },
+                    "last_date": {
+                      "type": "string"
+                    },
+                    "recommended_frequency_months": {
+                      "type": "integer"
+                    },
+                    "due_since_months": {
+                      "type": "integer"
+                    },
+                    "priority": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "ScheduleResponse": {
+        "type": "object",
+        "properties": {
+          "result": {
+            "type": "string"
           }
         }
       }
     }
   }
-}
+}

material/openapi-tools-spec.yaml

@@ -1,355 +1,284 @@
 openapi: 3.0.3
 info:
   title: BenefitsAgent Tools
-  version: 1.0.0
+  version: 1.1.0
+  description: Tools for AskBenefits — a healthcare plan member assistant.
 servers:
-- url: https://taller-wox.fitlabs.dev/api
+  - url: https://taller-wox.fitlabs.dev/api
-  description: Local development server
+
 paths:
+
   /historical-procedures:
     post:
-      summary: This tool enables intelligent analysis and summarization of the historical
+      operationId: query_historical_procedures
-        procedures dataset.
+      summary: Query the member's past medical procedures
-      description: |-
+      description: |
-        This tool enables intelligent analysis and summarization of the historical procedures dataset.
+        Retrieves the member's historical medical procedures with optional
-        ### Key Features
+        filtering and aggregation. Use this tool when the user asks about
-        - Filtering on any combination of columns
+        past procedures, what they paid for previous treatments, or wants
-        - Grouping and aggregation of results
+        a summary of their medical history.
-        ### Dataset Overview
+
-        Detected columns:
+        Example questions this tool answers:
-        - **member_name**: e.g., Alice, Bob, Charlie...
+        - "What procedures have I had this year?"
-        - **relationship**: e.g., Mother, Father, Son...
+        - "How much did I pay for my last X-ray?"
-        - **age**: e.g., 42, 45, 12...
+        - "Show me all procedures at City Hospital."
-        - **gender**: e.g., Female, Male
+        - "What did I spend on diagnostic procedures?"
-        - **procedure**: e.g., Annual Physical Exam, Appendectomy, CT Scan...
+
-        - **procedure_type**: e.g., preventive, surgery, diagnostic...
+        VALID COLUMN NAMES for filters and group_by:
-        - **location**: e.g., City Hospital, Green Valley Clinic, Sunrise Health...
+        - member_name (string)
-        - **date**: e.g., 2024-04-28, 2023-05-02, 2022-05-11...
+        - relationship (string: Self, Spouse, Mother, Father, Son, Daughter)
-        - **in_network**: e.g., True, False
+        - age (integer)
-        - **member_plan**: e.g., Gold PPO, Family Plan - Silver EPO
+        - gender (string: Female, Male)
-        - **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Gold PPO, Family Plan - Silver EPO, Family Plan - Silver EPO, Medicare Advantage...
+        - procedure (string: "Annual Physical Exam", "MRI", "CT Scan", "X Ray",
-        - **cost_facility**: e.g., 29.4, 48.02, 30.8...
+          "Dental Cleaning", "Vision Exam", "Blood Test", "Appendectomy")
-        - **cost_physician**: e.g., 199.09, 189.75, 128.9...
+        - procedure_type (string: preventive, surgery, diagnostic)
-        - **cost_anesthesia**: e.g., 0.0, 2024.21, 2257.4...
+        - location (string: City Hospital, Green Valley Clinic, Sunrise Health,
-        - **cost_medication**: e.g., 4.19, 5.53, 7.15...
+          Regional Medical Center)
-        - **total_cost**: e.g., 232.68, 243.3, 166.85...
+        - date (string: YYYY-MM-DD)
-        - **facility_rating**: e.g., 4.7, 4.5, 4.6...
+        - in_network (boolean: true, false)
-        - **notes**: e.g., Annual Physical Exam performed at City Hospital., Appendectomy performed at City Hospital., CT Scan performed at Green Valley Clinic....
+        - member_plan (string: Gold PPO, Family Plan - Silver EPO, Bronze HDHP)
-        ### Example Input:
+        - accepted_plans (string)
-        ```json
+        - cost_facility, cost_physician, cost_anesthesia, cost_medication,
-        {
+          total_cost (number)
-          "filters": [
+        - facility_rating (number)
-            {
+        - notes (string)
-              "column": "member_name",
+
-              "operator": "equals",
+        IMPORTANT: Use exactly these column names. Do NOT use "procedure_name",
-              "value": "Alice"
+        "name", or other variants. Both filters and group_by must be passed
-            }
+        as JSON-encoded strings (not arrays).
-          ]
+        Supported operators: equals, ne, contains, gt, lt, ge, le.
-        }
-        {
-          "filters": [
-            {
-              "column": "member_name",
-              "operator": "contains",
-              "value": "Ali"
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "member_name",
-              "operator": "ne",
-              "value": "Alice"
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "age",
-              "operator": "gt",
-              "value": 22.69
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "age",
-              "operator": "lt",
-              "value": 27.73
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "age",
-              "operator": "ge",
-              "value": 25
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "age",
-              "operator": "le",
-              "value": 25
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "age",
-              "operator": "ne",
-              "value": 25
-            }
-          ]
-        }
-        {
-          "group_by": [
-            "member_name",
-            "relationship"
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "member_name",
-              "operator": "equals",
-              "value": "Alice"
-            },
-            {
-              "column": "age",
-              "operator": "ge",
-              "value": 12.0
-            }
-          ],
-          "group_by": [
-            "relationship"
-          ]
-        }
-        ```
-        Example Questions:
-        - "What rows match member_name = Alice?" → `{"filters": [{"column": "member_name", "operator": "equals", "value": "Alice"}]}`
-        - "What rows do not match member_name = Alice?" → `{"filters": [{"column": "member_name", "operator": "ne", "value": "Alice"}]}`
-        - "What rows contain 'Ali' in member_name?" → `{"filters": [{"column": "member_name", "operator": "contains", "value": "Ali"}]}`
-        - "What rows have age greater than 25.21?" → `{"filters": [{"column": "age", "operator": "gt", "value": 25.21}]}`
-        - "What rows have age less than 25.21?" → `{"filters": [{"column": "age", "operator": "lt", "value": 25.21}]}`
-        - "What rows have age greater than or equal to 25.21?" → `{"filters": [{"column": "age", "operator": "ge", "value": 25.21}]}`
-        - "What rows have age less than or equal to 25.21?" → `{"filters": [{"column": "age", "operator": "le", "value": 25.21}]}`
-        - "What rows do not have age equal to 25.21?" → `{"filters": [{"column": "age", "operator": "ne", "value": 25.21}]}`
-        - "What is the average of age grouped by member_name?" → `{"group_by": ["member_name"]}`
-        - "What is the total age for member_name = 25.210526315789473 grouped by relationship?" → `{"filters": [{"column": "member_name", "operator": "equals", "value": "25.210526315789473"}], "group_by": ["relationship"]}`
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ProcedureQuery'
+            examples:
+              filter_xray:
+                summary: Find the member's X-Ray history
+                value:
+                  filters: '[{"column":"procedure","operator":"equals","value":"X Ray"}]'
+                  group_by: '[]'
+              filter_by_member:
+                summary: Filter rows by member name
+                value:
+                  filters: '[{"column":"member_name","operator":"equals","value":"Charlie Smith"}]'
+                  group_by: '[]'
+              filter_contains:
+                summary: Filter by partial match
+                value:
+                  filters: '[{"column":"procedure","operator":"contains","value":"MRI"}]'
+                  group_by: '[]'
+              group_by_relationship:
+                summary: Aggregate costs by family relationship
+                value:
+                  filters: '[]'
+                  group_by: '["relationship"]'
       responses:
         '200':
-          description: Successful result
+          description: List of matching procedure records
           content:
             application/json:
               schema:
-                type: object
+                $ref: '#/components/schemas/ResultArray'
-                properties:
+
-                  result:
-                    type: object
   /available-procedures:
     post:
-      summary: This tool enables intelligent analysis and summarization of the available
+      operationId: query_available_procedures
-        procedures dataset.
+      summary: Query available procedures and costs by provider
-      description: |-
+      description: |
-        This tool enables intelligent analysis and summarization of the available procedures dataset.
+        Searches the catalog of medical procedures available at in-network
-        ### Key Features
+        and out-of-network providers, with cost, location, distance and
-        - Filtering on any combination of columns
+        plan acceptance. Use this tool when the user asks where to get a
-        - Grouping and aggregation of results
+        procedure, how much it costs, or wants to compare providers.
-        ### Dataset Overview
+
-        Detected columns:
+        Example questions this tool answers:
-        - **procedure**: e.g., Angioplasty, Annual Physical Exam, Appendectomy...
+        - "How much does an MRI cost?"
-        - **location**: e.g., City Hospital, Regional Medical Center, Green Valley Clinic...
+        - "Where can I get a dental cleaning near me?"
-        - **facility_rating**: e.g., 4.7, 4.3, 4.5...
+        - "Which hospital has the cheapest CT scan?"
-        - **distance_miles**: e.g., 5.2, 12.6, 1.2...
+        - "Is X-ray covered by my Gold PPO plan?"
-        - **gold_ppo_plan_accepted**: e.g., True, False
+
-        - **silver_epo_plan_accepted**: e.g., True
+        VALID COLUMN NAMES for filters and group_by:
-        - **accepted_plans**: e.g., Gold PPO, Family Plan - Silver EPO, Medicare Advantage, Family Plan - Silver EPO, Bronze HDHP, Medicaid, Gold PPO, Family Plan - Silver EPO...
+        - procedure (string: "MRI", "CT Scan", "X Ray", "Annual Physical Exam",
-        - **cost_facility**: e.g., 9432.8, 23594.95, 3807.32...
+          "Appendectomy", "Dental Cleaning", "Vision Exam", "Blood Test",
-        - **cost_physician**: e.g., 4774.57, 4897.27, 5687.8...
+          "Angioplasty", "Ultrasound")
-        - **cost_anesthesia**: e.g., 1894.37, 581.04, 293.41...
+        - location (string: City Hospital, Green Valley Clinic, Sunrise Health,
-        - **cost_medication**: e.g., 834.8, 783.86, 1301.58...
+          Regional Medical Center)
-        - **total_cost**: e.g., 16936.54, 29857.12, 11090.11...
+        - facility_rating (number)
-        ### Example Input:
+        - distance_miles (number)
-        ```json
+        - gold_ppo_plan_accepted (boolean)
-        {
+        - silver_epo_plan_accepted (boolean)
-          "filters": [
+        - accepted_plans (string)
-            {
+        - cost_facility, cost_physician, cost_anesthesia, cost_medication,
-              "column": "procedure",
+          total_cost (number)
-              "operator": "equals",
+
-              "value": "Angioplasty"
+        IMPORTANT: Use exactly these column names. Do NOT use "procedure_name",
-            }
+        "name", or other variants. Both filters and group_by must be passed
-          ]
+        as JSON-encoded strings (not arrays).
-        }
+        Supported operators: equals, ne, contains, gt, lt, ge, le.
-        {
+
-          "filters": [
+        VALUE MAPPING — when the user asks in Spanish, translate to the exact
-            {
+        English value the dataset uses BEFORE calling the tool:
-              "column": "procedure",
+        - radiografía / rayos X → "X Ray"
-              "operator": "contains",
+        - resonancia / resonancia magnética → "MRI"
-              "value": "Ang"
+        - tomografía → "CT Scan"
-            }
+        - limpieza dental → "Dental Cleaning"
-          ]
+        - examen visual / de la vista → "Vision Exam"
-        }
+        - examen anual / chequeo anual → "Annual Physical Exam"
-        {
+        - apendicectomía → "Appendectomy"
-          "filters": [
+        - análisis de sangre → "Blood Test"
-            {
-              "column": "procedure",
-              "operator": "ne",
-              "value": "Angioplasty"
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "facility_rating",
-              "operator": "gt",
-              "value": 4.01
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "facility_rating",
-              "operator": "lt",
-              "value": 4.9
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "facility_rating",
-              "operator": "ge",
-              "value": 4
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "facility_rating",
-              "operator": "le",
-              "value": 4
-            }
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "facility_rating",
-              "operator": "ne",
-              "value": 4
-            }
-          ]
-        }
-        {
-          "group_by": [
-            "procedure",
-            "location"
-          ]
-        }
-        {
-          "filters": [
-            {
-              "column": "procedure",
-              "operator": "equals",
-              "value": "Angioplasty"
-            },
-            {
-              "column": "facility_rating",
-              "operator": "ge",
-              "value": 4.5
-            }
-          ],
-          "group_by": [
-            "location"
-          ]
-        }
-        ```
-        Example Questions:
-        - "What rows match procedure = Angioplasty?" → `{"filters": [{"column": "procedure", "operator": "equals", "value": "Angioplasty"}]}`
-        - "What rows do not match procedure = Angioplasty?" → `{"filters": [{"column": "procedure", "operator": "ne", "value": "Angioplasty"}]}`
-        - "What rows contain 'Ang' in procedure?" → `{"filters": [{"column": "procedure", "operator": "contains", "value": "Ang"}]}`
-        - "What rows have facility_rating greater than 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "gt", "value": 4.45}]}`
-        - "What rows have facility_rating less than 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "lt", "value": 4.45}]}`
-        - "What rows have facility_rating greater than or equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "ge", "value": 4.45}]}`
-        - "What rows have facility_rating less than or equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "le", "value": 4.45}]}`
-        - "What rows do not have facility_rating equal to 4.45?" → `{"filters": [{"column": "facility_rating", "operator": "ne", "value": 4.45}]}`
-        - "What is the average of facility_rating grouped by procedure?" → `{"group_by": ["procedure"]}`
-        - "What is the total facility_rating for procedure = 4.450442477876106 grouped by location?" → `{"filters": [{"column": "procedure", "operator": "equals", "value": "4.450442477876106"}], "group_by": ["location"]}`
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/ProcedureQuery'
+            examples:
+              filter_xray:
+                summary: Find X-Ray providers (use "X Ray" not "radiografia")
+                value:
+                  filters: '[{"column":"procedure","operator":"equals","value":"X Ray"}]'
+                  group_by: '[]'
+              filter_by_procedure:
+                summary: Find all MRI options
+                value:
+                  filters: '[{"column":"procedure","operator":"equals","value":"MRI"}]'
+                  group_by: '[]'
+              filter_cheap:
+                summary: Find procedures under $500
+                value:
+                  filters: '[{"column":"total_cost","operator":"lt","value":500}]'
+                  group_by: '[]'
+              group_avg_cost:
+                summary: Average cost by procedure
+                value:
+                  filters: '[]'
+                  group_by: '["procedure"]'
       responses:
         '200':
-          description: Successful result
+          description: List of matching available-procedure records
           content:
             application/json:
               schema:
-                type: object
+                $ref: '#/components/schemas/ResultArray'
-                properties:
+
-                  result:
-                    type: object
   /member-insights:
     get:
-      summary: Returns member data including plan information and overdue procedures.
+      operationId: get_member_insights
-      description: |-
+      summary: Get the member's plan profile and overdue procedures
-        Returns member data including:
+      description: |
-        - Plan information (medical, pharmacy, mental health, wellness, tax documents)
+        Returns the member's full plan profile including medical plan
-        - Overdue preventive procedures
+        (deductible, copays, coinsurance), pharmacy plan, mental health
+        coverage, wellness benefits, tax documents, and a list of
+        preventive procedures the member is overdue for.
+
+        Use this tool when the user asks about their plan details,
+        deductible status, what their plan covers, or whether they are
+        overdue on any preventive checkups.
+
+        Example questions this tool answers:
+        - "What's my plan?"
+        - "How much have I met of my deductible?"
+        - "Am I overdue on any checkups?"
+        - "What's my copay for a specialist visit?"
       responses:
         '200':
-          description: Member profile and plan data
+          description: Member profile, plan data, and overdue procedures
           content:
             application/json:
               schema:
-                type: object
+                $ref: '#/components/schemas/MemberInsightsResponse'
-                properties:
+
-                  result:
-                    type: object
   /schedule:
     get:
-      summary: Provides appointment scheduling guidance.
+      operationId: get_scheduling_guidance
-      description: Provides appointment scheduling guidelines to help users arrange
+      summary: Get instructions for scheduling a medical appointment
-        medical visits through a live scheduling system.
+      description: |
+        Returns step-by-step guidance for scheduling a medical appointment,
+        including which provider to call, what information to confirm, and
+        how to handle pre-authorizations.
+
+        Use this tool when the user asks to book, schedule, or arrange a
+        medical appointment.
+
+        Example questions this tool answers:
+        - "Schedule me an appointment."
+        - "How do I book a visit with a specialist?"
+        - "Can you set up my MRI?"
       responses:
         '200':
-          description: Synthetic appointment instructions
+          description: Scheduling guidance text
           content:
             application/json:
               schema:
-                type: object
+                $ref: '#/components/schemas/ScheduleResponse'
-                properties:
+
-                  result:
-                    type: string
 components:
   schemas:
     ProcedureQuery:
       type: object
+      required: [filters, group_by]
       properties:
         filters:
           type: string
-          description: JSON-encoded list of filter objects
+          description: |
-          example: '[{"column": "procedure", "operator": "equals", "value": "X ray"}]'
+            JSON-encoded array of filter objects. Each filter has shape
+            {"column": "<name>", "operator": "<op>", "value": <value>}.
+            Operators: equals, ne, contains, gt, lt, ge, le.
+            Pass "[]" (empty string-encoded array) for no filters.
+          example: '[{"column":"member_name","operator":"equals","value":"Charlie Smith"}]'
         group_by:
           type: string
-          description: JSON-encoded list of columns to group by
+          description: |
-          example: '["facility_rating"]'
+            JSON-encoded array of column names to aggregate by. Numeric
+            columns are averaged. Pass "[]" for no grouping.
+          example: '["relationship"]'
+
+    ResultArray:
+      type: object
+      properties:
+        result:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+
+    MemberInsightsResponse:
+      type: object
+      properties:
+        result:
+          type: object
+          properties:
+            member:
+              type: object
+              properties:
+                name: { type: string }
+                date_of_birth: { type: string }
+                plan: { type: string }
+                member_id: { type: string }
+            medical_plan:
+              type: object
+            pharmacy_plan:
+              type: object
+            mental_health:
+              type: object
+            wellness:
+              type: object
+            tax_documents:
+              type: object
+            overdue_procedures:
+              type: array
+              items:
+                type: object
+                properties:
+                  procedure: { type: string }
+                  last_date: { type: string }
+                  recommended_frequency_months: { type: integer }
+                  due_since_months: { type: integer }
+                  priority: { type: string }
+
+    ScheduleResponse:
+      type: object
+      properties:
+        result:
+          type: string