pms-analysis-reports-mcp-server/dist/tools/schema.js

PMS analysis reports server handling maintenance reports, equipment analysis, compliance tracking, and performance metrics with ERP access for data extraction

export const listToolsRequestSchema = {
    type: "object",
    properties: {
        category: {
            type: "string",
            description: "Optional category to filter tools by",
            enum: ["analysis", "reports", "maintenance", "compliance", "performance"]
        },
        search: {
            type: "string",
            description: "Optional search term to filter tools by name or description"
        },
        include_deprecated: {
            type: "boolean",
            description: "Whether to include deprecated tools in the response",
            default: false
        }
    },
    additionalProperties: false
};
// Typesense tool definitions
export const typesenseTools = [
    {
        name: "universal_fuel_analysis_search",
        description: `Universal search handler for ALL Fuel Oil Analysis operations. This tool replaces all individual fuel analysis tools and provides comprehensive functionality for:

        ✅ **Report Management**: Get latest fuel analysis reports, historical data analysis
        ✅ **Advanced Search**: Complex queries across all fuel oil analysis data
        ✅ **Direct Query**: Full Typesense query control
        ✅ **Structured Parameters**: Separate fields for query, filter, and sort operations
        ✅ **Field Validation**: Only accepts fields from the documented schema below
        ✅ **Flexible Search**: Supports full-text search across indexed fields
        ✅ **Date Filtering**: Supports date range filtering with yyyy-mm-dd format

        ## OPERATION MODES

        ### **Simple Parameter Operations**
        - **Latest Report**: Use filter_by: "imo:123456789" + optional filter_by: "fuelType:VLSFO" + per_page=5 + sort_by: "bunkerDate:desc"
        - **Historical Data**: Use filter_by: "imo:123456789 && bunkerDate:>=YYYY-MM-DD" + optional filter_by with fuelType

        ## PARAMETER USAGE
        - **query_by**: Comma-separated field names for full-text search (e.g., "vesselName,bunkerPort,fuelType,supplier")
        - **q**: Search query string for full-text search (e.g., "VLSFO Singapore")
        - **filter_by**: Filtering conditions using Typesense syntax (e.g., "rating:WARNING && sulfur:<0.5")
        - **sort_by**: Field name with direction for sorting (e.g., "bunkerDate:desc,sulfur:asc")
        - **page**: Page number for pagination (default: 1)
        - **per_page**: Results per page, up to 250 (default: 50)

        ## DATE HANDLING
        **IMPORTANT**: For date fields (bunkerDate), always use **yyyy-mm-dd** format in filter_by parameter.
        
        **Examples**:
        - ✅ CORRECT: "bunkerDate:>=2024-01-01"
        - ✅ CORRECT: "bunkerDate:<=2024-12-31"
        - ❌ WRONG: "bunkerDate:>=01-01-2024" (dd-mm-yyyy format)

        ## COMMON MISTAKES TO AVOID
        ❌ WRONG: Using non-existent fields
        ❌ WRONG: Incorrect date format (use yyyy-mm-dd for date filters, NOT dd-mm-yyyy)
        ❌ WRONG: Using SQL syntax instead of Typesense syntax for filters

        ## TYPESENSE DATABASE SCHEMA - FUEL OIL DATA TABLE
        The fuel_oil_data table contains comprehensive fuel oil analysis data organized into the following categories:

        ### 1. VESSEL INFORMATION (2 fields)
        Information about the vessel associated with fuel oil samples.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | imo | int64 | IMO number of the vessel only use for filter not in queryby argument |
        | vesselName | string | Name of the vessel |

        ### 2. SAMPLE IDENTIFICATION (3 fields)
        Core sample identification information.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | sampleId | string | Unique sample identification number for the fuel test |
        | bunkerDate | int64 | Date when fuel was bunkered (Unix timestamp). Use symbols > < = for date range queries |
        | bunkerPort | string | Port where the fuel was bunkered |

        ### 3. FUEL PROPERTIES (6 fields)
        Basic fuel type and supplier information.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | fuelType | string | Type of fuel (e.g., VLSFO, HSFO, MGO, MDO) |
        | supplier | string | Fuel supplier name |
        | testLab | string | Laboratory that conducted the fuel analysis |
        | rating | string | Overall fuel quality rating (e.g., Normal, Warning, Alert) |
        | sulfur | float | Sulfur content in percentage |
        | density@15°C | float | Fuel density at 15°C in kg/m³ |

        ### 4. VISCOSITY AND TEMPERATURE PROPERTIES (5 fields)
        Viscosity and temperature-related properties of the fuel.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | viscosity50C | float | Kinematic viscosity at 50°C in cSt |
        | viscosity100C | float | Kinematic viscosity at 100°C in cSt |
        | flashPoint | string | Flash point temperature (may include > or < symbols) |
        | pourPoint | float | Pour point temperature in °C |
        | storageTemperature | float | Recommended storage temperature in °C |

        ### 5. COMPOSITION PROPERTIES (7 fields)
        Chemical composition properties of the fuel.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | water | string | Water content (may include < symbol) |
        | ash | float | Ash content percentage |
        | microCarbonResidue | float | Micro carbon residue percentage |
        | netSpecificEnergy | float | Net specific energy in MJ/kg |
        | calculatedCarbonAromaticityIndex | float | Calculated Carbon Aromaticity Index |
        | acidNumber | float | Acid number in mg KOH/g |
        | totalSedimentPotential | float | Total sediment potential percentage |

        ### 6. METAL CONTENT (11 fields)
        Metal content measurements in the fuel.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | vanadium | float | Vanadium content in mg/kg |
        | aluminium | float | Aluminium content in mg/kg |
        | silicon | float | Silicon content in mg/kg |
        | iron | float | Iron content in mg/kg |
        | nickel | float | Nickel content in mg/kg |
        | calcium | float | Calcium content in mg/kg |
        | sodium | string | Sodium content in mg/kg (may include < symbol) |
        | magnesium | string | Magnesium content in mg/kg (may include < symbol) |
        | zinc | string | Zinc content in mg/kg (may include < symbol) |
        | lead | string | Lead content in mg/kg (may include < symbol) |
        | phosphorus | string | Phosphorus content in mg/kg (may include < symbol) |

        ### 7. SAMPLING AND HANDLING (5 fields)
        Information about sampling methods and handling.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | samplingMethod | string | Method used for fuel sampling |
        | samplingPoint | string | Location where fuel sample was taken |
        | receivedDate | string | Date when sample was received by laboratory |
        | sentDate | string | Date when sample was sent to laboratory |
        | separationTemperature | float | Recommended separation temperature in °C |

        ### 8. BUNKER DELIVERY NOTE (BDN) DATA (6 fields)
        Information from the bunker delivery note.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | bdnDensity@15°C | string | Bunker Delivery Note density at 15°C with unit |
        | bdnSulfur | string | Bunker Delivery Note sulfur content with unit |
        | bdnViscosity | string | Bunker Delivery Note viscosity with unit |
        | bdnWater | string | Bunker Delivery Note water content with unit |
        | bdnReceiptNumber | string | Bunker Delivery Note receipt number |
        | barge | string | Name of the barge used for fuel delivery |

        ### 9. ADDITIONAL PROPERTIES (5 fields)
        Additional properties and compliance information.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | specificGravity | string | Specific gravity of the fuel |
        | hydrogenSulphide | string | Hydrogen sulphide test result |
        | potassium | string | Potassium content in mg/kg (may include < symbol) |
        | injectionTemp | string | Recommended injection temperatures for different viscosities |
        | complianceComments | string | Detailed compliance comments and recommendations from the testing laboratory |

        ### 10. SYSTEM FIELDS (2 fields)
        System-generated fields.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | location | string | URL or file path to the detailed fuel analysis report |
        | _id | string | Unique document identifier |

        ## USAGE EXAMPLES

        **Basic Search Queries:**
        - universal_fuel_analysis_search(query_by="vesselName,bunkerPort", q="Singapore", per_page=100)
        - universal_fuel_analysis_search(filter_by="fuelType:VLSFO", sort_by="bunkerDate:desc")

        **Advanced Filtering:**
        - universal_fuel_analysis_search(filter_by="imo:9000000 && sulfur:<0.5", sort_by="bunkerDate:desc")
        - universal_fuel_analysis_search(filter_by="rating:WARNING && fuelType:VLSFO", query_by="vesselName", q="*")

        **Date Range Filtering:**
        - universal_fuel_analysis_search(filter_by="bunkerDate:>=2024-01-01 && bunkerDate:<=2024-12-31")
        - universal_fuel_analysis_search(filter_by="bunkerDate:<2024-08-15 && rating:WARNING")

        **Complex Queries:**
        - universal_fuel_analysis_search(query_by="supplier,bunkerPort", q="Shell", filter_by="sulfur:<0.5 && viscosity50C:>180", sort_by="bunkerDate:desc")

        **Simple Parameter Operations (replacing individual functions):**
        - universal_fuel_analysis_search(filter_by="imo:123456789 && fuelType:VLSFO", sort_by="bunkerDate:desc", per_page=5) // get_latest_fuel_analysis_report
        - universal_fuel_analysis_search(filter_by="imo:123456789 && bunkerDate:>=2024-04-01 && fuelType:VLSFO") // get_historical_fuel_analysis_data (6 months lookback example)

        ## SECURITY NOTES
        - Results are filtered based on company restrictions
        - Queries have timeout limits
        - Maximum 250 results per page
        - All date filters must use yyyy-mm-dd format

        This tool enables advanced analytics, reporting, and data exploration for fuel oil quality management operations.`,
        inputSchema: {
            type: "object",
            properties: {
                query_by: {
                    type: "string",
                    description: "Comma-separated list of field names to search in for full-text search. Only use string fields that are useful for text-based queries.",
                    enum: [
                        "vesselName",
                        "sampleId",
                        "bunkerPort",
                        "fuelType",
                        "supplier",
                        "testLab",
                        "rating",
                        "flashPoint",
                        "water",
                        "sodium",
                        "magnesium",
                        "zinc",
                        "lead",
                        "phosphorus",
                        "potassium",
                        "samplingMethod",
                        "samplingPoint",
                        "receivedDate",
                        "sentDate",
                        "bdnDensity@15°C",
                        "bdnSulfur",
                        "bdnViscosity",
                        "bdnWater",
                        "bdnReceiptNumber",
                        "barge",
                        "specificGravity",
                        "hydrogenSulphide"
                    ]
                },
                q: {
                    type: "string",
                    description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'VLSFO Singapore' or 'Shell*'",
                    default: "*"
                },
                filter_by: {
                    type: "string",
                    description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'fuelType:VLSFO && sulfur:<0.5'"
                },
                sort_by: {
                    type: "string",
                    description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'bunkerDate:desc,sulfur:asc'",
                    default: "relevance"
                },
                page: {
                    type: "number",
                    description: "Page number for pagination. Default: 1",
                    minimum: 1,
                    default: 1
                },
                per_page: {
                    type: "number",
                    description: "Number of results per page. Maximum: 250, Default: 50",
                    minimum: 1,
                    maximum: 250,
                    default: 50
                }
            },
            required: [],
            additionalProperties: false
        }
    },
    // ============================================================================
    // INDIVIDUAL FUEL ANALYSIS TOOLS - REPLACED BY universal_fuel_analysis_search
    // ============================================================================
    // The following individual fuel analysis tools have been consolidated into the 
    // universal_fuel_analysis_search tool above. They are commented out but kept for 
    // reference and potential future use if needed.
    // ============================================================================
    // {
    //     name: "get_latest_fuel_analysis_report",
    //     description: "This tool retrieves the latest fuel oil analysis report for a specified vessel using its vessel name or IMO number and for a specific fuel type if provided.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "number", description: "IMO number of the vessel"},
    //             fuelType: {type: "string", description: "Optional fuel type filter (e.g., \"VLSFO\", \"HSFO\", \"MGO\", \"LSMGO\")."},
    //             per_page: {type: "number", description: "Set to 5 (default) because only the newest report is needed."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "get_historical_fuel_analysis_data",
    //     description: "This tool retrieves historical fuel oil analysis data for a specified vessel over the last X months or years for trend analysis purposes.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "string", description: "IMO number of the vessel."},
    //             lookback_months: {type: "number", description: "Number of months to look back for historical data (e.g., 6 for last 6 months, 24 for last 2 years)."},
    //             fuelType: {type: "string", description: "Optional fuel type filter (e.g., \"VLSFO\", \"HSFO\", \"MGO\", \"LSMGO\"). Omit to include all fuel types."},
    //             per_page: {type: "number", description: "Number of records to return per page (default 100 for comprehensive trend analysis)."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo", "lookback_months"],
    //         additionalProperties: false
    //     }
    // },
    {
        name: "universal_pms_maintenance_search",
        description: `Universal search handler for ALL Planned Maintenance System (PMS) operations. This tool replaces all individual PMS maintenance tools and provides comprehensive functionality for:

        ✅ **Job Management**: List jobs by category and status, overdue jobs
        ✅ **Component Operations**: List jobs for specific components, jobs due within timeframe
        ✅ **Advanced Search**: Complex queries across all PMS maintenance data
        ✅ **Direct Query**: Full Typesense query control
        ✅ **Structured Parameters**: Separate fields for query, filter, and sort operations
        ✅ **Field Validation**: Only accepts fields from the documented schema below
        ✅ **Flexible Search**: Supports full-text search across indexed fields
        ✅ **Date Filtering**: Supports date range filtering with yyyy-mm-dd format

        ## OPERATION MODES

        ### **Simple Parameter Operations**
        - **Jobs by Category/Status**: Use filter_by: "imo:123456789 && jobCategory:CRITICAL && jobStatus:OVERDUE"
        - **Jobs for Component**: Use filter_by: "imo:123456789" + query_by: "component" + q: "breathing air compressor"
        - **Component Due Within**: Use filter_by: "imo:123456789 && remainingDaysNextOverhaul:<30" + query_by: "component" + q: "purifier"
        - **Overdue Jobs**: Use filter_by: "imo:123456789 && jobStatus:OVERDUE" + optional filter_by with jobCategory

        ## PARAMETER USAGE
        - **query_by**: Comma-separated field names for full-text search (e.g., "vesselName,jobTitle,component")
        - **q**: Search query string for full-text search (e.g., "exhaust valve overhaul")
        - **filter_by**: Filtering conditions using Typesense syntax (e.g., "jobCategory:CRITICAL && imo:9000000")
        - **sort_by**: Field name with direction for sorting (e.g., "jobDueDate:asc,remainingDaysNextOverhaul:asc")
        - **page**: Page number for pagination (default: 1)
        - **per_page**: Results per page, up to 250 (default: 50)

        ## DATE HANDLING
        **IMPORTANT**: For date fields (jobDueDate, jobDoneDate, defermentRequestedDate), always use **yyyy-mm-dd** format in filter_by parameter.
        
        **Examples**:
        - ✅ CORRECT: "jobDueDate:>=2024-01-01"
        - ✅ CORRECT: "jobDoneDate:<=2024-12-31"
        - ❌ WRONG: "jobDueDate:>=01-01-2024" (dd-mm-yyyy format)

        ## COMMON MISTAKES TO AVOID
        ❌ WRONG: Using non-existent fields
        ❌ WRONG: Incorrect date format (use yyyy-mm-dd for date filters, NOT dd-mm-yyyy)
        ❌ WRONG: Using SQL syntax instead of Typesense syntax for filters

        ## TYPESENSE DATABASE SCHEMA - PMS TABLE
        The PMS table contains comprehensive maintenance job data organized into the following categories:

        ### 1. VESSEL INFORMATION (2 fields)
        Information about the vessel associated with maintenance jobs.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | imo | int64 | IMO number of the vessel only use for filter not in queryby argument |
        | vesselName | string | Name of the vessel |

        ### 2. JOB INFORMATION (5 fields)
        Core job details and categorization.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | jobTitle | string | Title or description of the maintenance job (e.g., "ME EXHAUST VALVE OVERHAUL", "AE FUEL INJECTOR ROUTINES"). Use abbreviations – ME (Main Engine), AE/DG (Auxiliary Engine), SW (Sea Water), FW (Fresh Water), OWS (Oily Water Separator). |
        | jobCategory | string | Category of the job (use only if specifically requested). Possible values: "CRITICAL", "NON‑CRITICAL". |
        | intervalType | string | Interval basis for scheduling the job. Possible values: "HOURS", "DAILY", "WEEKLY", "MONTHLY", "HALF YEARLY", "YEARLY". |
        | jobStatus | string | Current job status (use only if explicitly asked). Possible values: "IN ORDER" (not overdue), "OVERDUE". |
        | type | string | Distinguishes Life‑Saving/Fire‑Fighting Appliances jobs. Value is "LSA/FFA" when applicable; otherwise null. |

        ### 3. COMPONENT INFORMATION (1 field)
        Information about the component being maintained.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | component | string | The name of the component which is being maintained |

        ### 4. SCHEDULING AND TIMING (4 fields)
        Job scheduling, due dates, and completion information.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | remainingHrsNextOverhaul | number | Hours remaining until the next overhaul (use only if explicitly asked). Query with symbols as strings, e.g., ">10", "<10", "=10". |
        | remainingDaysNextOverhaul | number | Days remaining until the next overhaul (use only if explicitly asked). Query with symbols as strings, e.g., ">10", "<10", "=10". |
        | jobDueDate | string | Next due date for the job. Convert to date‑time for querying; use symbols > < = (e.g., ">2025-01-01 <2025-12-31"). |
        | jobDoneDate | string | Date the job was performed. Convert to date‑time for querying; use symbols > < = (e.g., ">2025-01-01 <2025-12-31"). |

        ### 5. DEFERMENT INFORMATION (3 fields)
        Information about job deferments and their status.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | defermentApplied | string | Indicates whether a deferment request has been submitted. Possible values: "YES", "NO". |
        | defermentRequestedDate | string | Date the deferment was requested. Convert to date‑time for querying; use symbols > < = (e.g., ">2025-01-01 <2025-12-31"). |
        | defermentStatus | string | Current status of the deferment request. Possible values: "DEFERMENT APPROVED", "AWAITING APPROVAL", "DEFERMENT REJECTED", "NOT APPLICABLE". |

        ## USAGE EXAMPLES

        **Basic Search Queries:**
        - universal_pms_maintenance_search(query_by="jobTitle,component", q="exhaust valve", per_page=100)
        - universal_pms_maintenance_search(filter_by="jobStatus:OVERDUE", sort_by="jobDueDate:asc")

        **Advanced Filtering:**
        - universal_pms_maintenance_search(filter_by="imo:9000000 && jobCategory:CRITICAL", sort_by="remainingDaysNextOverhaul:asc")
        - universal_pms_maintenance_search(filter_by="intervalType:MONTHLY && jobStatus:OVERDUE", query_by="component", q="*")

                 **Date Range Filtering:**
         - universal_pms_maintenance_search(filter_by="jobDueDate:>=2024-01-01 && jobDueDate:<=2024-12-31")
         - universal_pms_maintenance_search(filter_by="jobDoneDate:<2024-08-15 && defermentApplied:YES")

        **Complex Queries:**
        - universal_pms_maintenance_search(query_by="component,jobTitle", q="main engine", filter_by="remainingDaysNextOverhaul:<30 && jobCategory:CRITICAL", sort_by="remainingDaysNextOverhaul:asc")

        **Simple Parameter Operations (replacing individual functions):**
        - universal_pms_maintenance_search(filter_by="imo:123456789 && jobCategory:CRITICAL && jobStatus:OVERDUE") // list_pms_jobs_by_category_and_status
        - universal_pms_maintenance_search(filter_by="imo:123456789", query_by="component", q="breathing air compressor") // list_pms_jobs_for_component
        - universal_pms_maintenance_search(filter_by="imo:123456789 && remainingDaysNextOverhaul:<30", query_by="component", q="purifier") // list_pms_jobs_for_component_due_within (30 days)
        - universal_pms_maintenance_search(filter_by="imo:123456789 && jobStatus:OVERDUE && jobCategory:CRITICAL") // list_overdue_pms_jobs

        ## SECURITY NOTES
        - Results are filtered based on company restrictions
        - Queries have timeout limits
        - Maximum 250 results per page
        - All date filters must use yyyy-mm-dd format

        This tool enables advanced analytics, reporting, and data exploration for planned maintenance operations.`,
        inputSchema: {
            type: "object",
            properties: {
                query_by: {
                    type: "string",
                    description: "Comma-separated list of field names to search in for full-text search. Only use string fields that are useful for text-based queries.",
                    enum: [
                        "vesselName",
                        "jobTitle",
                        "jobCategory",
                        "intervalType",
                        "jobStatus",
                        "type",
                        "component",
                        "defermentApplied",
                        "defermentStatus"
                    ]
                },
                q: {
                    type: "string",
                    description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'exhaust valve' or 'main engine*'",
                    default: "*"
                },
                filter_by: {
                    type: "string",
                    description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'jobCategory:CRITICAL && imo:9000000'"
                },
                sort_by: {
                    type: "string",
                    description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'jobDueDate:asc,remainingDaysNextOverhaul:asc'",
                    default: "relevance"
                },
                page: {
                    type: "number",
                    description: "Page number for pagination. Default: 1",
                    minimum: 1,
                    default: 1
                },
                per_page: {
                    type: "number",
                    description: "Number of results per page. Maximum: 250, Default: 50",
                    minimum: 1,
                    maximum: 250,
                    default: 50
                }
            },
            required: [],
            additionalProperties: false
        }
    },
    // ============================================================================
    // INDIVIDUAL PMS MAINTENANCE TOOLS - REPLACED BY universal_pms_maintenance_search
    // ============================================================================
    // The following individual PMS maintenance tools have been consolidated into the 
    // universal_pms_maintenance_search tool above. They are commented out but kept for 
    // reference and potential future use if needed.
    // ============================================================================
    // {
    //     name: "list_pms_jobs_by_category_and_status",
    //     description: "Use this tool to list Planned-Maintenance (PMS) jobs for a vessel that match a specific **job category** and **job status**.",
    //     inputSchema: {
    //         type: "object",
    //         required: ["imo", "jobCategory", "jobStatus"],
    //         properties: {
    //             imo: {
    //                 type: "string",
    //                 description: "IMO number of the vessel"
    //             },
    //             jobCategory: {
    //                 type: "string",
    //                 enum: ["CRITICAL", "NON-CRITICAL"],
    //                 description: "Maintenance job category to filter."
    //             },
    //             jobStatus: {
    //                 type: "string",
    //                 enum: ["OVERDUE", "IN ORDER"],
    //                 description: "Status of the job to filter. Value must match the database exactly."
    //             },
    //             per_page: {
    //                 type: "number",
    //                 description: "Number of records to return per page (default is 250)."
    //             },
    //             session_id: {
    //                 type: "string",
    //                 description: "Session ID for tracking client sessions, if available"
    //             }
    //         },
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "list_pms_jobs_for_component",
    //     description: "Use this tool to list Planned-Maintenance (PMS) jobs for a component or machinery (e.g., \"Breathing Air Compressor\").",
    //     inputSchema: {
    //         type: "object",
    //         required: ["imo", "component"],
    //         properties: {
    //             imo: {
    //                 type: "string",
    //                 description: "IMO number of the vessel"
    //             },
    //             component: {
    //                 type: "string",
    //                 description: "Full or partial text to match the component or machinery name(e.g., breathing air compressor)."
    //             },
    //             per_page: {
    //                 type: "number",
    //                 description: "Number of records to return per page (default is 250)."
    //             },
    //             session_id: {
    //                 type: "string",
    //                 description: "Session ID for tracking client sessions, if available"
    //             }
    //         },
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "list_pms_jobs_for_component_due_within",
    //     description: "Use this tool to list Planned-Maintenance (PMS) jobs for a vessel **whose due-date falls within the next *X* days** and that belong to a specific machinery *component*.",
    //     inputSchema: {
    //         type: "object",
    //         required: ["imo", "component", "days"],
    //         properties: {
    //             imo: {
    //                 type: "string",
    //                 description: "IMO number of the vessel."
    //             },
    //             component: {
    //                 type: "string",
    //                 description: "Machinery component (keyword) to match in the PMS record, e.g., \"purifier\"."
    //             },
    //             days: {
    //                 type: "number",
    //                 description: "Number of days to look ahead for due dates."
    //             },
    //             per_page: {
    //                 type: "number",
    //                 description: "Number of records to return per page (default is 250)."
    //             },
    //             session_id: {
    //                 type: "string",
    //                 description: "Session ID for tracking client sessions, if available"
    //             }
    //         },
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "list_overdue_pms_jobs",
    //     description: "Return Planned-Maintenance (PMS) jobs for a vessel that are **OVERDUE**.",
    //     inputSchema: {
    //         type: "object",
    //         required: ["imo"],
    //         properties: {
    //             imo: {
    //                 type: "string",
    //                 description: "IMO number of the vessel."
    //             },
    //             jobCategory: {
    //                 type: "string",
    //                 enum: ["CRITICAL", "NON-CRITICAL"],
    //                 description: "Optional filter to restrict the results to critical or non-critical jobs."
    //             },
    //             per_page: {
    //                 type: "number",
    //                 description: "Number of records to return per page (default 50)."
    //             }
    //         },
    //         additionalProperties: false
    //     }
    // },
    {
        name: "universal_lube_oil_search",
        description: `Universal search handler for ALL Lube Oil operations. This tool replaces all individual lube oil tools and provides comprehensive functionality for:

        ✅ **Sample Management**: List overdue samples, samples by frequency
        ✅ **Analysis Reports**: Get latest analysis for machinery, machinery with warnings
        ✅ **Data Retrieval**: Fetch analysis with shareable links
        ✅ **Schema Information**: Get table schema and query instructions
        ✅ **Advanced Search**: Complex queries across all lube oil data
        ✅ **Direct Query**: Full Typesense query control
        ✅ **Fallback Query**: Advanced nested query object support
        ✅ **Collection Management**: Direct collection specification

        ## OPERATION MODES

        ### **Simple Parameter Operations**
        - **Overdue Samples**: Use filter_by: "imo:123456789 && dueStatus:OVERDUE" + optional query_by/q for machineryName search
        - **Warning Analysis**: Use filter_by: "imo:123456789 && reportStatus:WARNING" + optional query_by/q for machineryName search
        - **Latest Analysis**: Use filter_by: "imo:123456789" + query_by: "machineryName" + q: "main engine" + sort_by: "sampleDate:desc"
        - **Frequency Samples**: Use filter_by: "imo:123456789 && frequency:weekly"
        - **Fetch with Link**: Use filter_by: "imo:123456789" + optional query_by/q for machineryName + optional date range filters

        ### **Advanced Direct Query Operations**
        - **Custom Search**: Use q, query_by, filter_by, sort_by for complex queries
        - **Field Selection**: Use include_fields and exclude_fields for precise control
        - **Schema Info**: Use category: "lube_oil_reports" for schema details

        ## KEY FEATURES
        ✅ **STRUCTURED PARAMETERS**: Separate fields for query, filter, and sort operations
        ✅ **FIELD VALIDATION**: Only accepts fields from the documented schema below
        ✅ **FLEXIBLE SEARCH**: Supports full-text search across indexed fields
        ✅ **DATE FILTERING**: Supports date range filtering with yyyy-mm-dd format

        ## PARAMETER USAGE
        - **query_by**: Comma-separated field names for full-text search (e.g., "vesselName,machineryName,testLab")
        - **q**: Search query string for full-text search (e.g., "main engine castrol")
        - **filter_by**: Filtering conditions using Typesense syntax (e.g., "reportStatus:WARNING && dueStatus:OVERDUE")
        - **sort_by**: Field name with direction for sorting (e.g., "nextDue:asc,frequency:desc")
        - **page**: Page number for pagination (default: 1)
        - **per_page**: Results per page, up to 250 (default: 50)

        ## DATE HANDLING
        **IMPORTANT**: For date fields (sampleDate, nextDue), always use **yyyy-mm-dd** format in filter_by parameter.
        
        **Examples**:
        - ✅ CORRECT: "sampleDate:>=2024-01-01"
        - ✅ CORRECT: "nextDue:<=2024-12-31"
        - ❌ WRONG: "sampleDate:>=01-01-2024" (dd-mm-yyyy format)

        ## COMMON MISTAKES TO AVOID
        ❌ WRONG: Using non-existent fields
        ❌ WRONG: Incorrect date format (use yyyy-mm-dd for date filters, NOT dd-mm-yyyy)
        ❌ WRONG: Using SQL syntax instead of Typesense syntax for filters

        ## TYPESENSE DATABASE SCHEMA - LUBE OIL REPORTS TABLE
        The lube_oil_reports table contains comprehensive lube oil analysis data organized into the following categories:

        ### 1. VESSEL INFORMATION (2 fields)
        Information about the vessel associated with lube oil samples.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | imo | int64 | IMO number of the vessel only use for filter not in queryby argument |
        | vesselName | string | Name of the vessel |

        ### 2. MACHINERY INFORMATION (1 field)
        Information about the machinery for which the lube oil sample was taken.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | machineryName | string | Name of the machinery for which the lube oil analysis report is provided |

        ### 3. REPORT STATUS AND DATES (4 fields)
        Status and timing information for the lube oil analysis.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | reportStatus | string | Status shows if the oil analysis was found Satisfactory or not. Possible values: "SATISFACTORY", "WARNING" |
        | sampleDate | int64 | The date when the sample was landed |
        | nextDue | int64 | The date when the new sample has to be landed |
        | dueStatus | string | Status which indicates if nextDue date is in the future, close by or has already passed. Possible values: "IN ORDER", "DUE", "OVERDUE" |

        ### 4. SAMPLING INFORMATION (2 fields)
        Information about sampling frequency and testing laboratory.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | frequency | string | The intervals at which the Lube oil samples have to be taken and landed ashore for lab analysis |
        | testLab | string | The name of the lab or source from where the analysis report has been downloaded |

        ### 5. REPORT LINK (1 field)
        Link to the detailed lube oil analysis report.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | report | string | The url link to the lube oil analysis report |

        ## USAGE EXAMPLES

        **Basic Search Queries:**
        - universal_lube_oil_search(query_by="vesselName,machineryName", q="main engine", per_page=100)
        - universal_lube_oil_search(filter_by="reportStatus:WARNING", sort_by="nextDue:asc")

        **Advanced Filtering:**
        - universal_lube_oil_search(filter_by="imo:9000000 && dueStatus:OVERDUE", sort_by="nextDue:asc")
        - universal_lube_oil_search(filter_by="reportStatus:WARNING && dueStatus:OVERDUE", query_by="machineryName", q="*")

        **Date Range Filtering:**
        - universal_lube_oil_search(filter_by="sampleDate:>=2024-01-01 && sampleDate:<=2024-12-31")
        - universal_lube_oil_search(filter_by="nextDue:<2024-08-15 && reportStatus:WARNING")

        **Complex Queries:**
        - universal_lube_oil_search(query_by="machineryName,testLab", q="main engine castrol", filter_by="reportStatus:WARNING && dueStatus:OVERDUE", sort_by="nextDue:asc")

        **Simple Parameter Operations (replacing individual functions):**
        - universal_lube_oil_search(filter_by="imo:123456789 && dueStatus:OVERDUE") // list_overdue_lube_oil_samples
        - universal_lube_oil_search(filter_by="imo:123456789 && reportStatus:WARNING", query_by="machineryName", q="main engine") // machinery_with_warning_lube_oil_analysis
        - universal_lube_oil_search(filter_by="imo:123456789", query_by="machineryName", q="main engine", sort_by="sampleDate:desc") // get_latest_lube_oil_analysis_for_machinery
        - universal_lube_oil_search(filter_by="imo:123456789 && frequency:weekly") // list_lube_oil_samples_by_frequency
        - universal_lube_oil_search(filter_by="imo:123456789", query_by="machineryName", q="main engine") // fetch_lube_oil_analysis_with_link
        - universal_lube_oil_search(category="lube_oil_reports") // get_lube_report_table_schema

        **Advanced Direct Query (replacing lube_report_table_query):**
        - universal_lube_oil_search(q="main engine", query_by="machineryName", include_fields="imo,vesselName,machineryName,reportStatus")
        - universal_lube_oil_search(filter_by="imo:123456789 && reportStatus:WARNING", exclude_fields="embedding")
        - universal_lube_oil_search(collection="lube_oil_reports", query={q:"*", query_by:"machineryName", filter_by:"reportStatus:WARNING"})
        - universal_lube_oil_search(collection="lube_oil_reports", query={q:"castrol", query_by:"testLab", per_page:25})

        ## SECURITY NOTES
        - Results are filtered based on company restrictions
        - Queries have timeout limits
        - Maximum 250 results per page
        - All date filters must use yyyy-mm-dd format

        This tool enables advanced analytics, reporting, and data exploration for lube oil analysis operations.`,
        inputSchema: {
            type: "object",
            properties: {
                query_by: {
                    type: "string",
                    description: "Comma-separated list of field names to search in for full-text search. Only use string fields that are useful for text-based queries.",
                    enum: [
                        "vesselName",
                        "machineryName",
                        "reportStatus",
                        "frequency",
                        "dueStatus",
                        "testLab"
                    ]
                },
                q: {
                    type: "string",
                    description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'main engine' or 'castrol*'",
                    default: "*"
                },
                filter_by: {
                    type: "string",
                    description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'reportStatus:WARNING && dueStatus:OVERDUE'"
                },
                sort_by: {
                    type: "string",
                    description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'nextDue:asc,frequency:desc'",
                    default: "relevance"
                },
                page: {
                    type: "number",
                    description: "Page number for pagination. Default: 1",
                    minimum: 1,
                    default: 1
                },
                per_page: {
                    type: "number",
                    description: "Number of results per page. Maximum: 250, Default: 50",
                    minimum: 1,
                    maximum: 250,
                    default: 50
                }
            },
            required: [],
            additionalProperties: false
        }
    },
    // ============================================================================
    // INDIVIDUAL LUBE OIL TOOLS - REPLACED BY universal_lube_oil_search
    // ============================================================================
    // The following individual lube oil tools have been consolidated into the 
    // universal_lube_oil_search tool above. They are commented out but kept for 
    // reference and potential future use if needed.
    // ============================================================================
    // {
    //     name: "lube_report_table_query",
    //     description: "[FALLBACK TOOL] Searches planned maintenance system (PMS jobs, schedules, overhauls, components) and lube oil analysis reports (test labs, sample dates, machinery analysis status) databases. Use when other PMS/lube oil tools fail or for keyword searches across multiple fields. Always get the schema first using get_lube_report_table_schema tool. Example: Find test lab used for main engine oil analysis on <vessel>",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             collection: {
    //                 type: "string",
    //                 description: "Name of the collection to search",
    //                 enum: ["lube_oil_reports"]
    //             },
    //             query: {
    //                 type: "object",
    //                 description: "Query object to send to Typesense's search endpoint.",
    //                 properties: {
    //                     q: {
    //                         type: "string",
    //                         description: "Search string. Use '*' to match all records."
    //                     },
    //                     query_by: {
    //                         type: "string",
    //                         description: "Comma-separated list of fields to apply the `q` search on. Example: 'field1,field2'."
    //                     },
    //                     filter_by: {
    //                         type: "string",
    //                         description: "Filter expression using Typesense syntax. Use ':' for equality, '<'/'>' for ranges. Combine multiple conditions using '&&' or '||'. Example: 'imo:<imo_number> && type:<certificate_type> && daysToExpiry:<cutoff_timestamp>'"
    //                     },
    //                     include_fields: {
    //                         type: "string",
    //                         description: "Comma-separated list of fields to include in the results. Example: 'field1,field2,field3'."
    //                     },
    //                     per_page: {
    //                         type: "number",
    //                         description: "Number of results to return per page, defaults to 10"
    //                     }
    //                 },
    //                 required: ["q", "query_by"]
    //             }
    //         },
    //         required: ["collection", "query"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "list_overdue_lube_oil_samples",
    //     description: "Retrieve lube-oil analysis records whose next sample is **OVERDUE** for a vessel.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "string", description: "IMO number of the vessel."},
    //             machineryName: {type: "string", description: "Optional machinery name filter."},
    //             per_page: {type: "number", description: "Records per page (default 30)."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "machinery_with_warning_lube_oil_analysis",
    //     description: "Return all lube oil analysis reports for a vessel where `reportStatus` is **\"WARNING\"** (i.e., unsatisfactory results).",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "string", description: "IMO number of the vessel."},
    //             machineryName: {type: "string", description: "Optional machinery name filter."},
    //             per_page: {type: "number", description: "Records per page (default 30)."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "get_latest_lube_oil_analysis_for_machinery",
    //     description: "Fetch the most recent lube-oil analysis record for a specific machinery item on a vessel.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "string", description: "IMO number of the vessel."},
    //             machineryName: {type: "string", description: "Machinery name, e.g., \"MAIN ENGINE\"."},
    //             per_page: {type: "number", description: "Set to 10 (default) because only the newest record is required."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo", "machineryName"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "list_lube_oil_samples_by_frequency",
    //     description: "Return lube-oil analysis records for a vessel with a specific sampling `frequency`.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             imo: {type: "string", description: "IMO number of the vessel."},
    //             frequency: {type: "string", description: "Sampling frequency to filter, e.g., \"6 Months\"."},
    //             per_page: {type: "number", description: "Records per page (default 30)."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["imo", "frequency"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "fetch_lube_oil_analysis_with_link",
    //     description: "This tool retrieves the latest lube oil (LO) analysis report for a specified vessel using its IMO number and for a machinery if name is provided.",
    //     inputSchema: {
    //         type: "object",
    //         properties: {
    //             vesselName: {type: "string", description: "Name of the vessel (case-insensitive match on the vesselName field)."},
    //             machineryName: {type: "string", description: "Optional machinery name filter (e.g., \"MAIN ENGINE\")."},
    //             per_page: {type: "number", description: "Set to 10 (default) because only the newest report is needed."},
    //             session_id: {type: "string", description: "Session ID for tracking client sessions, if available"}
    //         },
    //         required: ["vesselName"],
    //         additionalProperties: false
    //     }
    // },
    // {
    //     name: "get_lube_report_table_schema",
    //     description: "This tool retrieves Typesense schema and instructions on how to query a typesense table for a specific category.",
    //     inputSchema: {
    //         type: "object",
    //