# Clarypull for AI agents

> **Closed demonstration, not production.** Sign-in is through the configured identity provider; each store and each purchase is the signed-in person's own. No Amazon connection is configured. No payment provider is configured, so purchases are refused.

> **Free catalog beta.** This deployment sells nothing: it has no quote, order, checkout, payment, market check or offer. Listed prices are sellers' published terms, not offers.

Operational reference for an AI agent that searches Clarypull's free catalog beta for a person: how to search the catalog exactly and completely, every tool it serves with its arguments and results, and what this deployment does not offer. It sells nothing: there is no quote, order, payment or offer.

This is the text form of [/for-agents](/for-agents). A person connecting an agent should read [/agents](/agents) instead. Identifiers, times, amounts and counts in the examples are illustrative.

Contents:

- [Read this first](#rules)
- [Connect and discover](#discovery)
- [Search and explore the catalog](#search)
  - [Exact search](#exact)
  - [Constraints, units and unknown values](#constraints)
  - [Identifiers, models and variants](#identifiers)
  - [Paging and completeness](#paging)
  - [Exploration by meaning](#meaning)
  - [The catalog directory](#directory)
- [Authorization and boundaries](#boundaries)
- [Calling the REST API](#rest)
- [Tool reference](#tools)

<a id="rules"></a>

## Read this first

This deployment is a **free catalog beta**. Sellers publish their own catalogs for free, and you search and read them. **Nothing can be bought here**: there is no quote, order, checkout, payment, payout or paid plan, and no market check or offer. A listed price is the seller's published term, never an offer or a quote.

- **What you can do.** Search the catalog exactly, read a product and every seller's published listing of it, browse the categories and find products by their words, read a seller's disclosure, and report suspicious activity. These are the seven tools below, each also a REST operation.
- **What you cannot do.** Obtain a quote, prepare or pay for a purchase, read an order, create a market check, ask sellers for offers or select one. None of these tools is advertised, and a REST request for any of them is answered `403 PURCHASING_NOT_AVAILABLE`: a final answer, not a retry. Nothing was created or charged.
- **How to tell.** `tools/list` returns only the seven tools below, and the server's instructions and `clarypull_shopping_guide` say this is a free catalog beta. Every REST answer of a catalog operation carries `Clarypull-Service-Mode: FREE_CATALOG_BETA` and `Clarypull-Purchasing: unavailable`, and an MCP result carries the same statement in its text beside the document, which is not altered.
- **A result's `market_check_scope`.** A search result still carries it, because the result document is the contract's, but there is no market check to create here. Do not use it.
- **Never claim a purchase.** Tell the person plainly that this service lists products and that buying is not available in this beta. Do not say you can reserve, hold, buy or pay.

<a id="discovery"></a>

## Connect and discover

- Transport: MCP over Streamable HTTP at the deployment's connection address. The person copies it from [Connect an agent](/agents) and adds it to their agent app.
- Authorization: OAuth 2.0 with the person's own Clarypull account. The protected resource metadata (RFC 9728) is served without authentication at the well-known location derived from the address, and every `401` names it in `WWW-Authenticate`.
- Only agent apps that Clarypull has enabled can connect. Your token acts for one person.
- Decide what you can do from the tool names `tools/list` returns and from each tool's input schema. Each result document states its own `schema_version`.

**Discover the tools the server actually serves**

```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
```

<a id="search"></a>

## Search and explore the catalog

1. Read `clarypull_describe_catalog` for the category: which `attr.<key>` fields exist, their units, and how many products state each (`product_coverage`).
2. Turn each of the person's real requirements into a `where` clause with its unit. Keep preferences out of `where`.
3. Search in the exact mode. Read `membership`, `facets`, `near_misses` and `clause_impact` before suggesting the person relax anything, and never relax a requirement silently.
4. Follow `next_cursor` until it is `null` whenever you count, enumerate or claim completeness.
5. Read `clarypull_get_catalog_product` for the stated facts and every listing of the products the person cares about; it lists all of them, matching or not (see [Paging and completeness](#paging)).

**Example: Read the fields of one category before constraining them** (clarypull_describe_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_describe_catalog",
  "arguments": {
    "country": "US",
    "categories": [
      "amazon.dishwasher"
    ],
    "limit": 50
  }
}
```

**Example: One attribute field from the answer: its type, units, coverage and range** (clarypull_describe_catalog result, manifest 1.3.0 and later)

```json
{
  "field": "attr.width",
  "type_source": "OBSERVED_VALUES",
  "types": [
    {
      "type": "quantity",
      "dimension": "length",
      "listings": 37
    }
  ],
  "operators": [
    "eq",
    "ne",
    "lt",
    "lte",
    "gt",
    "gte",
    "between",
    "exists",
    "missing"
  ],
  "products_with_value": 31,
  "listings_with_value": 37,
  "product_coverage": 0.62,
  "canonical_unit": "mm",
  "stated_units": [
    "cm",
    "in",
    "inches"
  ],
  "minimum": "596",
  "maximum": "610",
  "top_values": [
    {
      "value": "609.6",
      "products": 12
    },
    {
      "value": "606",
      "products": 7
    }
  ],
  "distinct_values": 9,
  "top_values_truncated": true
}
```

A field with `product_coverage` 0.62 is stated for 62 % of the products in scope. A clause on it excludes the rest as unknown unless you admit unknowns, so tell the person when coverage is low.

<a id="exact"></a>

### Exact search

A product is a member when one of its listings satisfies every `where` clause and the text matches. All clauses of a `where` hold on the same listing. Membership is exhaustive and exact; ranking (`CATALOG_RANKING_V1`) orders members and decides none of them.

**Example: Exact search: every member under hard constraints, with facets and near misses** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "text": "built-in dishwasher",
    "categories": [
      "amazon.dishwasher"
    ],
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "all": [
        {
          "field": "attr.width",
          "op": "between",
          "values": [
            23.5,
            24.25
          ],
          "unit": "in"
        },
        {
          "field": "attr.noise_level",
          "op": "lte",
          "value": 46,
          "unit": "dB"
        },
        {
          "field": "price",
          "op": "lte",
          "value": {
            "amount_minor": 90000,
            "currency": "USD"
          }
        },
        {
          "not": {
            "field": "title",
            "op": "contains_words",
            "value": "refurbished"
          }
        }
      ]
    },
    "facets": [
      {
        "field": "attr.finish"
      },
      {
        "field": "attr.width",
        "unit": "in",
        "edges": [
          20,
          24,
          30
        ]
      }
    ],
    "include_near_misses": true,
    "explain": "full",
    "page": {
      "size": 25
    }
  }
}
```

**Example: The complete first page of that search** (clarypull_search_catalog result, manifest 1.3.0 and later)

```json
{
  "schema_version": "1.0.0",
  "capability": "CATALOG_SEARCH",
  "notice": "Catalog search reads the published catalog only: each listing's terms are what its seller published, as observed at observed_at, and each product fact is what that listing's seller stated. Nothing here is an offer, no seller was contacted, and nothing was reserved or bought. Read a product's every visible listing and stated fact with getCatalogProduct, and a field's coverage with describeCatalog; searching and reading never need a market check. market_check_scope only names how a result could scope an optional market check later; when it is null the product has no GTIN or ASIN, and none is to be invented.",
  "as_of": "2026-10-26T15:04:05.000Z",
  "ranking_policy": "CATALOG_RANKING_V1",
  "ship_to": {
    "country": "US",
    "postal_code": "94110"
  },
  "membership": {
    "mode": "EXHAUSTIVE_FILTERED",
    "exhaustive": true,
    "total_products": 1,
    "total_listings": 1,
    "rule": "Every product with at least one visible listing on which every hard constraint holds and the text matches, as of as_of; every member is reachable by following next_cursor, and ranking orders members without deciding any. An UNKNOWN value never satisfies a constraint."
  },
  "text_interpretation": {
    "mode": "WORDS",
    "applied_text": "built-in dishwasher",
    "text_mode": "all_terms",
    "not_applied": [],
    "warnings": []
  },
  "results": [
    {
      "product_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
      "category": "amazon.dishwasher",
      "product_type": "DISHWASHER",
      "title": "Example 24 in built-in dishwasher, stainless steel",
      "brand": "Example Brand",
      "model": "EX-24B",
      "identifiers": {
        "gtins": [
          "00012345678905"
        ],
        "asins": [],
        "mpns": [
          "EX-24B"
        ]
      },
      "score": 1.5,
      "matched_by": "WORDS",
      "qualifying_listings": 1,
      "listings_shown": 1,
      "listings": [
        {
          "listing_id": "c41e7b20-9d3a-4b5c-8f61-2e0a7d9b3c15",
          "seller_id": "5e8a1f3c-7b2d-4c90-a6e4-9f0b3d2c1a78",
          "seller_name": "Example Appliance Store",
          "content_origin": "SELLER_FEED",
          "published_price": {
            "item": {
              "amount_minor": 84900,
              "currency": "USD"
            },
            "total_before_tax": {
              "amount_minor": 89900,
              "currency": "USD"
            },
            "basis": "ITEM_AND_EVERY_MANDATORY_CHARGE_KNOWN_TAX_STATED_SEPARATELY",
            "tax": "KNOWN"
          },
          "availability": {
            "value": "AVAILABLE",
            "authoritative": false,
            "observed_at": "2026-10-26T14:30:00.000Z"
          },
          "delivery_window": {
            "earliest": "2026-10-29",
            "latest": "2026-11-03"
          },
          "deliverable_to_postal_code": "SATISFIED",
          "observed_at": "2026-10-26T14:30:00.000Z",
          "clauses": [
            {
              "path": "/where/all/0",
              "field": "attr.width",
              "op": "between",
              "negated": false,
              "status": "SATISFIED",
              "admitted_unknown": false,
              "values": [
                {
                  "kind": "QUANTITY",
                  "stated": "{\"unit\": \"inches\", \"value\": 23.875}",
                  "stated_unit": "inches",
                  "canonical": "606.425",
                  "canonical_unit": "mm",
                  "derived_by_unit_conversion": true,
                  "source": "SELLER_FEED"
                }
              ]
            },
            {
              "path": "/where/all/1",
              "field": "attr.noise_level",
              "op": "lte",
              "negated": false,
              "status": "SATISFIED",
              "admitted_unknown": false,
              "values": [
                {
                  "kind": "QUANTITY",
                  "stated": "{\"unit\": \"dB\", \"value\": 44}",
                  "stated_unit": "dB",
                  "canonical": "44",
                  "canonical_unit": "dB",
                  "source": "SELLER_FEED"
                }
              ]
            },
            {
              "path": "/where/all/2",
              "field": "price",
              "op": "lte",
              "negated": false,
              "status": "SATISFIED",
              "admitted_unknown": false,
              "values": [
                {
                  "kind": "MONEY",
                  "stated": "84900",
                  "canonical": "84900",
                  "canonical_unit": "USD"
                }
              ]
            },
            {
              "path": "/where/all/3/not",
              "field": "title",
              "op": "contains_words",
              "negated": true,
              "status": "SATISFIED",
              "admitted_unknown": false,
              "values": [
                {
                  "kind": "TEXT",
                  "stated": "Example 24 in built-in dishwasher, stainless steel",
                  "canonical": "Example 24 in built-in dishwasher, stainless steel"
                }
              ]
            }
          ]
        }
      ],
      "market_check_scope": {
        "category": "amazon.dishwasher",
        "hard_constraint": {
          "field": "gtin",
          "operator": "eq",
          "value": "00012345678905"
        },
        "note": "Optional, and never needed to search or read the catalog: a market check scoped by this category and hard constraint would ask every eligible seller of this exact product for personalized offers. Catalog search did not create one."
      }
    }
  ],
  "facets": [
    {
      "field": "attr.finish",
      "type": "text",
      "excluded_clauses": [],
      "products_in_scope": 1,
      "products_with_value": 1,
      "products_unknown": 0,
      "values": [
        {
          "value": "stainless steel",
          "products": 1
        }
      ],
      "distinct_values": 1,
      "complete": true
    },
    {
      "field": "attr.width",
      "type": "quantity",
      "excluded_clauses": [
        "/where/all/0"
      ],
      "products_in_scope": 2,
      "products_with_value": 1,
      "products_unknown": 1,
      "complete": true,
      "canonical_unit": "mm",
      "minimum": "606.425",
      "maximum": "606.425",
      "buckets": [
        {
          "to": "20",
          "products": 0
        },
        {
          "from": "20",
          "to": "24",
          "products": 1
        },
        {
          "from": "24",
          "to": "30",
          "products": 0
        },
        {
          "from": "30",
          "products": 0
        }
      ]
    }
  ],
  "near_misses": [
    {
      "product_id": "0d5e7f91-3a2b-4c6d-9e8f-7a1b2c3d4e5f",
      "title": "Example 24 in built-in dishwasher, black",
      "brand": "Example Brand",
      "listing_id": "6b8d0f2a-4c6e-4a1b-8d3f-5e7a9c1b3d26",
      "seller_id": "5e8a1f3c-7b2d-4c90-a6e4-9f0b3d2c1a78",
      "failed": {
        "path": "/where/all/1",
        "field": "attr.noise_level",
        "op": "lte",
        "negated": false,
        "status": "VIOLATED",
        "admitted_unknown": false
      }
    }
  ],
  "clause_impact": [
    {
      "path": "/where/all/0",
      "additional_products_without_it": 1
    },
    {
      "path": "/where/all/1",
      "additional_products_without_it": 1
    },
    {
      "path": "/where/all/2",
      "additional_products_without_it": 0
    },
    {
      "path": "/where/all/3",
      "additional_products_without_it": 1
    }
  ],
  "suggested_filters": [],
  "withdrawn_since_snapshot": 0,
  "withdrawn_products_since_snapshot": 0,
  "next_cursor": null
}
```

- `clause_impact` says how many more products each top-level clause excludes: here, dropping the width, the noise or the exclusion clause would each add one product.
- The near miss is kept out by its noise level alone (`VIOLATED`). The width facet sets its own clause aside (`excluded_clauses`), so it counts the alternatives to the person's choice too.
- `explain: full` shows the stated value behind each clause: 23.875 inches, compared as 606.425 mm. `summary` (the default) shows statuses only, and `none` omits them.
- Use `product_id` exactly as returned when you read a product again. There is no market check or purchase to continue to here.

<a id="constraints"></a>

### Constraints, units and unknown values

- **Three values.** Each clause is `SATISFIED`, `VIOLATED` or `UNKNOWN` on a listing. A value nobody stated is `UNKNOWN`, and `UNKNOWN` never satisfies a clause.
- **Admitting unknowns.** `if_unknown: include` (per clause or for the request) admits a listing whose value is unknown, labelled `UNKNOWN` with `admitted_unknown: true`. Use it only after the person accepts unconfirmed fit, and say which results are unconfirmed.
- **Negation.** Write exclusions as `not` clauses or with `ne`, `not_in` and `missing`. A `not` over `UNKNOWN` stays `UNKNOWN`. An exclusion written into the text ("-refurbished", "without wifi") is reported in `text_interpretation.not_applied` and not applied.
- **Units.** State the unit of every quantity. Values compare exactly across units in their dimension's canonical unit. Spellings are case-sensitive: `MB` is megabytes and `Mb` is not a unit; `dBA` is its own dimension, not `dB`. The accepted spellings are in `clarypull_describe_catalog`'s `units`.
- **Several stated values.** A value a seller stated several times (compatible devices, features) matches on any of them.
- **Sources.** Each stated value names its source: `SELLER_FEED`, `AMAZON_LISTING`, `AMAZON_CATALOG` (Amazon's shared catalog, which may merge other contributors' data), `SELLER_COMPLETION`, `DEVELOPMENT_FIXTURE` or `UNKNOWN`. Clarypull never states an inferred value as a fact.
- **Money.** A price clause takes money: `{"amount_minor": 90000, "currency": "USD"}` is $900.00. Sorting by `price` compares one currency: state `currency` when the deployment asks for it.
- **Published price.** `item` is the item price. `total_before_tax` is present only when every mandatory charge is known (`basis`), and `tax` says separately whether tax is known. These are published terms with `observed_at`, not offers or quotes.
- **Availability.** `AVAILABLE`, `UNAVAILABLE` or `UNKNOWN`, with `observed_at` and whether the observation is authoritative. Unknown availability is not availability.

**Example: Admit products that leave one requirement unstated, after the person accepts unconfirmed fit** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "categories": [
      "amazon.dishwasher"
    ],
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "all": [
        {
          "field": "attr.width",
          "op": "between",
          "values": [
            23.5,
            24.25
          ],
          "unit": "in",
          "if_unknown": "include"
        },
        {
          "field": "attr.noise_level",
          "op": "lte",
          "value": 46,
          "unit": "dB"
        }
      ]
    },
    "sort": [
      {
        "by": "price",
        "direction": "asc"
      }
    ],
    "currency": "USD"
  }
}
```

<a id="identifiers"></a>

### Identifiers, models and variants

A text that is exactly a GTIN, UPC-A, EAN-13 or GTIN-8 with a correct check digit, or an ASIN, matches exactly that product (an ASIN only in the destination's marketplace). One token of letters and digits also matches a model or MPN with or without punctuation. A wrong check digit is searched as words, with a warning.

**Example: One exact product by its GTIN (an ASIN or a model number works the same way)** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "text": "00012345678905",
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    }
  }
}
```

`variant_family` names a product's variation family. Its siblings (other sizes, colors or capacities) are other products with their own `product_id`; filter on the family to list them.

**Example: The siblings of a product's variation family (other sizes or colors are other products)** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "field": "variant_family",
      "op": "eq",
      "value": "ASIN:ATVPDKIKX0DER:B0EXAMPL00"
    }
  }
}
```

<a id="paging"></a>

### Paging and completeness

- An exact page states `total_products` and `total_listings` for the whole traversal. Repeat the identical request with `page.cursor` set to `next_cursor` until `next_cursor` is `null`; every member then appears exactly once.
- Every later page reads the snapshot of the first page, so concurrent publications neither add nor duplicate members. A seller suspended or disconnected meanwhile is removed, and `withdrawn_since_snapshot` and `withdrawn_products_since_snapshot` count what left.
- A cursor is bound to the person, the tenant and the request apart from `page`, and lasts fifteen minutes from the first page. Change anything else and you must start again. `CURSOR_EXPIRED` or `CURSOR_INVALID` means start again from the first page.
- A search result shows up to ten of a product's listings that satisfy the search; its `qualifying_listings` counts all that do, and no search cursor reaches the rest.
- `clarypull_get_catalog_product` does not continue a search. It applies no text or `where`, lists every listing of the product visible for the destination in price order, and reads its own snapshot, with its own `as_of`, count and cursor. A listing it returns may break the person's requirements, so check each one against them, with the same unknown-value policy, using the stated values it shows; present only those that pass as matches, and never as the search's total.
- Directory pages continue with `next_after` until it is empty.

**Example: The next page: the identical request with the cursor the previous page returned** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "text": "built-in dishwasher",
    "categories": [
      "amazon.dishwasher"
    ],
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "all": [
        {
          "field": "attr.width",
          "op": "between",
          "values": [
            23.5,
            24.25
          ],
          "unit": "in"
        },
        {
          "field": "attr.noise_level",
          "op": "lte",
          "value": 46,
          "unit": "dB"
        },
        {
          "field": "price",
          "op": "lte",
          "value": {
            "amount_minor": 90000,
            "currency": "USD"
          }
        },
        {
          "not": {
            "field": "title",
            "op": "contains_words",
            "value": "refurbished"
          }
        }
      ]
    },
    "facets": [
      {
        "field": "attr.finish"
      },
      {
        "field": "attr.width",
        "unit": "in",
        "edges": [
          20,
          24,
          30
        ]
      }
    ],
    "include_near_misses": true,
    "explain": "full",
    "page": {
      "size": 25,
      "cursor": "c2VhcmNoLWN1cnNvci1leGFtcGxl"
    }
  }
}
```

**Example: Every visible listing of one product, matching or not, fifty at a time** (clarypull_get_catalog_product call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_get_catalog_product",
  "arguments": {
    "product_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
    "country": "US",
    "postal_code": "94110",
    "page_size": 50
  }
}
```

<a id="meaning"></a>

### Exploration by meaning

When the person describes a need in words a listing may not use, add `retrieval: {"mode": "hybrid"}` (words and meaning) or `"semantic"` (meaning). The answer is one page of at most `candidates` products per lane, ranked by meaning, each still satisfying every hard constraint.

**Example: Exploration by meaning: one bounded page of candidates, still under every hard constraint** (clarypull_search_catalog call, manifest 1.3.0 and later)

```json
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "text": "quiet dishwasher for a small apartment kitchen",
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "field": "attr.width",
      "op": "lte",
      "value": 24,
      "unit": "in"
    },
    "retrieval": {
      "mode": "hybrid",
      "candidates": 50
    }
  }
}
```

**Example: What a ranked page says about its own coverage** (clarypull_search_catalog result, manifest 1.3.0 and later)

```json
{
  "mode": "RANKED_CANDIDATES",
  "exhaustive": false,
  "total_products": 12,
  "total_listings": 15,
  "rule": "Not every member: at most candidate_budget_per_lane products from each of two lanes, the products whose text matches in any-terms mode and the products whose documents are nearest the text's meaning, each with at least one visible listing on which every hard constraint holds, ranked by meaning in one page with no next page. An UNKNOWN value never satisfies a constraint. Search without retrieval to enumerate every member.",
  "ranked": {
    "mode": "hybrid",
    "model": "google/embeddinggemma-2@58faf90940886df2d62be555c8765d00dac362c5:bf16:768",
    "candidate_budget_per_lane": 50,
    "lexical_lane_products": 4,
    "dense_lane_products": 10,
    "dense_documents_examined": 40,
    "dense_listing_rows": 44,
    "dense_termination": "SCAN_STOPPED_EARLY_COVERAGE_UNKNOWN",
    "candidates_without_embedding": 0
  }
}
```

- A ranked answer is not every member: `membership.exhaustive` is false and `next_cursor` is always `null`. Never call it the complete set or count from it.
- A ranked request refuses `page.cursor`, `facets`, `include_near_misses`, `prefer` and any order but relevance. Use the exact mode to enumerate, count, facet or sort.
- `dense_termination: SCAN_STOPPED_EARLY_COVERAGE_UNKNOWN` means the index stopped at its own limits. It does not mean nothing else is near.
- A text that is an identifier or a model number is answered by the exact mode whatever mode you ask for, and is answered even without an embedding model.

<a id="directory"></a>

### The catalog directory

The directory is the simple lookup every deployment with manifest 1.2.0 or later serves: categories with counts, and one category's products by words in the title, brand or model, with identifiers. It carries no price, stock or offer. Where catalog search is listed, use search for anything more than an identity lookup.

**Example: Directory: the served categories, from the start** (clarypull_list_catalog_categories call, manifest 1.2.0 and later)

```json
{
  "name": "clarypull_list_catalog_categories",
  "arguments": {}
}
```

**Example: Directory: a category's products whose title, brand or model contain the words** (clarypull_find_catalog_products call, manifest 1.2.0 and later)

```json
{
  "name": "clarypull_find_catalog_products",
  "arguments": {
    "category": "amazon.dishwasher",
    "q": "EX-24B"
  }
}
```

<a id="boundaries"></a>

## Authorization and boundaries

- The server enforces authentication, scopes, ownership and constraint validation. A denial is final for that call; never try to bypass it.
- You may search and read. A search is not an offer, and nothing here is a purchase.
- Search results cover the sellers who have published here, not every product on the market. An empty result means nothing suitable was found here, not that nothing exists.
- A listing keeps its `listing_id` when its seller updates it, and gains a version. A product is merged only on an exact GTIN, marketplace ASIN, or brand, MPN and variant together; a seller's own item that states none of them is never merged with another publication of itself, so if its seller publishes again its `product_id` changes. A read of the old `product_id` is then answered `CATALOG_PRODUCT_NOT_FOUND`: search again for the current `product_id` rather than holding or guessing one.
- A deployment that is not live says so on its website. Its stores are test stores; never present its prices or stock as real.

<a id="rest"></a>

## Calling the REST API

Every tool is also a REST operation that answers the same document under the same scopes. Use it when your runtime makes HTTPS requests rather than MCP tool calls. A REST request is not a tool call: never send a JSON-RPC envelope, or a `{"name", "arguments"}` object, to a REST path.

- Origin: send requests to the API origin the deployment publishes for its REST API. This reference names none.
- Authentication: `Authorization: Bearer <access token>`, with a token the deployment's authorization server issued for that API and the operation's scopes.
- Responses: the same documents a tool returns as `structuredContent`. A refusal is `application/problem+json` with the same members, and a `Retry-After` header carries any retry interval.

**Each tool's REST request**

| Tool | Request | Arguments over REST |
| --- | --- | --- |
| `clarypull_describe_catalog` | `GET /v1/catalog/fields` | `country` → query `country`; `categories` → query `categories` (one value, comma-separated); `limit` → query `limit`; `after` → query `after` |
| `clarypull_search_catalog` | `POST /v1/catalog/search` | every argument → a JSON body member of the same name |
| `clarypull_get_catalog_product` | `GET /v1/catalog/products/{product_id}` | `product_id` → path `{product_id}`; `country` → query `country`; `postal_code` → query `postal_code`; `page_size` → query `page_size`; `cursor` → query `cursor` |
| `clarypull_list_catalog_categories` | `GET /v1/catalog/categories` | `after` → query `after` |
| `clarypull_find_catalog_products` | `GET /v1/catalog/products` | `category` → query `category`; `q` → query `q`; `after` → query `after` |
| `clarypull_get_seller_disclosure` | `GET /v1/sellers/{seller_id}/disclosure` | `seller_id` → path `{seller_id}` |
| `clarypull_report_marketplace_activity` | `POST /v1/marketplace-reports` | `idempotency_key` → header `Idempotency-Key`; `request` → the whole JSON body |

**Example: Catalog search over REST: the body is the tool's arguments, unchanged** (REST request for clarypull_search_catalog, manifest 1.3.0 and later)

```http
POST /v1/catalog/search HTTP/1.1
Host: <API host>
Authorization: Bearer <access token>
Accept: application/json
Content-Type: application/json

{
  "text": "built-in dishwasher",
  "categories": [
    "amazon.dishwasher"
  ],
  "ship_to": {
    "country": "US",
    "postal_code": "94110"
  },
  "where": {
    "all": [
      {
        "field": "attr.width",
        "op": "between",
        "values": [
          23.5,
          24.25
        ],
        "unit": "in"
      },
      {
        "not": {
          "field": "title",
          "op": "contains_words",
          "value": "refurbished"
        }
      }
    ]
  },
  "page": {
    "size": 25
  }
}
```

**Example: The field registry over REST: arguments in the query, categories comma-separated** (REST request for clarypull_describe_catalog, manifest 1.3.0 and later)

```http
GET /v1/catalog/fields?country=US&categories=amazon.dishwasher,amazon.refrigerator&limit=50 HTTP/1.1
Host: <API host>
Authorization: Bearer <access token>
Accept: application/json
```

<a id="tools"></a>

## Tool reference

<a id="tool-clarypull-describe-catalog"></a>

### `clarypull_describe_catalog`

Every searchable field: the core fields with their types, operators and level, and the attributes sellers state, with observed types, units, coverage, range and top values; and the units each dimension accepts.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `GET /v1/catalog/fields` (`describeCatalog`)
- Served from: manifest 1.3.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `country` | yes | Destination country (ISO 3166-1 alpha-2, for example `US`). |
| `categories` | no | Up to 20 served categories to describe; all visible categories when absent. |
| `limit` | no | Attribute fields per page, 1 to 200. |
| `after` | no | The `next_after` of the previous page. |

Returns:

- `core_fields`: Fixed fields with type, level (`product` or `listing`), operators and whether a listing may leave them unknown.
- `attribute_fields`: Each `attr.<key>` with `product_coverage`, `stated_units`, `canonical_unit`, range and top values.
- `units`: Each dimension's canonical unit and every accepted spelling.
- `next_after`: Field key to continue after; `null` on the last page.

- Contacts no seller. Read it before constraining a field you have not seen in this deployment.

<a id="tool-clarypull-search-catalog"></a>

### `clarypull_search_catalog`

Search every published listing visible to the person, under exact hard constraints, and return every member ranked and explained; or, with `retrieval`, one bounded page of candidates found by meaning.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `POST /v1/catalog/search` (`searchCatalog`)
- Served from: manifest 1.3.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `ship_to` | yes | `{country, postal_code?}`. The country decides which sellers and marketplaces apply; a postal code excludes sellers whose coverage does not reach it. |
| `text` | no | Up to 256 characters. A whole GTIN, UPC, EAN or ASIN matches that product exactly; one token of letters and digits also matches a model or MPN. |
| `text_mode` | no | `all_terms` (default), `any_terms` or `phrase`. |
| `categories` | no | Up to 20 served categories. |
| `where` | no | Hard constraints: a clause, or `all` / `any` / `not` over clauses, four levels and 64 nodes at most. |
| `if_unknown` | no | `exclude` (default) or `include`, for every clause that does not set its own. |
| `prefer` | no | Up to 8 clauses that only add to the rank of the exact mode. Never a filter. |
| `sort` | no | Up to 3 keys: `relevance`, `price`, `delivery_latest`, `title` or an `attr.<key>`, each `asc` or `desc`. |
| `currency` | no | The currency price sorting compares in, when the deployment has no single launch currency. |
| `facets` | no | Up to 16 fields to count values or numeric buckets for (`unit`, `edges`, `limit`, `after`). |
| `page` | no | `{size, cursor}`: 1 to 100 products per page, and the previous page's `next_cursor`. |
| `explain` | no | `none`, `summary` (default: each clause's status per listing) or `full` (also the stated values compared). |
| `include_near_misses` | no | Up to 10 products kept out by exactly one clause, with the clause that failed. |
| `retrieval` | no | `{mode, candidates?}`: `exact` (default), `hybrid` or `semantic`, with up to 100 candidates per lane. |

Returns:

- `membership`: `EXHAUSTIVE_FILTERED` with exact `total_products` and `total_listings`, or `RANKED_CANDIDATES` with what was examined.
- `results`: Products with identifiers, the qualifying listings' published terms, clause statuses and `market_check_scope`.
- `text_interpretation`: How the text was read: identifier, model or words, and any exclusion it did not apply.
- `facets`: Value counts or buckets, unknown counts, and the clauses each facet set aside.
- `near_misses`: What one clause keeps out.
- `clause_impact`: How many more products each top-level clause excludes.
- `suggested_filters`: Words of the text that equal a field value, or a near spelling of one.
- `next_cursor`: Cursor of the next page; `null` when there is none.

- Takes no idempotency key: it changes nothing and contacts no seller.
- Prices in results are published terms with their observation time, never offers.

<a id="tool-clarypull-get-catalog-product"></a>

### `clarypull_get_catalog_product`

Every listing of one product visible for the destination, a page at a time in price order, with each seller's published terms and every attribute each seller states, exactly as stated with its unit and the canonical value it is compared as. It applies no search constraint.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `GET /v1/catalog/products/{product_id}` (`getCatalogProduct`)
- Served from: manifest 1.3.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `product_id` | yes | A `product_id` from search or the directory. |
| `country` | yes | Destination country. |
| `postal_code` | no | US ZIP code; limits listings to sellers whose coverage reaches it. |
| `page_size` | no | Listings per page, 1 to 50 (default 20). |
| `cursor` | no | The previous page's `next_cursor`. |

Returns:

- `product`: The product with `qualifying_listings` (here every visible listing of it, not a search's matches), `listings_shown` and the listings of this page.
- `next_cursor`: Cursor of the next page of listings; `null` on the last.

- A separate read with its own snapshot, `as_of` and cursor, not a continuation of a search. Re-check each listing against the person's hard constraints and unknown-value policy before calling it a match.
- Statements that differ between sellers are shown side by side; none is chosen or merged.

<a id="tool-clarypull-list-catalog-categories"></a>

### `clarypull_list_catalog_categories`

The served categories that hold a product the person can reach, with product and seller counts, in category order.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `GET /v1/catalog/categories` (`listCatalogCategories`)
- Served from: manifest 1.2.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `after` | no | The previous page's `next_after`. |

Returns:

- `categories`: Each with `category`, `product_type`, `scope_category`, `products` and `sellers`.
- `next_after`: Category to continue after; empty on the last page.

- Identity only: no price, stock, offer or ranking.

<a id="tool-clarypull-find-catalog-products"></a>

### `clarypull_find_catalog_products`

A simple lookup of one served category's products whose title, brand or model contain the words, fifty a page by title, each with the identifiers a market check is scoped by.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `GET /v1/catalog/products` (`findCatalogProducts`)
- Served from: manifest 1.2.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `category` | yes | A served category, as `clarypull_list_catalog_categories` names it. |
| `q` | no | Up to 128 characters; empty lists every product of the category. |
| `after` | no | The previous page's `next_after`. |

Returns:

- `products`: Each with `product_id`, `scope_category`, title, brand, model, `asins` and `gtins`.
- `next_after`: Cursor to continue after; empty on the last page.

- Identity only. Where `clarypull_search_catalog` is listed, use it for constraints, units, ranking and facets.

<a id="tool-clarypull-get-seller-disclosure"></a>

### `clarypull_get_seller_disclosure`

What the INFORM Consumers Act requires disclosed of a seller, by the `seller_id` a listing, search result or purchase carries: whether it is a high-volume seller, whether identity disclosure is required of it, the verification standing of what is shown, its identity where required, and how to report suspicious activity.

- Effect: Read only; repeat freely
- Scopes: `market_checks:create`
- REST: `GET /v1/sellers/{seller_id}/disclosure` (`getSellerDisclosure`)
- Served from: manifest 1.7.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `seller_id` | yes | The seller, from `seller_id` on a listing, a search result or a purchase. |

Returns:

- `high_volume`: Whether the seller is a high-volume seller under the statute's thresholds.
- `disclosure_required`: Whether the seller's identity must be shown to the person; show `identity` whenever it is true.
- `verification`: `VERIFIED`, `PENDING`, `REJECTED` or `NONE`: the standing of the identity shown.
- `identity`: The seller's legal name and entity type, its address as its certification allows (in full, a returns address, or country and state with a statement that no business address is available), its phone or the statement that none is available, and its email; `null` when not required or not provided.
- `reporting`: The marketplace's email address and telephone number for reporting suspicious activity, beside `clarypull_report_marketplace_activity`; `null` until the operator registers them.

- Read it before the person buys from a seller and show the identity and reporting members when they are present; they are not terms of the purchase.
- Never state how the seller's bank, tax or identity elements are held: the document does not say, and neither do you.

<a id="tool-clarypull-report-marketplace-activity"></a>

### `clarypull_report_marketplace_activity`

Report suspicious marketplace activity to Clarypull's operator when the person asks to: a suspected counterfeit, fraud, an unsafe or recalled product, stolen goods, a misrepresented seller identity, or anything else, with the seller, product, listing or purchase it concerns where known.

- Effect: Creates a resource; takes an idempotency key
- Scopes: `market_checks:create`
- REST: `POST /v1/marketplace-reports` (`reportMarketplaceActivity`)
- Served from: manifest 1.7.0 and later

| Argument | Required | Meaning |
| --- | --- | --- |
| `idempotency_key` | yes | Unique per report; a retry with the same key and request answers the same receipt. |
| `request` | yes | `{schema_version: "1.0.0", category, seller_id?, product_id?, listing_id?, purchase_id?, description}`; `description` is the person's own words, up to 2000 characters. |

Returns:

- `report_id`: The report, for the person's records.
- `replayed`: `true` when the same key answered an earlier report.
- `reporting`: The marketplace's email address and telephone number, for reporting by other means; `null` until registered.

- A report changes no order, refund or listing on its own; the operator reviews it. Never promise an outcome.
- Send only what the person said about the activity; never a transcript, and never their own contact details, which the credential already identifies.
