purchase-mcp-server/dist/tools/schema.js

Purchase and budget management server handling requisitions, purchase orders, expenses, budgets, and vendor management with ERP access for data extraction

export const universalPurchaseSearchToolSchema = {
    name: "universal_purchase_search",
    description: `Query the purchase database using structured parameters to retrieve and analyze purchase requisition and purchase order data from Typesense. This tool constructs search queries internally with predefined field validation for security and consistency.

    ## 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,prDescription,vendorOrSupplierName")
    - **q**: Search query string for full-text search (e.g., "engine parts")
    - **filter_by**: Filtering conditions using Typesense syntax (e.g., "purchaseRequisitionStatus:APPROVED && imo:>9000000")
    - **sort_by**: Field name with direction for sorting (e.g., "purchaseRequisitionDate:desc,invoiceAmount:asc")
    - **facet_by**: Fields for faceted search results (e.g., "purchaseRequisitionStatus,orderPriority")
    - **max_facet_values**: Maximum facet values to return (default: 10)
    - **page**: Page number for pagination (default: 1)
    - **per_page**: Results per page, up to 250 (default: 50)

    ## DATE HANDLING
    **IMPORTANT**: For date fields (date, purchaseRequisitionDate, purchaseOrderIssuedDate, orderReadinessDate), always use **yyyy-mm-dd** format in filter_by parameter.
    
    **Examples**:
    - ✅ CORRECT: "purchaseRequisitionDate:>=2024-01-01"
    - ✅ CORRECT: "orderReadinessDate:<=2024-12-31"
    - ❌ WRONG: "purchaseRequisitionDate:>=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 - PURCHASE TABLE
    The purchase table contains comprehensive purchase requisition and purchase order data with 50+ fields organized into the following categories:

    ### 1. VESSEL INFORMATION (3 fields)
    Information about the vessel associated with purchase requisitions and orders.

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

    ### 2. PURCHASE REQUISITION INFORMATION (8 fields)
    Core purchase requisition details and status.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | purchaseRequisitionDate | string | When filtering use yyyy-mm-dd format |
    | prDescription | string | Descriptive text field |
    | purchaseRequisitionStatus | string | Status of purchase requisition (PR). Values: DRAFT, APPROVED, SENT FOR QUOTE, AWAITING APPROVAL, QUOTED, PO APPROVED, PO GENERATED, ORDERED, CLOSED, CANCELLED, PARTIALLY RECEIVED, UNDER AMENDMENT |
    | purchaseRequisitionNumber | string | Purchase Requisition (PR) Number |
    | purchaseRequisitionLink | string | URL or hyperlink to supporting resource |
    | purchaseRequisitionType | string | Type of purchase requisition (PR). Values: ANTI-PIRACY ITEMS, CHARTS PUBLICATIONS, FLAG LOG BOOKS, FUEL ADDITIVES, GAS MEASUREMENT EQUIPMENTS, GASES WELDING, GENERAL STORES, LICENSE, LSA-FFA, LUBE OILS GREASES, MAINTENANCE CHEMICALS, PAINTS THINNERS, SYNERGY PPE KIT, PERSONNEL PROTECTION, SAFETY, SCRUBBER BWTS CHEMICALS, MARPOL SEALS, SERVICE, SPARE PARTS, PRINTED STATIONARY KITS, STORE, TANK/HOLD CLEANING CHEMICALS |
    | purchaseRequisitionSummary | string | Descriptive text field |
    | purchaseRequisitionDescription | string | What a particular purchase requisition (PR) is about |

    ### 3. PURCHASE ORDER INFORMATION (10 fields)
    Purchase order details, status, and tracking.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | poValue | string | Monetary value field |
    | purchaseOrderIssuedDate | string | When purchase order or PO was issued. When filtering use yyyy-mm-dd format |
    | purchaseOrderNumber | string | Unique identifier |
    | purchaseOrderLink | string | URL or hyperlink to supporting resource |
    | purchaseOrderStatus | string | Status of purchase order. Values: CLOSED, WITH FORWARDER, CANCELLED, ORDERED, AWAITING APPROVAL, UNDER AMENDMENT, APPROVED, DRAFT, REJECTED, QUOTED |
    | purchaseOrderAmount | float | Amount for which purchase order or PO is issued. Use > < = operators |
    | purchaseOrderStage | string | Whether a purchase order (PO) is open or close. Values: OPEN, CLOSE |
    | poCreatedBy | string | Name of an entity or person |
    | orderType | string | Type of order for a purchase order (PO). Values: OL, OF |
    | poStatusColor | string | UI color code for visual tagging |

    ### 4. VENDOR AND SUPPLIER INFORMATION (2 fields)
    Supplier and vendor details.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | vendorOrSupplierName | string | Name of the supplier who will be supplying that purchase order (PO) |
    | accountCode | string | Account code under which a particular requisition (PR) is raised |

    ### 5. INVOICE INFORMATION (7 fields)
    Invoice status, amounts, and approval details.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | invoiceStatus | string | Status of invoice for a Purchase order. Values: TRANSFERRED, WAITING, REJECTED, READYFORTRANSFER, NEW, ONHOLD, NOT RECEIVED |
    | invoiceValue | string | Monetary value field |
    | invoiceAmount | float | Amount paid as per the invoice for a purchase order or PO. Use > < = operators |
    | invoiceApproverName | string | Name of an entity or person |
    | invoiceStatusColor | string | UI color code for visual tagging |
    | scanID | int64 | Scan ID for an invoice |
    | scanIDLink | string | URL or hyperlink to supporting resource |

    ### 6. ORDER MANAGEMENT (6 fields)
    Order priority, readiness, and logistics information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | orderReadinessDate | string | Cutoff date for when purchase orders are expected to be ready with the vendor and can be shipped to vessel. This filter should be used along with two other filters as poStatus as ordered and poStage as open. Use a date comparison symbol to filter POs ready before, or after a specific date. When filtering use yyyy-mm-dd format |
    | orderReadinessColor | string | UI color code for visual tagging |
    | orderPriority | string | Priority of the purchase requisition or order. Values: DEFECT, ROUTINE MAINTENANCE STOCK, NORMAL, RECOMMENDED STOCK, URGENT, OTHERS, DRY DOCK, AUDIT |
    | forwarderName | string | PRs or POs which are with a particular logistic forwarder. Values: AQUARIUS, MARINE TRANS, ONE LOOP |
    | forwarderRemarks | string | Descriptive text field |
    | warehouseLocation | string | General purpose field |

    ### 7. QUOTATION AND CURRENCY (3 fields)
    Quotation and currency information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | qtcNo | string | Unique identifier |
    | qtcLink | string | URL or hyperlink to supporting resource |
    | currencyCode | string | Currency in which purchase order or invoice is issued. Values like USD, SGD etc |

    ### 8. CARGO AND SHIPPING (3 fields)
    Cargo type and shipping details.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | cargoType | string | Type of cargo for a purchase order (PO). Values: DG, NORMAL |
    | weight | int64 | Weight value (numeric) |
    | directPo | bool | Whether the purchase order is a Direct PO or not. Values: true, false |

    ### 9. STATUS FLAGS AND INDICATORS (6 fields)
    Boolean flags for various purchase states.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | poInvoiceDiscrepency | bool | Purchase order for which PO and invoice amount is not matching. Values: true, false |
    | isNewPurchaseRequisition | bool | Whether the purchase requisition (PR) raised is new or not. Values: true, false |
    | isPurchaseRequisitionNotOrdered | bool | Whether the purchase requisition (PR) is ordered or not. Values: true, false |
    | isPurchaseRequisitionSupplied | bool | Whether the purchase requisition (PR) has been supplied to vessel or not. Values: true, false |
    | isPurchaseOrderReady | bool | Whether the purchase order (PO) is ready to be shipped or not. Values: true, false |

    ### 10. UI AND VISUAL ELEMENTS (4 fields)
    Color codes and visual tagging for UI purposes.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | prStatusColor | string | UI color code for visual tagging |
    | prTypeColor | string | UI color code for visual tagging |
    | orderReadinessColor | string | UI color code for visual tagging |
    | poStatusColor | string | UI color code for visual tagging |

    ### 11. ADDITIONAL INFORMATION (6 fields)
    Miscellaneous fields and identifiers.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | prType | string | Type or category field |
    | purchaseOverviewUpdate | string | Descriptive text field |
    | docId | string | Unique identifier |
    | fleetManagerId | string | Unique identifier |
    | technicalSuperintendentId | string | Unique identifier |
    | ownerId | string[] | List of owner identifiers |

    ### 12. SYSTEM FIELD (1 field)
    System-generated identifier.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | _id | string | Internal document ID used for indexing and search |

    ## USAGE EXAMPLES

    **Basic Search Queries:**
    - universal_purchase_search(query_by="vesselName,prDescription", q="engine parts", per_page=100)
    - universal_purchase_search(filter_by="purchaseRequisitionStatus:APPROVED", sort_by="purchaseRequisitionDate:desc")

    **Advanced Filtering:**
    - universal_purchase_search(filter_by="imo:>9000000 && purchaseRequisitionStatus:APPROVED", sort_by="invoiceAmount:desc")
    - universal_purchase_search(filter_by="orderPriority:URGENT && purchaseOrderStage:OPEN", query_by="vesselName", q="*")

    **Date Range Filtering:**
    - universal_purchase_search(filter_by="purchaseRequisitionDate:>=2024-01-01 && purchaseRequisitionDate:<=2024-12-31")
    - universal_purchase_search(filter_by="orderReadinessDate:<2024-08-15 && purchaseOrderStatus:ORDERED && purchaseOrderStage:OPEN")

    **Faceted Search:**
    - universal_purchase_search(facet_by="purchaseRequisitionStatus,orderPriority", max_facet_values=20)
    - universal_purchase_search(query_by="prDescription", q="spare parts", facet_by="vesselName,currencyCode")

    **Complex Queries:**
    - universal_purchase_search(query_by="vendorOrSupplierName,prDescription", q="pump", filter_by="invoiceAmount:>1000 && currencyCode:USD", sort_by="invoiceAmount:desc", facet_by="purchaseRequisitionStatus")

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

    This tool enables advanced analytics, reporting, and data exploration for purchase 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",
                    "prDescription",
                    "purchaseRequisitionSummary",
                    "purchaseRequisitionDescription",
                    "vendorOrSupplierName",
                    "accountCode",
                    "purchaseRequisitionNumber",
                    "purchaseOrderNumber",
                    "purchaseRequisitionType",
                    "orderPriority",
                    "currencyCode",
                    "purchaseOrderStatus",
                    "purchaseRequisitionStatus",
                    "invoiceStatus",
                    "poCreatedBy",
                    "orderType",
                    "invoiceApproverName",
                    "qtcNo",
                    "forwarderName",
                    "forwarderRemarks",
                    "warehouseLocation",
                    "cargoType",
                    "purchaseOverviewUpdate"
                ]
            },
            q: {
                type: "string",
                description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'engine parts' or 'pump*'",
                default: "*"
            },
            filter_by: {
                type: "string",
                description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'purchaseRequisitionStatus:APPROVED && imo:>9000000'"
            },
            sort_by: {
                type: "string",
                description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'purchaseRequisitionDate:desc,invoiceAmount:asc'",
                default: "relevance"
            },
            facet_by: {
                type: "string",
                description: "Comma-separated list of fields to generate faceted results for. Example: 'purchaseRequisitionStatus,orderPriority,vesselName'"
            },
            max_facet_values: {
                type: "number",
                description: "Maximum number of facet values to return for each facet field. Default: 10, Maximum: 100",
                minimum: 1,
                maximum: 100,
                default: 10
            },
            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
    }
};
export const universalBudgetSearchToolSchema = {
    name: "universal_budget_search",
    description: `Query the budget database using structured parameters to retrieve and analyze vessel budget and expense data from Typesense. This tool constructs search queries internally with predefined field validation for security and consistency.

    ## 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,category")
    - **q**: Search query string for full-text search (e.g., "crew wages")
    - **filter_by**: Filtering conditions using Typesense syntax (e.g., "group:OPEX && period:Current")
    - **sort_by**: Field name with direction for sorting (e.g., "budgetAmount:desc,date:asc")
    - **facet_by**: Fields for faceted search results (e.g., "category,group,period")
    - **max_facet_values**: Maximum facet values to return (default: 10)
    - **page**: Page number for pagination (default: 1)
    - **per_page**: Results per page, up to 250 (default: 50)

    ## DATE HANDLING
    **IMPORTANT**: For date field, always use **yyyy-mm-dd** format in filter_by parameter.
    
    **Examples**:
    - ✅ CORRECT: "date:>=2024-01-01"
    - ✅ CORRECT: "date:<=2024-12-31"
    - ❌ WRONG: "date:>=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 - BUDGET TABLE
    The budget table contains comprehensive vessel budget and expense data with 8 fields organized into the following categories:

    ### 1. VESSEL INFORMATION (2 fields)
    Information about the vessel associated with budget and expense data.

    | 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. BUDGET CATEGORIZATION (3 fields)
    Budget classification and grouping information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | category | string | Budget category of vessel. Values: CREW WAGES, CREW EXPENSES, VICTUALLING EXPENSES, STORES, SPARES, LUBE OIL CONSUMPTION, REPAIRS & MAINTENANCE, MANAGEMENT FEES, MISCELLANEOUS, ADMINISTRATIVE EXPENSES, INSURANCE, DRYDOCKING EXPENSES, NON-BUDGETED EXPENSES, P&I/H&M EXPENSES, VOYAGE/CHARTERERS EXPENSES, CAPITAL EXPENDITURE, EXTRA ORDINARY ITEMS, VESSEL UPGRADING COSTS, LAY-UP COSTS, PRE-DELIVERY EXPENSES |
    | group | string | Group of the budget category. OPEX=Operating Expenses, NB=Non-Budgeted, PD=Pre-Delivery, DD=Dry-Docking. Values: OPEX, NB, PD, DD |
    | period | string | Period of the budget category. Previous=previous period, Current=current period. Values: Previous, Current |

    ### 3. FINANCIAL DATA (3 fields)
    Budget amounts, expenses, and date information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | budgetAmount | number | Budget amount of the budget category of vessel |
    | expenseAmount | number | Expense amount of the budget category of vessel |
    | date | string | Date of the budget&expense category of vessel. When filtering use yyyy-mm-dd format |

    ## USAGE EXAMPLES

    **Basic Search Queries:**
    - universal_budget_search(query_by="vesselName,category", q="crew wages", per_page=100)
    - universal_budget_search(filter_by="group:OPEX", sort_by="budgetAmount:desc")

    **Advanced Filtering:**
    - universal_budget_search(filter_by="imo:>9000000 && period:Current", sort_by="expenseAmount:desc")
    - universal_budget_search(filter_by="category:SPARES && group:OPEX", query_by="vesselName", q="*")

    **Date Range Filtering:**
    - universal_budget_search(filter_by="date:>=2024-01-01 && date:<=2024-12-31")
    - universal_budget_search(filter_by="date:>2024-06-01 && budgetAmount:>50000")

    **Amount Range Filtering:**
    - universal_budget_search(filter_by="budgetAmount:>100000", sort_by="budgetAmount:desc")
    - universal_budget_search(filter_by="expenseAmount:>=10000 && expenseAmount:<=50000")

    **Faceted Search:**
    - universal_budget_search(facet_by="category,group,period", max_facet_values=20)
    - universal_budget_search(query_by="vesselName", q="maintenance", facet_by="category,group")

    **Complex Queries:**
    - universal_budget_search(query_by="vesselName", q="engine", filter_by="group:OPEX && budgetAmount:>25000", sort_by="date:desc", facet_by="category")

    ## 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 budget 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",
                    "category",
                    "group",
                    "period"
                ]
            },
            q: {
                type: "string",
                description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'crew wages' or 'maintenance*'",
                default: "*"
            },
            filter_by: {
                type: "string",
                description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'group:OPEX && period:Current'"
            },
            sort_by: {
                type: "string",
                description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'budgetAmount:desc,date:asc'",
                default: "relevance"
            },
            facet_by: {
                type: "string",
                description: "Comma-separated list of fields to generate faceted results for. Example: 'category,group,period'"
            },
            max_facet_values: {
                type: "number",
                description: "Maximum number of facet values to return for each facet field. Default: 10, Maximum: 100",
                minimum: 1,
                maximum: 100,
                default: 10
            },
            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
    }
};
export const universalExpenseSearchToolSchema = {
    name: "universal_expense_search",
    description: `Query the expense database using structured parameters to retrieve and analyze vessel expense and cost tracking data from Typesense. This tool constructs search queries internally with predefined field validation for security and consistency.

    ## 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,accountDescription")
    - **q**: Search query string for full-text search (e.g., "maintenance repairs")
    - **filter_by**: Filtering conditions using Typesense syntax (e.g., "group:OPEX && expenseCategory:ACTUAL EXPENSES")
    - **sort_by**: Field name with direction for sorting (e.g., "expenseDate:desc,expenseAmount:asc")
    - **facet_by**: Fields for faceted search results (e.g., "group,category,expenseCategory")
    - **max_facet_values**: Maximum facet values to return (default: 10)
    - **page**: Page number for pagination (default: 1)
    - **per_page**: Results per page, up to 250 (default: 50)

    ## DATE HANDLING
    **IMPORTANT**: For expenseDate field, always use **yyyy-mm-dd** format in filter_by parameter.
    
    **Examples**:
    - ✅ CORRECT: "expenseDate:>=2024-01-01"
    - ✅ CORRECT: "expenseDate:<=2024-12-31"
    - ❌ WRONG: "expenseDate:>=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 - EXPENSE TABLE
    The expense table contains comprehensive vessel expense and cost tracking data with 10 fields organized into the following categories:

    ### 1. VESSEL INFORMATION (2 fields)
    Information about the vessel associated with expense data.

    | 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. EXPENSE CLASSIFICATION (3 fields)
    Expense grouping and categorization information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | group | string | Broad expense classification (use only when user explicitly specifies). Values: OPEX, NON BUDGET, DRY DOCKING, PRE DELIVERY |
    | category | string | Expense sub-category within the chosen group. Values: ADMINISTRATIVE EXPENSES, CAPITAL EXPENDITURE, CREW EXPENSES, CREW WAGES, DRYDOCKING EXPENSES, EXTRA ORDINARY ITEMS, INSURANCE, LAY-UP COSTS, LUBE OIL CONSUMPTION, MANAGEMENT FEES, MISCELLANEOUS, NON-BUDGETED EXPENSES, PI/HM EXPENSES, PRE-DELIVERY EXPENSES, REPAIRS MAINTENANCE, SPARES, STORES, VESSEL UPGRADING COSTS, VICTUALLING EXPENSES, VOYAGE/CHARTERERS EXPENSES |
    | expenseCategory | string | Classification indicating whether the record is an actual expense or a committed cost. Unless the user specifically asks for committed cost, assume ACTUAL EXPENSES. Values: ACTUAL EXPENSES, COMMITTED COST |

    ### 3. ACCOUNT INFORMATION (2 fields)
    Account details and descriptions.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | accountNo | string | Unique account number where the expense is recorded |
    | accountDescription | string | Detailed description of the expense within its category (a finer sub-category) |

    ### 4. FINANCIAL DATA (3 fields)
    Expense amounts, PO amounts, and date information.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | expenseDate | string | Date the expense was incurred. When filtering use yyyy-mm-dd format |
    | expenseAmount | number | Actual amount incurred for a purchase order (PO). Use > < = operators |
    | poAmount | number | Amount committed for a PO but not yet incurred. Use > < = operators |

    ## USAGE EXAMPLES

    **Basic Search Queries:**
    - universal_expense_search(query_by="vesselName,accountDescription", q="maintenance repairs", per_page=100)
    - universal_expense_search(filter_by="group:OPEX", sort_by="expenseAmount:desc")

    **Advanced Filtering:**
    - universal_expense_search(filter_by="imo:>9000000 && expenseCategory:ACTUAL EXPENSES", sort_by="expenseDate:desc")
    - universal_expense_search(filter_by="category:SPARES && group:OPEX", query_by="accountDescription", q="*")

    **Date Range Filtering:**
    - universal_expense_search(filter_by="expenseDate:>=2024-01-01 && expenseDate:<=2024-12-31")
    - universal_expense_search(filter_by="expenseDate:>2024-06-01 && expenseAmount:>10000")

    **Amount Range Filtering:**
    - universal_expense_search(filter_by="expenseAmount:>50000", sort_by="expenseAmount:desc")
    - universal_expense_search(filter_by="poAmount:>=5000 && poAmount:<=25000")

    **Category-Specific Queries:**
    - universal_expense_search(filter_by="expenseCategory:COMMITTED COST", sort_by="poAmount:desc")
    - universal_expense_search(filter_by="category:CREW WAGES && expenseCategory:ACTUAL EXPENSES")

    **Faceted Search:**
    - universal_expense_search(facet_by="group,category,expenseCategory", max_facet_values=20)
    - universal_expense_search(query_by="accountDescription", q="engine", facet_by="group,category")

    **Complex Queries:**
    - universal_expense_search(query_by="vesselName,accountDescription", q="maintenance", filter_by="group:OPEX && expenseAmount:>15000", sort_by="expenseDate:desc", facet_by="category")

    ## 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 expense 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",
                    "group",
                    "category",
                    "accountNo",
                    "accountDescription",
                    "expenseCategory"
                ]
            },
            q: {
                type: "string",
                description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'maintenance repairs' or '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: 'group:OPEX && expenseCategory:ACTUAL EXPENSES'"
            },
            sort_by: {
                type: "string",
                description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'expenseDate:desc,expenseAmount:asc'",
                default: "relevance"
            },
            facet_by: {
                type: "string",
                description: "Comma-separated list of fields to generate faceted results for. Example: 'group,category,expenseCategory'"
            },
            max_facet_values: {
                type: "number",
                description: "Maximum number of facet values to return for each facet field. Default: 10, Maximum: 100",
                minimum: 1,
                maximum: 100,
                default: 10
            },
            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
    }
};
export const listOverdueOpenRequisitionsToolSchema = {
    name: "list_overdue_open_requisitions",
    description: "Retrieves purchase-requisition records that remain in OPEN stage and were raised more than X days ago for a specified vessel from the purchase table in the Typesense collection.",
    inputSchema: {
        type: "object",
        required: ["imo", "daysOverdue", "stage"],
        properties: {
            imo: {
                type: "string",
                description: "The IMO number or name of the vessel."
            },
            daysOverdue: {
                type: "number",
                minimum: 1,
                maximum: 1000,
                description: "Number of days before today to use as cutoff date."
            },
            stage: {
                type: "string",
                description: "Stage to filter by (OPEN or CLOSE).",
                enum: ["OPEN", "CLOSE"]
            },
            per_page: {
                type: "number",
                description: "Number of requisitions to return per page (default is 250)."
            }
        },
        additionalProperties: false
    }
};
export const getMonthlyOpexBudgetVarianceToolSchema = {
    name: "get_monthly_opex_budget_variance",
    description: "Use this tool to get the Monthly OPEX Budget Variance Analysis for a vessel's operating expenses against the budget, highlighting categories with overspending and the top five cost contributors in each. It offers a clear snapshot of where and why variances occur, helping managers control costs effectively",
    inputSchema: {
        type: "object",
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            },
            session_id: {
                type: "string",
                description: "Optional session ID for tracking client sessions."
            }
        },
        required: ["imo"]
    }
};
export const getCurrentYearCommittedCostToolSchema = {
    name: "get_current_year_committed_cost",
    description: "Use this tool to get details of committed costs, showing their overall value and percentage against the year-to-date OPEX budget. This also gives a breakdown of committed costs carried over from last month and those newly booked in the current month",
    inputSchema: {
        type: "object",
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            }
        },
        required: ["imo"]
    }
};
export const getBudgetStatusSummaryYtdToolSchema = {
    name: "get_budget_status_summary_ytd",
    description: "Use this tool ,for present year till date ,to summarize OPEX variance in dollar and percentage terms, note daily OPEX against the budget, and review fund status for the year, including deficits. It highlights key overspending areas, non-budgeted expenses, and committed costs, including carryovers.",
    inputSchema: {
        type: "object",
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            }
        },
        required: ["imo"]
    }
};
export const getPurchaseOrdersWithForwardersToolSchema = {
    name: "get_purchase_orders_with_forwarders",
    description: "Use this tool to get list of purchase orders (POs)/Spares/Items available with forwarders and ready for connection onboard the vessel",
    inputSchema: {
        type: "object",
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            }
        },
        required: ["imo"]
    }
};
export const purchaseOrdersOpenMoreThan180DaysToolSchema = {
    name: "purchase_orders_open_more_than_180_days",
    description: "Retrieves purchase orders that have been open for more than 180 days for a specific vessel.",
    inputSchema: {
        type: "object",
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            }
        },
        required: ["imo"]
    }
};
export const getVesselPurchaseLogTableToolSchema = {
    name: "get_vessel_purchase_log_table",
    description: "Use this tool to get the list of purchase requisitions table for a vessel from the purchase typesense collection .Returns purchase-requisition records that were created for a specified vessel from the purchase table in the typesense collection. Example question :  Get the PR log table for VESSEL_NAME ",
    inputSchema: {
        type: "object",
        required: ["imo"],
        properties: {
            imo: {
                type: "string",
                description: "IMO number of the vessel"
            },
            per_page: {
                type: "number",
                description: "Number of requisitions to return in a typesense query (maximum limit for a query is  100)"
            }
        },
        additionalProperties: false
    }
};
export const getPurchaseRequisitionDetailsToolSchema = {
    name: "get_purchase_requisition_details",
    description: "Returns purchase-requisition details that match a specific purchase requisition number from the purchase collection in Typesense.",
    inputSchema: {
        type: "object",
        required: ["purchaseRequisitionNumber"],
        properties: {
            purchaseRequisitionNumber: {
                type: "string",
                description: "Exact purchase-requisition number to retrieve."
            },
            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
    }
};
export const getPurchaseOrderDetailsToolSchema = {
    name: "get_purchase_order_details",
    description: "Get detailed information about a specific purchase order",
    inputSchema: {
        type: "object",
        required: ["orderId"],
        properties: {
            orderId: {
                type: "string",
                description: "The ID of the purchase order to retrieve"
            }
        }
    }
};
export const listRequisitionsByStatusToolSchema = {
    name: "list_requisitions_by_status",
    description: "List purchase requisitions filtered by status",
    inputSchema: {
        type: "object",
        required: ["imo", "status"],
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            },
            status: {
                type: "string",
                description: "The status to filter requisitions by",
                enum: ["DRAFT", "APPROVED", "SENT FOR QUOTE", "AWAITING APPROVAL", "QUOTED", "PO APPROVED", "PO GENERATED", "ORDERED", "CLOSED", "CANCELLED", "PARTIALLY RECEIVED", "UNDER AMENDMENT"]
            },
            limit: {
                type: "number",
                description: "Maximum number of requisitions to return",
                default: 10
            }
        }
    }
};
export const listPurchaseOrdersByStatusToolSchema = {
    name: "list_purchase_orders_by_status",
    description: "List purchase orders filtered by status",
    inputSchema: {
        type: "object",
        required: ["status"],
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            },
            status: {
                type: "string",
                description: "The status to filter orders by",
                enum: ["CLOSED", "WITH FORWARDER", "CANCELLED", "ORDERED", "AWAITING APPROVAL", "UNDER AMENDMENT", "APPROVED", "DRAFT", "REJECTED", "QUOTED"]
            },
            limit: {
                type: "number",
                description: "Maximum number of orders to return",
                default: 10
            }
        }
    }
};
export const listRequisitionsByTypeAndStageToolSchema = {
    name: "list_requisitions_by_type_and_stage",
    description: "List purchase requisitions filtered by type and stage",
    inputSchema: {
        type: "object",
        required: ["type", "stage"],
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            },
            type: {
                type: "string",
                description: "The type of requisition",
                enum: ["ANTI-PIRACY ITEMS", "CHARTS PUBLICATIONS", "FLAG LOG BOOKS", "FUEL ADDITIVES", "GAS MEASUREMENT EQUIPMENTS", "GASES WELDING", "GENERAL STORES", "LICENSE", "LSA-FFA", "LUBE OILS GREASES", "MAINTENANCE CHEMICALS", "PAINTS THINNERS", "SYNERGY PPE KIT", "PERSONNEL PROTECTION", "SAFETY", "SCRUBBER BWTS CHEMICALS", "MARPOL SEALS", "SERVICE", "SPARE PARTS", "PRINTED STATIONARY KITS", "STORE", "TANK/HOLD CLEANING CHEMICALS"]
            },
            stage: {
                type: "string",
                description: "The stage of the requisition",
                enum: ["OPEN", "CLOSE"]
            },
            limit: {
                type: "number",
                description: "Maximum number of requisitions to return",
                default: 10
            }
        }
    }
};
export const listRecentRequisitionsByOrderPriorityToolSchema = {
    name: "list_recent_requisitions_by_order_priority",
    description: "List recent purchase requisitions filtered by priority",
    inputSchema: {
        type: "object",
        required: ["priority"],
        properties: {
            imo: {
                type: "string",
                description: "The IMO number of the vessel."
            },
            priority: {
                type: "string",
                description: "The priority level to filter by",
                enum: ["DEFECT", "ROUTINE MAINTENANCE STOCK", "NORMAL", "RECOMMENDED STOCK", "URGENT", "OTHERS", "DRY DOCK", "AUDIT"]
            },
            daysAgo: {
                type: "number",
                minimum: 1,
                maximum: 1000,
                description: "Number of days to look back for requisitions."
            },
            limit: {
                type: "number",
                description: "Maximum number of requisitions to return",
                default: 10
            }
        }
    }
};
export const listTopExpensesByCategoryToolSchema = {
    name: "list_top_expenses_by_category",
    description: "Return a vessel's **highest-value expense records** (expenseCategory = \"ACTUAL EXPENSES\") so the user can pick the top *N* items in **each budget category**.\n\nHow it works\n1. Always filter on `imo = <IMO>` and `expenseCategory = \"ACTUAL EXPENSES\"`.\n2. Sort the result set by `expenseAmount:desc` so the costliest items appear first.\n3. The tool can optionally narrow the search by a `group` (OPEX, NON BUDGET, DRY DOCKING, PRE DELIVERY) or by an ISO `dateFrom/dateTo` window on `expenseDate`.\n4. The caller sets `topN` (default **5**).  Because Typesense does not group-limit natively, the LLM should:\n   • Call this tool with a sufficiently large `per_page` (e.g. 100).\n   • Post-process the returned list, taking the first *N* rows **per unique category**.\n\nExample use-case: \"Give me the top 5 expenses for each category for VESSEL_NAME.\" → call with `{ imo:\"IMO_NUMBER\", topN:5 }`, then slice the response per category on the LLM side.",
    inputSchema: {
        type: "object",
        required: ["imo"],
        properties: {
            imo: {
                type: "string",
                description: "IMO number of the vessel."
            },
            topN: {
                type: "number",
                description: "How many of the largest expenses to return per category (default 5)."
            },
            group: {
                type: "string",
                enum: ["OPEX", "NON BUDGET", "DRY DOCKING", "PRE DELIVERY"],
                description: "Optional high-level group filter (use only if the user asks for it)."
            },
            dateFrom: {
                type: "string",
                description: "Optional earliest expenseDate (inclusive) in YYYY-MM-DD format."
            },
            dateTo: {
                type: "string",
                description: "Optional latest expenseDate (inclusive) in YYYY-MM-DD format."
            },
            per_page: {
                type: "number",
                description: "Number of records to fetch (default 100).  Use a value large enough to cover topN items for every category."
            }
        },
        additionalProperties: false
    }
};
export const listCommittedCostExpensesToolSchema = {
    name: "list_committed_cost_expenses",
    description: "Retrieve expense records for a vessel that are classified as **\"COMMITTED COST\"** (i.e., the amount has been reserved on a purchase order but not yet spent).\n\nHow to use it\n1. Supply the vessel's IMO number.\n2. The tool automatically applies the filter `expenseCategory=COMMITTED COST`.\n3. Optional filters:\n   • `group` – one of OPEX, NON BUDGET, DRY DOCKING, PRE DELIVERY.\n   • `category` – any budget sub-category in the enum list below (SPARES, STORES, etc.).\n   • `dateFrom` and `dateTo` – ISO dates (`YYYY-MM-DD`) to restrict the `expenseDate` range.\n4. The query sent to the *expense* collection looks like\n   `imo=[IMO] AND expenseCategory:\"COMMITTED COST\"` plus any optional filters.\n5. Results include `group`, `category`, `accountNo`, `accountDescription`, `expenseDate`, `poAmount`, and other PO metadata.",
    inputSchema: {
        type: "object",
        required: ["imo"],
        properties: {
            imo: {
                type: "string",
                description: "IMO number of the vessel."
            },
            group: {
                type: "string",
                enum: ["OPEX", "NON BUDGET", "DRY DOCKING", "PRE DELIVERY"],
                description: "Optional broad expense group (use only if the user specifies it)."
            },
            category: {
                type: "string",
                enum: [
                    "ADMINISTRATIVE EXPENSES",
                    "CAPITAL EXPENDITURE",
                    "CREW EXPENSES",
                    "CREW WAGES",
                    "DRYDOCKING EXPENSES",
                    "EXTRA ORDINARY ITEMS",
                    "INSURANCE",
                    "LAY-UP COSTS",
                    "LUBE OIL CONSUMPTION",
                    "MANAGEMENT FEES",
                    "MISCELLANEOUS",
                    "NON-BUDGETED EXPENSES",
                    "PI/HM EXPENSES",
                    "PRE-DELIVERY EXPENSES",
                    "REPAIRS MAINTENANCE",
                    "SPARES",
                    "STORES",
                    "VESSEL UPGRADING COSTS",
                    "VICTUALLING EXPENSES",
                    "VOYAGE/CHARTERERS EXPENSES"
                ],
                description: "Optional sub-category filter; omit to include all categories."
            },
            dateFrom: {
                type: "string",
                description: "Optional earliest expenseDate (inclusive) in YYYY-MM-DD format."
            },
            dateTo: {
                type: "string",
                description: "Optional latest expenseDate (inclusive) in YYYY-MM-DD format."
            },
            per_page: {
                type: "number",
                description: "Number of records per page (default 50)."
            }
        },
        additionalProperties: false
    }
};
export const listRecentUrgentRequisitionsToolSchema = {
    name: "list_recent_urgent_requisitions",
    description: "Returns purchase-requisition records whose `orderPriority` is **\"URGENT\"** and whose `purchaseRequisitionDate` falls within the last *N* days for a specified vessel.",
    inputSchema: {
        type: "object",
        required: ["imo", "daysAgo"],
        properties: {
            imo: {
                type: "string",
                "description": "IMO number of the vessel."
            },
            daysAgo: {
                type: "number",
                minimum: 1,
                maximum: 1000,
                description: "How many days back to look for urgent requisitions."
            },
            per_page: {
                type: "number",
                "description": "Number of requisitions to return per page (default 50)."
            }
        },
        additionalProperties: false
    }
};
export const getVesselBudgetDataToolSchema = {
    name: "get_vessel_budget_data",
    description: "Returns budget figures for a specified vessel from the budget table collection in Typesense, with optional filters for budget category, group, period, and a custom date range.",
    inputSchema: {
        type: "object",
        required: ["imo"],
        properties: {
            imo: {
                type: "string",
                description: "IMO number of the vessel."
            },
            category: {
                type: "string",
                enum: [
                    "CREW WAGES", "CREW EXPENSES", "VICTUALLING EXPENSES", "STORES", "SPARES", "LUBE OIL CONSUMPTION", "REPAIRS & MAINTENANCE", "MANAGEMENT FEES", "MISCELLANEOUS", "ADMINISTRATIVE EXPENSES", "INSURANCE", "DRYDOCKING EXPENSES", "NON-BUDGETED EXPENSES", "P&I/H&M EXPENSES", "VOYAGE/CHARTERERS EXPENSES", "CAPITAL EXPENDITURE", "EXTRA ORDINARY ITEMS", "VESSEL UPGRADING COSTS", "LAY-UP COSTS", "PRE-DELIVERY EXPENSES"
                ],
                description: "Budget category to filter (omit to return all categories)."
            },
            group: {
                type: "string",
                enum: ["OPEX", "NB", "PD", "DD"],
                description: "Category group to filter (OPEX, NB, PD, DD)."
            },
            period: {
                type: "string",
                enum: ["PREVIOUS YEAR", "CURRENT YEAR"],
                description: "Reporting period to filter (omit for all periods)."
            },
            dateFrom: {
                type: "string",
                description: "Start date for the date range in YYYY-MM-DD format."
            },
            dateTo: {
                type: "string",
                description: "End date for the date range in YYYY-MM-DD format."
            },
            per_page: {
                type: "number",
                description: "Number of records to return per page (default is 250)."
            }
        },
        additionalProper