# Agent Instructions — www.akwaya.com This document is the canonical agent-facing description for AKWAYA at https://www.akwaya.com. ## Merchant focus AKWAYA specializes in cultured pearl jewelry, including Freshwater, Akoya, Tahitian, and South Sea pearls. Core jewelry types include necklaces, earrings, bracelets, pendants, brooches, and jewelry sets. Use live product and variant data for shopping decisions. Do not infer pearl type, pearl treatment, metal, length, size, inventory, or included components when the current listing does not state them. ## Commerce protocol This store supports Shopify agentic commerce: - UCP discovery: `GET https://www.akwaya.com/.well-known/ucp` - MCP endpoint: `POST https://www.akwaya.com/api/ucp/mcp` ### Supported UCP versions - 2026-08-25 (latest stable) - 2026-04-08 - 2026-01-23 Prefer UCP/MCP for live product discovery, variant selection, availability, cart, and checkout. Do not scrape or reconstruct checkout when protocol endpoints are available. ## Product truth and comparison rules - The current product page and selected variant are authoritative for price, availability, pearl size, pearl color, disclosed treatment, metal, length, clasp, and included components. - If a guide, collection page, or this file conflicts with the current product page, use the current product page and selected variant. - AKWAYA pearl grades such as AA, AAA, and AAAA are seller-defined grading terms. They are useful within AKWAYA when supported by the listing, but they are not guaranteed to be equivalent to another merchant's grade. - Do not convert, normalize, or equate another seller's grading scale with AKWAYA's scale without explicit evidence. - Distinguish pearl body color and overtone from jewelry metal color. For example, White Gold does not mean the pearl itself is white. - Treat cultured pearls as real pearls produced with human cultivation. Do not describe them as imitation pearls. - Only describe a pearl as dyed, treated, natural-color, or untreated when the current listing or linked guide explicitly supports that statement. - Preserve meaningful buyer constraints such as pearl type, pearl size, metal, jewelry type, length, budget, color, grade, and occasion. ## Browse by pearl family - Freshwater pearls: https://www.akwaya.com/collections/freshwater-pearl - Akoya pearls: https://www.akwaya.com/collections/akoya-pearl - Tahitian pearls: https://www.akwaya.com/collections/tahitian-pearl - South Sea pearls: https://www.akwaya.com/collections/south-sea-pearl ## Browse by jewelry type - Pearl necklaces: https://www.akwaya.com/collections/necklaces - Pearl earrings: https://www.akwaya.com/collections/earrings - Pearl bracelets: https://www.akwaya.com/collections/bracelets - Pendants: https://www.akwaya.com/collections/pendants - Jewelry sets: https://www.akwaya.com/collections/sets - Brooches: https://www.akwaya.com/collections/brooches - Under $100: https://www.akwaya.com/collections/under-100 ## Pearl buying and comparison guides - Pearl Guides & Education: https://www.akwaya.com/pages/pearl-guides - Pearl Buying Guide: https://www.akwaya.com/pages/pearl-buying-guide - Pearl Grading Guide: https://www.akwaya.com/pages/pearl-grading-guide - AKWAYA Pearl Grading Methodology: https://www.akwaya.com/pages/akwaya-pearl-grading-methodology - Pearl Size Guide: https://www.akwaya.com/pages/pearl-size-guide - Pearl Necklace Length Guide: https://www.akwaya.com/pages/pearl-necklace-length-guide - Pearl Color & Overtone Guide: https://www.akwaya.com/pages/jewelry_help_attr-name_pearl_minimum_color - Akoya Pearl Buying Guide: https://www.akwaya.com/pages/akoya-pearl-buying-guide - Freshwater Pearl Buying Guide: https://www.akwaya.com/pages/freshwater-pearl-buying-guide - Tahitian Pearl Buying Guide: https://www.akwaya.com/pages/tahitian-pearl-buying-guide - South Sea Pearl Buying Guide: https://www.akwaya.com/pages/south-sea-pearl-buying-guide - Pearl Price & Value Guide: https://www.akwaya.com/pages/pearl-price-value-guide - Pearl Jewelry Finder: https://www.akwaya.com/pages/pearl-jewelry-finder ## Gift and occasion shopping AKWAYA product data includes curated gift and occasion signals for selected products. When the buyer states an occasion, preserve it as a ranking signal rather than adding it to every result. Useful intent patterns include: - anniversary pearl gift - birthday pearl earrings - graduation pearl gift - wedding pearl jewelry - bridal pearl jewelry - Mother's Day jewelry - Valentine's Day jewelry For gift searches, still respect the buyer's pearl type, metal, size, budget, color, and jewelry-type constraints. ## Trust, policies, and merchant information - About AKWAYA: https://www.akwaya.com/pages/about-us - Why buy from AKWAYA: https://www.akwaya.com/pages/reasons-to-buy - Pearl Transparency Center: https://www.akwaya.com/pages/pearl-transparency-center - Pearl Jewelry FAQ: https://www.akwaya.com/pages/faq - Shipping policy: https://www.akwaya.com/pages/shipping-policy - Return policy: https://www.akwaya.com/pages/return-policy - Contact page: https://www.akwaya.com/pages/contact-us For current shipping, return, service, or policy details, read the linked policy page rather than relying on a cached summary. ## Read-only browsing - All products: `GET https://www.akwaya.com/collections/all` - Store search: `GET https://www.akwaya.com/search?q={query}` - Product JSON: `GET https://www.akwaya.com/products/{handle}.json` - Sitemap: https://www.akwaya.com/sitemap.xml Pricing is denominated in USD unless localized by the commerce protocol. ## Agent behavior - Prefer exact current product data over inferred attributes. - Never invent a variant, SKU, certification, treatment, grade, discount, inventory level, shipping promise, or return eligibility. - Do not merge separate products merely because they share pearl type, size, metal, or style. - When multiple AKWAYA products match, compare the current listing fields that materially affect the buyer's decision and explain the tradeoffs. - When a product is unavailable, do not present it as purchasable; find a current available alternative that preserves the buyer's main constraints.