openapi: 3.0.3
info:
  title: BenefitsAgent Tools
  version: 1.1.0
  description: Tools for AskBenefits — a healthcare plan member assistant.
servers:
  - url: https://taller-wox.fitlabs.dev/api

paths:

  /historical-procedures:
    post:
      operationId: query_historical_procedures
      summary: Query the member's past medical procedures
      description: |
        Retrieves the member's historical medical procedures with optional
        filtering and aggregation. Use this tool when the user asks about
        past procedures, what they paid for previous treatments, or wants
        a summary of their medical history.

        Example questions this tool answers:
        - "What procedures have I had this year?"
        - "How much did I pay for my last X-ray?"
        - "Show me all procedures at City Hospital."
        - "What did I spend on diagnostic procedures?"

        VALID COLUMN NAMES for filters and group_by:
        - member_name (string)
        - relationship (string: Self, Spouse, Mother, Father, Son, Daughter)
        - age (integer)
        - gender (string: Female, Male)
        - procedure (string: "Annual Physical Exam", "MRI", "CT Scan", "X Ray",
          "Dental Cleaning", "Vision Exam", "Blood Test", "Appendectomy")
        - procedure_type (string: preventive, surgery, diagnostic)
        - location (string: City Hospital, Green Valley Clinic, Sunrise Health,
          Regional Medical Center)
        - date (string: YYYY-MM-DD)
        - in_network (boolean: true, false)
        - member_plan (string: Gold PPO, Family Plan - Silver EPO, Bronze HDHP)
        - accepted_plans (string)
        - cost_facility, cost_physician, cost_anesthesia, cost_medication,
          total_cost (number)
        - facility_rating (number)
        - notes (string)

        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.
      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: List of matching procedure records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultArray'

  /available-procedures:
    post:
      operationId: query_available_procedures
      summary: Query available procedures and costs by provider
      description: |
        Searches the catalog of medical procedures available at in-network
        and out-of-network providers, with cost, location, distance and
        plan acceptance. Use this tool when the user asks where to get a
        procedure, how much it costs, or wants to compare providers.

        Example questions this tool answers:
        - "How much does an MRI cost?"
        - "Where can I get a dental cleaning near me?"
        - "Which hospital has the cheapest CT scan?"
        - "Is X-ray covered by my Gold PPO plan?"

        VALID COLUMN NAMES for filters and group_by:
        - procedure (string: "MRI", "CT Scan", "X Ray", "Annual Physical Exam",
          "Appendectomy", "Dental Cleaning", "Vision Exam", "Blood Test",
          "Angioplasty", "Ultrasound")
        - location (string: City Hospital, Green Valley Clinic, Sunrise Health,
          Regional Medical Center)
        - facility_rating (number)
        - distance_miles (number)
        - gold_ppo_plan_accepted (boolean)
        - silver_epo_plan_accepted (boolean)
        - accepted_plans (string)
        - cost_facility, cost_physician, cost_anesthesia, cost_medication,
          total_cost (number)

        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.

        VALUE MAPPING — when the user asks in Spanish, translate to the exact
        English value the dataset uses BEFORE calling the tool:
        - radiografía / rayos X → "X Ray"
        - resonancia / resonancia magnética → "MRI"
        - 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"
        - análisis de sangre → "Blood Test"
      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: List of matching available-procedure records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultArray'

  /member-insights:
    get:
      operationId: get_member_insights
      summary: Get the member's plan profile and overdue procedures
      description: |
        Returns the member's full plan profile including medical plan
        (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, plan data, and overdue procedures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberInsightsResponse'

  /schedule:
    get:
      operationId: get_scheduling_guidance
      summary: Get instructions for scheduling a medical appointment
      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: Scheduling guidance text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'

components:
  schemas:
    ProcedureQuery:
      type: object
      required: [filters, group_by]
      properties:
        filters:
          type: string
          description: |
            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 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