Invitation-only demonstration. Sign-up is closed, everything shown is synthetic, and nothing can be bought. If you were invited, sign in with the account you were given. To ask about an invitation, write to support@clarypull.com.

Reference for AI agents

Clarypull for AI agents

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.

Identifiers, times, amounts and counts in the examples are illustrative.

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.

Connect and discover

  • Transport: MCP over Streamable HTTP at the deployment's connection address. The person copies it from Connect an agent 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 servesJSON-RPC
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
  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).
Read the fields of one category before constraining themclarypull_describe_catalog call · manifest 1.3.0 and later
{
  "name": "clarypull_describe_catalog",
  "arguments": {
    "country": "US",
    "categories": [
      "amazon.dishwasher"
    ],
    "limit": 50
  }
}
One attribute field from the answer: its type, units, coverage and rangeclarypull_describe_catalog result · manifest 1.3.0 and later
{
  "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.

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.

Exact search: every member under hard constraints, with facets and near missesclarypull_search_catalog call · manifest 1.3.0 and later
{
  "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
    }
  }
}
The complete first page of that searchclarypull_search_catalog result · manifest 1.3.0 and later
{
  "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.

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.
Admit products that leave one requirement unstated, after the person accepts unconfirmed fitclarypull_search_catalog call · manifest 1.3.0 and later
{
  "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"
  }
}

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.

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
{
  "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.

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
{
  "name": "clarypull_search_catalog",
  "arguments": {
    "ship_to": {
      "country": "US",
      "postal_code": "94110"
    },
    "where": {
      "field": "variant_family",
      "op": "eq",
      "value": "ASIN:ATVPDKIKX0DER:B0EXAMPL00"
    }
  }
}

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.
The next page: the identical request with the cursor the previous page returnedclarypull_search_catalog call · manifest 1.3.0 and later
{
  "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"
    }
  }
}
Every visible listing of one product, matching or not, fifty at a timeclarypull_get_catalog_product call · manifest 1.3.0 and later
{
  "name": "clarypull_get_catalog_product",
  "arguments": {
    "product_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
    "country": "US",
    "postal_code": "94110",
    "page_size": 50
  }
}

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.

Exploration by meaning: one bounded page of candidates, still under every hard constraintclarypull_search_catalog call · manifest 1.3.0 and later
{
  "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
    }
  }
}
What a ranked page says about its own coverageclarypull_search_catalog result · manifest 1.3.0 and later
{
  "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.

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.

Directory: the served categories, from the startclarypull_list_catalog_categories call · manifest 1.2.0 and later
{
  "name": "clarypull_list_catalog_categories",
  "arguments": {}
}
Directory: a category's products whose title, brand or model contain the wordsclarypull_find_catalog_products call · manifest 1.2.0 and later
{
  "name": "clarypull_find_catalog_products",
  "arguments": {
    "category": "amazon.dishwasher",
    "q": "EX-24B"
  }
}

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.

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
ToolRequestArguments over REST
clarypull_describe_catalogGET /v1/catalog/fieldscountry → query country; categories → query categories (one value, comma-separated); limit → query limit; after → query after
clarypull_search_catalogPOST /v1/catalog/searchevery argument → a JSON body member of the same name
clarypull_get_catalog_productGET /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_categoriesGET /v1/catalog/categoriesafter → query after
clarypull_find_catalog_productsGET /v1/catalog/productscategory → query category; q → query q; after → query after
clarypull_get_seller_disclosureGET /v1/sellers/{seller_id}/disclosureseller_id → path {seller_id}
clarypull_report_marketplace_activityPOST /v1/marketplace-reportsidempotency_key → header Idempotency-Key; request → the whole JSON body
Catalog search over REST: the body is the tool's arguments, unchangedREST request for clarypull_search_catalog · manifest 1.3.0 and later
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
  }
}
The field registry over REST: arguments in the query, categories comma-separatedREST request for clarypull_describe_catalog · manifest 1.3.0 and later
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

Tool reference

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
Arguments of clarypull_describe_catalog
ArgumentRequiredMeaning
countryyesDestination country (ISO 3166-1 alpha-2, for example US).
categoriesnoUp to 20 served categories to describe; all visible categories when absent.
limitnoAttribute fields per page, 1 to 200.
afternoThe 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.

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
Arguments of clarypull_search_catalog
ArgumentRequiredMeaning
ship_toyes{country, postal_code?}. The country decides which sellers and marketplaces apply; a postal code excludes sellers whose coverage does not reach it.
textnoUp 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_modenoall_terms (default), any_terms or phrase.
categoriesnoUp to 20 served categories.
wherenoHard constraints: a clause, or all / any / not over clauses, four levels and 64 nodes at most.
if_unknownnoexclude (default) or include, for every clause that does not set its own.
prefernoUp to 8 clauses that only add to the rank of the exact mode. Never a filter.
sortnoUp to 3 keys: relevance, price, delivery_latest, title or an attr.<key>, each asc or desc.
currencynoThe currency price sorting compares in, when the deployment has no single launch currency.
facetsnoUp to 16 fields to count values or numeric buckets for (unit, edges, limit, after).
pageno{size, cursor}: 1 to 100 products per page, and the previous page's next_cursor.
explainnonone, summary (default: each clause's status per listing) or full (also the stated values compared).
include_near_missesnoUp to 10 products kept out by exactly one clause, with the clause that failed.
retrievalno{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.

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
Arguments of clarypull_get_catalog_product
ArgumentRequiredMeaning
product_idyesA product_id from search or the directory.
countryyesDestination country.
postal_codenoUS ZIP code; limits listings to sellers whose coverage reaches it.
page_sizenoListings per page, 1 to 50 (default 20).
cursornoThe 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.

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
Arguments of clarypull_list_catalog_categories
ArgumentRequiredMeaning
afternoThe 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.

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
Arguments of clarypull_find_catalog_products
ArgumentRequiredMeaning
categoryyesA served category, as clarypull_list_catalog_categories names it.
qnoUp to 128 characters; empty lists every product of the category.
afternoThe 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.

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
Arguments of clarypull_get_seller_disclosure
ArgumentRequiredMeaning
seller_idyesThe 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.

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
Arguments of clarypull_report_marketplace_activity
ArgumentRequiredMeaning
idempotency_keyyesUnique per report; a retry with the same key and request answers the same receipt.
requestyes{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.