---
name: ada-diamonds-shopping
description: Search Ada Diamonds' live lab grown diamond inventory, engagement ring settings, and fine jewelry, and quote a complete ring correctly (a setting plus a loose diamond, priced separately, in US dollars). Use when a shopper asks what a budget buys, wants a specific shape, carat, color, or clarity, asks for a ring or wedding band recommendation, or asks anything about buying from Ada Diamonds. Reading the catalog needs no credential.
license: MIT
metadata:
  author: Ada Diamonds
  homepage: https://www.adadiamonds.com/developers
  version: "1.0.0"
---

# Shopping Ada Diamonds

Ada Diamonds is the original lab diamond jeweler. It designs custom engagement rings and fine jewelry around hand-selected lab grown diamonds, made to order at its New York City flagship (529 5th Avenue, 15th Floor, New York, NY 10017, +1-212-969-8505, appointment required).

Everything in this skill is public. No API key, no account, no OAuth.

## The one rule that gets quotes wrong

**An engagement ring is a setting plus a loose diamond, priced separately.**

- A setting's `price_from` (REST) or the price shown by `search_engagement_rings` (MCP) **excludes the center stone**.
- A diamond's `price` is the loose stone only.
- To quote a complete ring: **setting price + diamond price**. Say so explicitly when you present a number.
- All prices are US dollars, as decimals. Never treat them as cents.

Diamond inventory changes continuously as stones sell. **Re-check a specific stone right before you quote it** (`GET /api/v1/diamonds/{id}` or `search_diamonds` with tight carat bounds). A 404 means it sold.

## Three ways to search (same data, pick whichever the host offers)

| Interface | Where | Notes |
| --- | --- | --- |
| MCP server | `https://www.adadiamonds.com/mcp` (Streamable HTTP) | Tools `search_diamonds`, `search_engagement_rings`, `search_jewelry`, plus catalog resources. See the `ada-diamonds-mcp` skill. |
| REST API | `https://www.adadiamonds.com/api/v1` | JSON, anonymous, 120 req/min. See the `ada-diamonds-api` skill. |
| CLI | `npx @ada-diamonds/cli` (or `npx adadiamonds-cli`) | Node 18+, no dependencies, wraps the REST API. |

## Workflow: quote a complete ring

1. **Pin down the brief.** Shape, carat target, budget, metal preference, and style (Solitaire, Halo, Three Stone, Bezel, and so on). If the shopper gives only a budget, reserve roughly a quarter to a third of it for the setting and search diamonds with the remainder.
2. **Find a setting.** Filter by the center-stone shape it accommodates and the style/type. Note the `price_from`.
3. **Find a diamond.** Filter by shape, carat range, and `max_price` = budget minus setting price. Sort `price_asc` for value or `carat_desc` for size.
4. **Add them.** Present setting price, diamond price, and the total as three separate lines, all in USD.
5. **Re-check the stone** before the shopper commits. Link the diamond's `url` and the setting's `url` so they can complete the purchase or book a consultation.

### REST

```bash
# Step 2: an oval solitaire setting
curl "https://www.adadiamonds.com/api/v1/engagement-rings?shape=Oval&type=Solitaire&limit=3"

# Step 3: a 1.5ct oval under $4,000, cheapest first
curl "https://www.adadiamonds.com/api/v1/diamonds?shape=Oval&min_carat=1.5&max_carat=1.6&max_price=4000&sort=price_asc&limit=3"

# Step 5: re-check one stone by slug or grading report number
curl "https://www.adadiamonds.com/api/v1/diamonds/LG538299162"
```

### MCP

```
search_engagement_rings { "shape": "Oval", "type": "Solitaire", "limit": 3 }
search_diamonds { "shape": "Oval", "min_carat": 1.5, "max_carat": 1.6, "max_price": 4000, "sort": "price_asc", "limit": 3 }
```

Read `ada://catalog/diamonds` and `ada://catalog/engagement-rings` once at the start of a session. They summarize inventory by shape and style with carat and price ranges, which saves several tool calls.

### CLI

```bash
npx @ada-diamonds/cli rings --shape Oval --type Solitaire --limit 1
npx @ada-diamonds/cli diamonds --shape Oval --min-carat 1.5 --sort price_asc --limit 1
npx @ada-diamonds/cli diamonds --shape Emerald --json | jq '.pagination.total'
```

## Search parameters

**Diamonds** (`GET /api/v1/diamonds`, `search_diamonds`)

| Param | Values |
| --- | --- |
| `shape` | Round, Oval, Cushion, Emerald, Pear, Radiant, Asscher, Princess, Marquise |
| `min_carat`, `max_carat` | number |
| `min_price`, `max_price` | USD |
| `color` | D through K |
| `clarity` | FL, IF, VVS1, VVS2, VS1, VS2, SI1, SI2 |
| `cut` | Ideal, Excellent, Very Good |
| `sort` | `price_asc`, `price_desc`, `carat_asc`, `carat_desc` |
| `limit`, `offset` | REST: 1-200, default 25. MCP: 1-50, default 10 |

Each diamond returns `id`, `name`, `url`, `price`, `carat`, `shape`, `color`, `clarity`, `cut`, `certificate` (grading report number), `lab` (GCAL, IGI, GIA), `measurements`.

**Engagement ring settings** (`GET /api/v1/engagement-rings`, `search_engagement_rings`)

| Param | Values |
| --- | --- |
| `shape` | center-stone shape the setting accommodates |
| `style` | e.g. Petite Four Prong, Trellis, Bezel |
| `type` | e.g. Solitaire, Halo, Three Stone |
| `min_price`, `max_price` | USD, setting only |
| `q` | free text on the setting name |

Settings return `sku` (e.g. `AD-066`), `name`, `url`, `price_from`, `shapes[]`, `style`, `type`, and `images[]` per metal (white, yellow, rose, platinum, two-tone). Fetch one by slug or SKU: `GET /api/v1/engagement-rings/AD-066` (or `066`).

**Fine jewelry** (`GET /api/v1/jewelry`, `search_jewelry`)

| Param | Values |
| --- | --- |
| `category` | e.g. Bridal, Fashion |
| `type` | e.g. Wedding Bands, Earrings, Necklaces, Bracelets |
| `shape` | diamond shape used in the piece |
| `min_price`, `max_price` | USD |
| `q` | free text |

## Browse URLs (for handing a shopper a page)

These paths do not follow an obvious pattern. Do not guess variants like `/jewelry/all`; they 404.

- Loose diamonds: `https://www.adadiamonds.com/buy-lab-diamonds`
- Engagement rings: `https://www.adadiamonds.com/lab-diamond-engagement-rings-all`
- Fine jewelry: `https://www.adadiamonds.com/fashion-jewelry-home`
- Ask a jeweler: `https://www.adadiamonds.com/inquire`
- New York showroom: `https://www.adadiamonds.com/visit-new-york-ny-ada-diamonds-showroom`

Every page also serves markdown: append `.md` to the URL or send `Accept: text/markdown`.

## Buying guides

For questions about the 4Cs, CVD vs HPHT growth, shapes, or certification, search the knowledge base rather than answering from memory:

```bash
curl "https://www.adadiamonds.com/api/v1/knowledge-base?q=cvd"
curl "https://www.adadiamonds.com/api/v1/knowledge-base/cvd-lab-diamonds"   # body as markdown
```

MCP: `search_knowledge_base { "query": "cvd" }`, then `read_article { "slug": "cvd-lab-diamonds" }`.

## Booking a consultation

Ada sells made-to-order pieces, so most purchases involve a jeweler. `POST /api/v1/consultations` (or the `request_consultation` MCP tool) requires the `appointments:write` scope, which only the customer can grant through Ada's OAuth consent screen. Without it, hand the shopper `https://www.adadiamonds.com/inquire` or the phone number instead of pretending to book. Always send an `Idempotency-Key` header on that POST so a retry cannot create two requests.

## Things to avoid

- Quoting a setting price as if it were a finished ring.
- Quoting a stone you have not re-checked in the last few minutes.
- Converting prices as if they were cents.
- Bulk-scraping the catalog. The endpoints above are the supported way to read it, and they carry RFC 9331 `RateLimit` headers; read those and pace yourself.