Pinch Grocery Prices MCP

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "sort": {
      "enum": [
        "relevance",
        "price_asc",
        "price_desc",
        "unit_price_asc"
      ],
      "type": "string",
      "default": "relevance"
    },
    "limit": {
      "type": "number",
      "description": "Number of results (1-50, default 20)"
    },
    "query": {
      "type": "string",
      "description": "Search query (e.g., 'full cream milk', 'chicken breast')"
    },
    "category": {
      "type": "string",
      "description": "Filter by category"
    },
    "retailer": {
      "enum": [
        "Woolworths",
        "Coles",
        "Aldi",
        "Harris Farm"
      ],
      "type": "string"
    },
    "on_special": {
      "type": "boolean",
      "description": "If true, only return products on special"
    }
  }
}

{
  "type": "object",
  "required": [
    "product_id"
  ],
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID from search results"
    }
  }
}

{
  "type": "object",
  "required": [
    "barcode"
  ],
  "properties": {
    "barcode": {
      "type": "string",
      "description": "EAN-13 barcode (e.g., '9300675016902')"
    }
  }
}

{
  "type": "object",
  "required": [
    "product_id"
  ],
  "properties": {
    "days": {
      "type": "number",
      "description": "Number of days of history (default: max for your tier)"
    },
    "product_id": {
      "type": "string",
      "description": "Product ID from search results"
    }
  }
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Number of results (1-50, default 20)"
    },
    "category": {
      "type": "string",
      "description": "Filter by category"
    },
    "retailer": {
      "enum": [
        "Woolworths",
        "Coles",
        "Aldi",
        "Harris Farm"
      ],
      "type": "string"
    }
  }
}

{
  "type": "object",
  "required": [
    "product_name"
  ],
  "properties": {
    "limit": {
      "type": "number",
      "description": "Number of results (1-50, default 10)"
    },
    "product_name": {
      "type": "string",
      "description": "Product to search for (e.g., 'full cream milk 2L')"
    }
  }
}

{
  "type": "object",
  "required": [
    "raw_input",
    "category_path",
    "canonical_query",
    "quantity",
    "qualifiers",
    "disqualifiers",
    "barcode_eligible"
  ],
  "properties": {
    "quantity": {
      "type": "object",
      "properties": {
        "size": {
          "type": "string",
          "description": "Expected size, e.g. '1kg', '2L', '6-pack'"
        },
        "intent": {
          "type": "string",
          "description": "Size intent: 'family' (2-3L/1-2kg), 'single serve', 'standard', 'bulk'"
        }
      },
      "description": "Target size. Use to filter results after search. Family intent means prefer larger sizes for better unit price."
    },
    "raw_input": {
      "type": "string",
      "description": "The item exactly as the user wrote it"
    },
    "qualifiers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Soft preferences that improve a match but don't disqualify if absent. e.g. ['skinless', 'boneless'] for chicken breast, ['Australian'] for sultanas"
    },
    "category_path": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ontological path from general to specific, e.g. ['meat', 'poultry', 'chicken', 'breast'] or ['pantry', 'cereal', 'wheat biscuits']"
    },
    "disqualifiers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Terms that indicate a WRONG product. Results containing these MUST be excluded. e.g. for 'chicken breast': ['thigh', 'drumstick', 'wing', 'nugget', 'schnitzel', 'crumbed', 'marinated']. For 'Vegemite': ['twist', 'scroll', 'shapes', 'cheesy bite']. For 'strawberries': ['yoghurt', 'jam', 'ice cream', 'flavoured']. For 'milk': ['flavoured', 'chocolate', 'coffee', 'almond', 'oat', 'soy', 'coconut']."
    },
    "canonical_query": {
      "type": "string",
      "description": "The cleaned search term to use with search_products. Strip sizes and brands (unless brand IS the product, like 'Vegemite'). 'chicken breast bulk pack' becomes 'chicken breast fillets'. 'Sanitarium Weet-Bix' becomes 'Weet-Bix'. 'full cream milk 2L' becomes 'full cream milk'."
    },
    "barcode_eligible": {
      "type": "boolean",
      "description": "true for branded packaged goods (Weet-Bix, Vegemite, cheese slices, chips). false for fresh produce, meat, and store-brand generics. When true AND a result has a barcode, call compare_prices to check if another retailer has it cheaper."
    },
    "brand_preference": {
      "type": "string",
      "description": "ONLY set this if the user LITERALLY named a brand (e.g. 'Weet-Bix', 'Vegemite'). If the user wrote a generic item like 'milk', 'chicken breast', 'eggs', 'bread', this MUST be null. When null, Pinch finds the cheapest option regardless of brand."
    },
    "suggested_category": {
      "type": "string",
      "description": "The grocery store category to filter search results. Use this to prevent wrong-category contamination. e.g. 'Pantry' for rice crackers (prevents dairy lunch packs), 'Fruit & Vegetables' for fresh produce, 'Meat & Seafood' for meat, 'Dairy, Eggs & Fridge' for dairy, 'Frozen' for frozen items. Only set when the item clearly belongs to one category and cross-category results would be noise."
    }
  }
}

{
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Item name as on a shopping list (e.g., 'chicken breast 1kg', 'fresh rosemary', 'sea salt')"
          },
          "category": {
            "type": "string",
            "description": "Explicit category filter (e.g., 'Fruit & Vegetables'). Overrides product_type."
          },
          "product_type": {
            "enum": [
              "fresh_produce",
              "meat",
              "dairy",
              "pantry",
              "frozen",
              "drinks",
              "bakery",
              "deli"
            ],
            "type": "string",
            "description": "Category hint. Set fresh_produce for fruits/vegetables/herbs, meat for raw proteins, dairy for milk/cheese/eggs/yoghurt, pantry for canned/dried/shelf-stable goods."
          }
        }
      },
      "description": "List of grocery items to search (1-20 items)."
    },
    "retailers": {
      "type": "array",
      "items": {
        "enum": [
          "Woolworths",
          "Coles",
          "Aldi",
          "Harris Farm"
        ],
        "type": "string"
      },
      "description": "Filter to these retailers only. If omitted, all 4 are searched."
    },
    "candidates_per_retailer": {
      "type": "number",
      "description": "Number of candidate products to return per retailer per item (1-30, default 10). Use more candidates if you expect ambiguous results."
    }
  }
}

{
  "type": "object",
  "required": [
    "selections"
  ],
  "properties": {
    "selections": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "query",
          "picks"
        ],
        "properties": {
          "picks": {
            "type": "object",
            "description": "Best product_id per retailer. Keys are retailer names (Woolworths, Coles, Aldi, Harris Farm). Values are product_id strings.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "query": {
            "type": "string",
            "description": "Original search query (for display in basket)"
          }
        }
      },
      "description": "List of confirmed product selections, one entry per shopping list item."
    }
  }
}

{
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Shopping list items exactly as the user wrote them, e.g. ['4 bananas', 'whole chicken', '12 free range eggs', 'full cream milk 2L', 'spaghetti', 'sliced white bread']. Include any size/quantity in the string ('2L', '1kg', '12 pack') so the cheapest CORRECT size is chosen."
    },
    "retailers": {
      "type": "array",
      "items": {
        "enum": [
          "Woolworths",
          "Coles",
          "Aldi",
          "Harris Farm"
        ],
        "type": "string"
      },
      "description": "Only return results from these stores. Omit to search all four."
    }
  }
}