Ivory River — Agent Commerce

Search the Ivory River catalog with semantic + keyword hybrid ranking. Use for natural-language queries like "rtx 5090 laptop under $3000" or "case for AM5 build with tempered glass".

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text search query."
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50
    },
    "in_stock": {
      "type": "boolean",
      "default": true,
      "description": "Whether to exclude out-of-stock items. Default true."
    }
  },
  "required": [
    "query"
  ]
}

Get full detail for a single product by ID. Includes price, stock, attributes, and (for BYOPC builds) a configurator summary.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "WooCommerce product ID."
    },
    "fields": {
      "type": "string",
      "description": "Optional comma-separated field projection."
    }
  },
  "required": [
    "id"
  ]
}

List the four BYOPC tiers (Squire, Knight, DragonSlayer, Archangel) with their base prices and aggregate component summaries. Use this to overview what custom-build options exist before drilling into a specific tier.

{
  "type": "object",
  "properties": {}
}

Pull the full configurator schema for a single BYOPC tier: every field (Processor, Motherboard, GPU, RAM, Storage, etc.) with all child product options including price, stock, and IDs. Use this to see what selections are available before quoting.

{
  "type": "object",
  "properties": {
    "tier_id": {
      "type": "integer",
      "description": "BYOPC tier product ID. 378 Squire, 459 Knight, 371 DragonSlayer, 460 Archangel."
    }
  },
  "required": [
    "tier_id"
  ]
}

Itemize a configured BYOPC build: returns line totals + grand total + pairwise compatibility check. Empty selections are valid -- the server auto-fills the cheapest in-stock option for any required field.

{
  "type": "object",
  "properties": {
    "tier_id": {
      "type": "integer"
    },
    "selections": {
      "type": "object",
      "description": "Object mapping field_id (string) → child_product_id (integer). E.g. {\"123\": 456, \"789\": 101}.",
      "additionalProperties": {
        "type": "integer"
      }
    }
  },
  "required": [
    "tier_id"
  ]
}

Pairwise socket / DDR / form-factor compatibility check between two products. Returns { compatible, reason }. Use before recommending a CPU + motherboard pairing or RAM + motherboard.

{
  "type": "object",
  "properties": {
    "product_id_1": {
      "type": "integer"
    },
    "product_id_2": {
      "type": "integer"
    }
  },
  "required": [
    "product_id_1",
    "product_id_2"
  ]
}

Recommend BYOPC desktop tiers, optionally filtered by budget. `use_case` is informational (echoed in metadata) and helps the agent reason; the result is sorted by total ascending. For laptop recommendations, call search_products with category="laptops" instead.

{
  "type": "object",
  "properties": {
    "use_case": {
      "type": "string",
      "description": "Free-form e.g. \"competitive FPS gaming\", \"video editing\"."
    },
    "budget": {
      "type": "number",
      "description": "USD ceiling. Builds with total > budget are dropped."
    }
  }
}

Build the URL the agent hands to the user to finalize a recommendation. Lands the user on ivoryriver.store with the chat widget auto-opened, the agent's recommendation pre-staged, and quick-reply chips: [Yes, add to cart] [Show me the breakdown] [Modify components]. Use this AFTER you've recommended a build (via recommend_build / list_build_options / quote_build) and the user wants to proceed. The user always finishes the purchase in the browser; you never check out.

{
  "type": "object",
  "properties": {
    "agent_name": {
      "type": "string",
      "description": "How the agent should be named in the handoff greeting (e.g. \"Claude Desktop\", \"Cursor\", \"your AI assistant\"). Cosmetic; defaults to \"your AI assistant\"."
    },
    "recommendation": {
      "type": "object",
      "description": "The recommendation to hand off.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "byopc",
            "product",
            "generic"
          ],
          "description": "byopc = a BYOPC tier with selections; product = a specific WooCommerce product (laptop, GPU, etc.); generic = no specific product, conversation context only."
        },
        "tier_id": {
          "type": "integer",
          "description": "BYOPC tier product ID (kind=byopc)."
        },
        "tier_name": {
          "type": "string",
          "description": "Human-readable tier name shown in the chat (kind=byopc)."
        },
        "selections": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          },
          "description": "field_id → child_product_id (kind=byopc)."
        },
        "product_id": {
          "type": "integer",
          "description": "WooCommerce product ID (kind=product)."
        },
        "product_name": {
          "type": "string",
          "description": "Human-readable product name shown in the chat (kind=product)."
        },
        "quoted_total": {
          "type": "number",
          "description": "USD total quoted to the user. Cosmetic in the greeting; the server re-quotes when the user confirms."
        }
      },
      "required": [
        "kind"
      ]
    },
    "context": {
      "type": "string",
      "description": "Optional one-line summary of what the user originally asked (e.g. \"streaming + 4K editing under $2K\"). Shown to the chat backend so Aivy understands the original ask."
    }
  },
  "required": [
    "recommendation"
  ]
}