{
  "id": "weekly-order-comparison-v1",
  "title": "Your first restaurant sales comparison",
  "exampleLabel": "Synthetic example. These are not customer results.",
  "description": "See what a useful first answer looks like, then ask your AI to repeat the method with your connected restaurant data.",
  "synthetic": true,
  "source": "Square",
  "timezone": "America/New_York",
  "location": { "id": "synthetic-square-location", "name": "Example Restaurant" },
  "currency": "USD",
  "metric": {
    "amountLabel": "Order amount",
    "amountDefinition": "Sum of interface.order.amount, in dollars, for completed Square order rows at one location. The Square mapping subtracts tax, service charge and tip from the order total. This is not profit, an accounting net-sales definition or marketing-attributed revenue.",
    "countLabel": "Completed orders",
    "countDefinition": "COUNT of non-null id values on the selected completed Square order rows. This single-source example has one row per order. Check row identity before reusing the method for another POS.",
    "averageLabel": "Average order amount",
    "averageDefinition": "Order amount divided by completed order rows, in dollars per order."
  },
  "ownerPrompt": "For my restaurant, compare September 28 to October 4 with October 5 to October 11, 2026, using the restaurant's local timezone. Use only one connected POS and location. Show the exact dates, source, sales definition, completed orders and average order amount. Check import coverage and missing amounts before interpreting a total. Explain whether the difference comes from order count, average order amount or both. Do not infer the cause from the comparison alone.",
  "periods": [
    {
      "id": "previous",
      "label": "September 28 to October 4, 2026",
      "startInclusive": "2026-09-28T04:00:00.000Z",
      "endExclusive": "2026-10-05T04:00:00.000Z",
      "expected": { "amountDollars": 600, "orders": 4, "averageOrderDollars": 150 }
    },
    {
      "id": "current",
      "label": "October 5 to October 11, 2026",
      "startInclusive": "2026-10-05T04:00:00.000Z",
      "endExclusive": "2026-10-12T04:00:00.000Z",
      "expected": { "amountDollars": 750, "orders": 5, "averageOrderDollars": 150 }
    }
  ],
  "expectedComparison": {
    "amountChangeDollars": 150,
    "amountChangePercent": 25,
    "orderChange": 1,
    "orderChangePercent": 25,
    "averageOrderChangeDollars": 0,
    "interpretation": "The restaurant recorded one more completed order. Average order amount stayed at $150, so the higher total came from order count, not a higher average order amount. These figures do not establish why the extra order happened."
  },
  "agentSetup": {
    "organizationTool": "listOrganizations",
    "organizationRule": "Choose the authorized restaurant returned by listOrganizations. In hosted MCP calls, add that organizationId to each subsequent input. The CLI uses --org instead. Never invent the ID or copy a real restaurant's ID into this public example.",
    "describeCalls": [
      { "tool": "describeData", "input": { "schemaName": "interface", "objectTypeName": "location" } },
      { "tool": "describeData", "input": { "schemaName": "interface", "objectTypeName": "order", "includeGrammar": false } }
    ],
    "locationsCall": {
      "tool": "queryData",
      "input": { "schemaName": "interface", "objectTypeName": "location", "args": { "fields": ["id", "name", "type"], "limit": 100 } }
    },
    "preflight": [
      "Confirm restaurant access, location identity, one source type and the restaurant's timezone.",
      "Confirm the requested history has finished importing. Empty query results cannot establish import completeness.",
      "Confirm the metric definition against the POS for the same source, local dates and location.",
      "If any selected completed row has a missing amount, report the incomplete data instead of treating it as zero or presenting the total as complete."
    ]
  },
  "queries": [
    {
      "id": "missing-amounts",
      "tool": "queryData",
      "input": {
        "schemaName": "interface",
        "objectTypeName": "order",
        "commands": [
          { "type": "filter", "filter": { "type": "and", "filters": [
            { "$type": { "string": "square", "match": "EQ" } },
            { "$locationId": { "string": "synthetic-square-location", "match": "EQ" } },
            { "$status": { "string": "COMPLETED", "match": "EQ" } },
            { "$closedAt": { "datetime": "2026-09-28T04:00:00.000Z", "match": "GTE" } },
            { "$closedAt": { "datetime": "2026-10-12T04:00:00.000Z", "match": "LT" } },
            { "$amount": { "match": "NULL" } }
          ] } },
          { "type": "aggregate", "aggregate": { "aggregate": { "$id": "COUNT" } } }
        ]
      },
      "expectedData": [{ "id": 0 }]
    },
    {
      "id": "previous",
      "tool": "queryData",
      "input": {
        "schemaName": "interface",
        "objectTypeName": "order",
        "commands": [
          { "type": "filter", "filter": { "type": "and", "filters": [
            { "$type": { "string": "square", "match": "EQ" } },
            { "$locationId": { "string": "synthetic-square-location", "match": "EQ" } },
            { "$status": { "string": "COMPLETED", "match": "EQ" } },
            { "$closedAt": { "datetime": "2026-09-28T04:00:00.000Z", "match": "GTE" } },
            { "$closedAt": { "datetime": "2026-10-05T04:00:00.000Z", "match": "LT" } }
          ] } },
          { "type": "aggregate", "aggregate": { "aggregate": { "$amount": "SUM", "$id": "COUNT" } } }
        ]
      },
      "expectedData": [{ "amount": 600, "id": 4 }]
    },
    {
      "id": "current",
      "tool": "queryData",
      "input": {
        "schemaName": "interface",
        "objectTypeName": "order",
        "commands": [
          { "type": "filter", "filter": { "type": "and", "filters": [
            { "$type": { "string": "square", "match": "EQ" } },
            { "$locationId": { "string": "synthetic-square-location", "match": "EQ" } },
            { "$status": { "string": "COMPLETED", "match": "EQ" } },
            { "$closedAt": { "datetime": "2026-10-05T04:00:00.000Z", "match": "GTE" } },
            { "$closedAt": { "datetime": "2026-10-12T04:00:00.000Z", "match": "LT" } }
          ] } },
          { "type": "aggregate", "aggregate": { "aggregate": { "$amount": "SUM", "$id": "COUNT" } } }
        ]
      },
      "expectedData": [{ "amount": 750, "id": 5 }]
    }
  ],
  "fixture": [
    { "id": "demo-01", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-09-28T04:00:00.000Z", "amount": 100 },
    { "id": "demo-02", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-09-29T17:00:00.000Z", "amount": 150 },
    { "id": "demo-03", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-01T17:00:00.000Z", "amount": 200 },
    { "id": "demo-04", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-05T03:59:59.999Z", "amount": 150 },
    { "id": "demo-05", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-05T04:00:00.000Z", "amount": 100 },
    { "id": "demo-06", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-06T17:00:00.000Z", "amount": 150 },
    { "id": "demo-07", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-08T17:00:00.000Z", "amount": 200 },
    { "id": "demo-08", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-10T17:00:00.000Z", "amount": 150 },
    { "id": "demo-09", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-12T03:59:59.999Z", "amount": 150 },
    { "id": "exclude-open", "type": "square", "locationId": "synthetic-square-location", "status": "OPEN", "closedAt": null, "amount": 999 },
    { "id": "exclude-cancelled", "type": "square", "locationId": "synthetic-square-location", "status": "CANCELED", "closedAt": "2026-10-06T17:00:00.000Z", "amount": 999 },
    { "id": "exclude-location", "type": "square", "locationId": "synthetic-other-location", "status": "COMPLETED", "closedAt": "2026-10-06T17:00:00.000Z", "amount": 999 },
    { "id": "exclude-source", "type": "clover", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-06T17:00:00.000Z", "amount": 999 },
    { "id": "exclude-before", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-09-28T03:59:59.999Z", "amount": 999 },
    { "id": "exclude-after", "type": "square", "locationId": "synthetic-square-location", "status": "COMPLETED", "closedAt": "2026-10-12T04:00:00.000Z", "amount": 999 }
  ],
  "limits": [
    "A synthetic fixture verifies the example and query contract, not a live POS integration, import coverage or OAuth connection.",
    "The example uses calendar weeks, not a restaurant's custom trading-day cutoff.",
    "Source metrics differ. Do not reuse the amount or count label for another POS without checking its definitions.",
    "No percentage change is defined when the previous period's value is zero.",
    "Comparing weeks does not establish marketing attribution, causation or profitability.",
    "These data tools are read-only. Other Feast tools can change account data and require appropriate permission."
  ],
  "setupUrl": "https://feastalytics.com/connect-ai",
  "quickstartUrl": "https://feastalytics.com/restaurant-data-connector-quickstart.md"
}