handle_aims360_request
ChatGPTFetch live AIMS360 data. Supports two domains — set domainKey accordingly: - domainKey='orders' (default): order queries — overdue orders, past due, no allocation, no WIP, unallocated, top customers, sales by channel, order lookup, grouped order summaries, charts, exports. - domainKey='invoices': invoice queries — open invoices, overdue invoices, outstanding balance, invoice margin, margin by style, invoice line items, billing, accounts receivable, AR balance. RULE: Any user question containing 'invoice', 'invoices', 'billing', 'margin', 'AR', 'accounts receivable', 'outstanding balance', 'balance due', or 'amount due' → use domainKey='invoices'. Do not say you lack access to AIMS360 data when this tool is available. For 'all orders'/'show orders' use domainKey='orders'; for 'all invoices'/'show invoices' use domainKey='invoices'. Always pass the user's original wording in userQuery. The server uses userQuery as a safety net to resolve business synonyms and correct weak structured intent before validation. List/table/details/rows requests must use outputMode='table' so the MCP widget opens. Do not render Markdown tables yourself for AIMS360 row lists. All/full/list all/every matching order means limit=null. Only set limit when the user explicitly asks for top N, first N, last N, sample N, or limit N. Build structured intent and call this tool. The server validates, expands named business patterns, generates OData, and executes against AIMS360. For ambiguous field names, unknown columns, business-definition questions, or complex grouping/filtering requests, call retrieve_aims360_metadata first and use that retrieved context to build this tool's structured input. RULE: If the user's phrasing is ambiguous or uses business synonyms not in the examples below, call retrieve_aims360_metadata first and use the returned patternHints to set basePattern and queryKind. Never guess business-pattern mappings. FOLLOW-UP QUERIES: When the user refines a previous query (e.g. 'group those by completed date as a chart' after 'show overdue orders'), carry forward basePattern and filters from the prior turn. The server re-expands basePattern on every call. NAMED PATTERNS - use basePattern instead of replicating canonical filters yourself: - 'overdue orders' -> basePattern='overdue' (do NOT also send statuses or completeBefore) - 'no allocation orders' -> basePattern='no_allocation' - ad-hoc queries -> basePattern=null and populate filters - If the user asks for a contradictory named pattern, still send the named basePattern plus the user-supplied conflicting filter so the server can reject it. Example: 'overdue canceled orders' -> basePattern='overdue' and filters.statuses=['Canceled']. SUPPORTED DIMENSIONS: order_source=order source, customer=customer, status=status, ship_to_state=state, division=division, season=season, sales_rep=sales rep, term=payment terms, ship_via=shipping method, buyer=buyer, vendor=vendor, entered_date=entered date, complete_date=complete date, start_date=start date, style=Style, color=Color, style_color=Style/Color, customer=Customer, invoice_status=Invoice Status, order_source=Order Source, shopify_store=Shopify Store, division=Division, season=Season, sales_rep=Sales Rep, bill_to_state=Bill-to State, ship_to_state=Ship-to State, term=Payment Term, ship_via=Carrier, invoice_date=Invoice Date, due_date=Due Date, style_color=Style + Color (style, color, style_color are line-item level — use with queryKind='line_items') SUPPORTED METRICS: Orders: booked_amount=Booked Amount, order_count=Order count, booked_qty=Booked Total; Invoices: total_amount=Total Amount, merchandise=Merchandise, balance=Balance, invoice_count=Invoice Count SUPPORTED BASE PATTERNS: Orders: overdue=Overdue orders — Open/Hold where completion date has passed, no_allocation=No allocation — Open/Hold orders with zero stock and zero WIP allocation; Invoices: overdue=Overdue invoices — Open invoices where dueDate has passed, outstanding_balance=Outstanding balance — Open invoices with a remaining balance SUPPORTED EXPANDS: lineItems, sizes, allocations STATUS VALUES: Canceled, Hold, Complete, Open EXAMPLES: - 'show overdue orders' -> queryKind='raw_list', basePattern='overdue', outputMode='summary', filters all null - 'show overdue orders as a table' -> queryKind='raw_list', basePattern='overdue', outputMode='table', filters all null - 'give me list of all over due orders' -> userQuery=original text, queryKind='raw_list', basePattern='overdue', outputMode='table', limit=null, filters all null - 'show all orders' / 'fetch all orders' -> queryKind='raw_list', basePattern=null, outputMode='summary', filters all null - 'what orders have come in that have no stock allocation and no production allocation?' -> userQuery=original text, queryKind='raw_list', basePattern='no_allocation', outputMode='summary', filters all null. Do not answer that API access is unavailable. - 'orders with no WIP' / 'unallocated orders' / 'orders with no stock' -> userQuery=original text, queryKind='raw_list', basePattern='no_allocation', outputMode='summary' - 'show me those 6 orders' after a summary with 6 rows -> re-call this tool with the same prior intent and outputMode='table' - 'booked quantity by order source' -> queryKind='grouped_summary', dimensionKey='order_source', metricKey='booked_qty', outputMode='summary' - 'breakdown Shopify orders this month by customer' -> queryKind='grouped_summary', dimensionKey='customer', metricKey='booked_qty' or 'booked_amount', filters.orderSource='Shopify', filters.dateRange resolved - 'breakdown Shopify orders this month' with no breakdown dimension -> ask what to break down by, unless prior context clearly supplies the dimension - 'latest entered orders' -> queryKind='raw_list', sortSpec={fieldKey:'entered', direction:'desc'} - 'show overdue orders with sales rep and freight' -> basePattern='overdue', selectFields=['salesRep1Code','salesRep1Name','freightAmount'] - 'orders where freight amount is greater than 100' -> fieldFilters=[{fieldKey:'freightAmount', operator:'gt', value:100}] - 'group those by completed date' after overdue results -> queryKind='grouped_summary', basePattern='overdue', dimensionKey='complete_date', metricKey='order_count', outputMode='summary' - 'group these by date' after overdue results -> same as completed date: use dimensionKey='complete_date' because overdue is defined by the complete field - 'group these by month' after overdue/date results -> same date dimension as context, set timeGrain='month'. Do not present individual dates as months. - 'can I get a nice view for this?' after a grouped result -> re-call this tool, carry forward all prior params, set outputMode='chart' - 'show this visually' or 'open a visual view' after a grouped result -> re-call this tool, carry forward all prior params, set outputMode='chart' - 'can i get a bar graph / line chart / donut for this?' after any result -> re-call this tool, carry forward all prior params, set outputMode='chart' and set chartType to the requested type - 'open this as a table/widget' after any result -> re-call this tool, carry forward the same intent, set outputMode='table' - 'order by date in desc order' after a grouped date result -> carry forward the same grouped intent and set sortSpec={fieldKey:'complete', direction:'desc'} - 'show no allocation orders' -> queryKind='raw_list', basePattern='no_allocation', outputMode='summary', filters all null - 'group those no allocation orders by customer' -> queryKind='grouped_summary', basePattern='no_allocation', dimensionKey='customer', metricKey='booked_amount', outputMode='summary' - 'orders completing this month' -> queryKind='raw_list', basePattern=null, filters.dateRange={field:'complete', start:'YYYY-MM-DD', end:'YYYY-MM-DD'} - 'show line items for order 102025' -> queryKind='line_items', filters.orderNumber='102025', outputMode='table' - 'show all open line items this month' -> queryKind='line_items', filters.dateRange resolved, outputMode='table' - 'booked quantity by style this month' -> queryKind='line_items', dimensionKey='style', metricKey='booked_qty', filters.dateRange resolved, outputMode='summary' - 'which styles have the most open units?' -> queryKind='line_items', dimensionKey='style', outputMode='summary' - 'group line items by style and color' -> queryKind='line_items', dimensionKey='style_color', outputMode='table' - 'which colors are selling best?' -> queryKind='line_items', dimensionKey='color', metricKey='booked_qty', outputMode='summary' DATE RESOLUTION: Always resolve relative phrases to exact YYYY-MM-DD before calling. Use the current date. Set filters.dateRange.field from the requested date field; do not default vague date wording to entered unless the user says order date/entered date or gives no date field. - 'this month' -> first of month to today - 'last week' -> Monday-Sunday of last calendar week - 'this quarter' -> first day of current quarter to today - 'Q1 2025' -> 2025-01-01 to 2025-03-31 (Q2=Apr-Jun, Q3=Jul-Sep, Q4=Oct-Dec) - 'last 30 days' -> today minus 30 days to today - 'last year' -> Jan 1 to Dec 31 of previous year - 'YTD' -> Jan 1 of current year to today OUTPUT MODES: - summary: text-only response (default for all simple questions, including grouped summaries) - table: only when the user explicitly asks for table, details, rows, widget table, or to open row-level data visually - chart: when the user asks for chart, graph, bar graph, bar chart, line chart, donut, visual, visualization, nice view, cleaner view, or any visual representation. ALWAYS re-call this tool with outputMode='chart' - never answer from memory, never generate bullet points, ASCII art, or Markdown tables as a visual substitute. - export: only when the user explicitly asks for export, Excel, XLSX, spreadsheet, or download - RULE: Any request for a chart or graph is a mandatory tool call. Do not skip it. Do not explain what the chart would look like in text. Call this tool with outputMode='chart' and carry forward all prior filters, basePattern, dimensionKey, and metricKey. - RULE: Any request for a list, rows, details, data table, full table, or 'show me those orders' must use outputMode='table'. Never answer with a Markdown table instead of opening the widget. - RULE: Do not use Python/data analysis to draw charts for AIMS360 results. Use this tool's chart output so the MCP widget renders the visual. - RULE: If the server rejects a basePattern conflict, retry once by removing the duplicate locked filter. Example: overdue already defines statuses, so do not set filters.statuses with basePattern='overdue'. - For summary output, do not mention widget, table, chart, or export unless the user asks for them. REGISTRY-BACKED QUERY PLANNING: - Use selectFields for extra raw-list columns the user asked to see. - Use fieldFilters for filters on registry fields not represented in the named filters object. - Use sortSpec for explicit sort field and direction. Keep legacy sort only for vague oldest/newest/highest requests. - Never invent field names. If unsure, call retrieve_aims360_metadata first. TOOL RESULT CONTRACT: - The server returns structuredContent.intentSummary with what the server understood after validation and business-rule expansion. - The server returns structuredContent.filters as plain-English filters. Use these to explain scope only when helpful. - The server returns structuredContent.resultSummary with authoritative counts, group counts, totals, and limit/truncation flags. - The server returns structuredContent.previewRows for grouped summaries or explicit table/export requests. - Use previewRows for concise details. If previewRows is empty, do not invent rows; re-call this tool with outputMode='table' when the user asks to see rows/orders. - Do not say you could not display rows after a successful table/detail call. Use the widget/table payload or previewRows returned by the tool. - Write the final answer from structuredContent. Do not recalculate totals from rows and do not invent missing numbers. - If outputMode is summary, answer in text only. Do not mention widget/table/chart/export unless the user asked for one. - If the user asked for a chart, visual, nice view, cleaner view, or widget, do not leave outputMode as summary. If the server returns a clarification message, relay it to the user and ask for the missing detail. If the user's intent is genuinely unclear, ask before calling.
