Skip to main content
Glama

Search listings

simpleSearchProductListings
Read-onlyIdempotent

Search Aura Historia's index of art, antiques and design objects listed by dealers, auction houses, marketplaces and auction platforms. Use it to find listings by text and by filters such as price, dates, availability, provider, auction, location and shipping. Returns listing summaries in the requested language and currency, with the total when known; pass the returned searchAfter object unchanged to get the next page. For a signed-in user, each result also carries userState sections for which the token has the read scope: watchlist:read, search-filters:read, notifications:read or users:read. Each result's viewLink.url is the provider link meant to be shared with people: it carries Aura Historia's referral tagging, which is lost when its query parameters are changed. viewLink.affiliate is true when that link is an affiliate link, which can earn Aura Historia a commission. url is the provider's untagged address. Amounts are always integers in the currency's minor unit when one exists (EUR 119199 = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (211453 = ¥211,453). Follow ISO 4217 exponents.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "simpleSearchProductListings"
  }
}

Input Schema

NameRequiredDescriptionDefault
sizeNoNumber of results per page, from 1 to 100 (default 21); values outside that range are clamped.
sortNoField to order results by: `score` (relevance), `updated` or `created`; cannot be combined with `geography.distanceOrder`.
orderNoSort direction, `asc` or `desc` (default `desc`); only valid together with `sort`.
priceNoPrice range in the request's `currency`, with both bounds inclusive. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents.
createdNoRange on the listing's creation time, as ISO 8601 date-times with offset; both bounds inclusive.
updatedNoRange on the listing's last update time, as ISO 8601 date-times with offset; both bounds inclusive.
currencyNoCurrency prices are returned in and `price` is interpreted in, as an ISO 4217 code (default `EUR`).EUR
languageNoLanguage of the returned listing text and of the titles `productQuery` is matched against, as an ISO 639-1 code (default `en`).en
shippingNoOnly listings whose advertised shipping terms meet these conditions for a destination country; every member given must hold.
auctionIdNoOnly listings that belong to these auctions, given as auction IDs (`auc_…`).
geographyNoWhere listings are located, by country, subdivision or distance from a point; every member given must hold.
searchAfterNoContinuation from the previous page: pass back exactly as returned by the previous page, with the same filters and sort.
availabilityNoOnly listings in one of these exact availability states; combined with `orderability`, a listing must satisfy both.
orderabilityNoOnly listings whose availability falls into one of these orderability groups; combined with `availability`, a listing must satisfy both.
productQueryNoKeyword phrases matched against listing titles; every word of one phrase must match, and a listing matches when any phrase does.
listingSourceIdNoOnly listings from these providers, given as listing source IDs (`ls_…`).
lotBiddingOpensNoRange on the time bidding on the lot opens, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive.
lotScheduledClosesNoRange on the lot's scheduled closing time, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive.
excludeListingSourceIdNoLeave out listings from these providers, given as listing source IDs (`ls_…`).
excludeProductListingIdNoListing IDs (`pl_…`) to leave out of the results.
enhancedSearchDescriptionNoOptional natural-language description that refines the ranking of `productQuery` results. Only effective together with `productQuery`; on its own it returns unranked, unrelated results.
includeUnspecifiedAvailabilityNoAlso include listings that state no availability (default false).

Output Schema

NameRequiredDescriptionDefault
sizeYes
itemsYes
totalNo
searchAfterNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedOutput schema / $defs / ProductListingSummaryData / properties / url / description
      Previous value: -"The provider's own address, without Aura Historia's referral tagging; `viewUrl` is the link meant to be shared."New value: +"The provider's own address, without Aura Historia's referral tagging; `viewLink.url` is the link meant to be shared."
    • addedOutput schema / $defs / ProductListingSummaryData / properties / viewLink
      Added value: +{
      +  "$ref": "#/$defs/ViewLinkData",
      +  "description": "The link to the provider's page that is meant to be shared with people, and whether it is an affiliate link."
      +}
    • removedOutput schema / $defs / ProductListingSummaryData / properties / viewUrl
      Removed value: -{
      -  "description": "Link to the provider's page that is meant to be shared with people. It carries Aura Historia's referral tagging, which is lost when its query parameters are changed.",
      -  "format": "uri",
      -  "type": "string"
      -}
    • changedOutput schema / $defs / ProductListingSummaryData / required
      Previous value: -[
      -  "productListingId",
      -  "eventId",
      -  "source",
      -  "sourceListingId",
      -  "priceValuation",
      -  "lifecycle",
      -  "url",
      -  "viewUrl",
      -  "updated"
      -]New value: +[
      +  "productListingId",
      +  "eventId",
      +  "source",
      +  "sourceListingId",
      +  "priceValuation",
      +  "lifecycle",
      +  "url",
      +  "viewLink",
      +  "updated"
      +]
    • addedOutput schema / $defs / ViewLinkData
      Added value: +{
      +  "description": "The provider link meant to be shared with people, paired with whether it is an affiliate link.",
      +  "properties": {
      +    "affiliate": {
      +      "description": "`true` when `url` is an affiliate link, which can earn Aura Historia a commission when people follow it. `false` when it carries only Aura Historia's tracking parameters or leads to Aura Historia itself.",
      +      "type": "boolean"
      +    },
      +    "url": {
      +      "description": "Link to the provider's page that is meant to be shared with people. It carries Aura Historia's referral tagging, which is lost when its query parameters are changed.",
      +      "format": "uri",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "url",
      +    "affiliate"
      +  ],
      +  "type": "object"
      +}
  2. Changed6 schema fields changed
    • addedOutput schema / $defs / ListingSourceSummaryData / properties / operator
      Added value: +{
      +  "$ref": "#/$defs/PublicListingSourceOperatorData"
      +}
    • changedOutput schema / $defs / ListingSourceSummaryData / required
      Previous value: -[
      -  "listingSourceId",
      -  "name",
      -  "slugId"
      -]New value: +[
      +  "listingSourceId",
      +  "name",
      +  "slugId",
      +  "operator"
      +]
    • addedOutput schema / $defs / ProductListingSummaryData / properties / image
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/ProductListingImageData"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • removedOutput schema / $defs / ProductListingSummaryData / properties / images
      Removed value: -{
      -  "items": {
      -    "$ref": "#/$defs/ProductListingImageData"
      -  },
      -  "type": "array"
      -}
    • changedOutput schema / $defs / ProductListingSummaryData / required
      Previous value: -[
      -  "productListingId",
      -  "eventId",
      -  "source",
      -  "sourceListingId",
      -  "priceValuation",
      -  "lifecycle",
      -  "url",
      -  "viewUrl",
      -  "images",
      -  "updated"
      -]New value: +[
      +  "productListingId",
      +  "eventId",
      +  "source",
      +  "sourceListingId",
      +  "priceValuation",
      +  "lifecycle",
      +  "url",
      +  "viewUrl",
      +  "updated"
      +]
    • addedOutput schema / $defs / PublicListingSourceOperatorData
      Added value: +{
      +  "description": "The Party that operates a ListingSource, as shown wherever a source is presented publicly.",
      +  "properties": {
      +    "name": {
      +      "type": "string"
      +    },
      +    "partner": {
      +      "description": "`true` while the operator Party has an active Aura Historia Partnership, otherwise\n`false`, including after a Partnership is dissolved. Unrelated to ingestion methods and\nreferral configuration.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "partner"
      +  ],
      +  "type": "object"
      +}
  3. Changed2 schema fields changed
    • addedOutput schema / $defs / ProductListingSummaryData / properties / url / description
      Added value: +"The provider's own address, without Aura Historia's referral tagging; `viewUrl` is the link meant to be shared."
    • addedOutput schema / $defs / ProductListingSummaryData / properties / viewUrl / description
      Added value: +"Link to the provider's page that is meant to be shared with people. It carries Aura Historia's referral tagging, which is lost when its query parameters are changed."
  4. Changed48 schema fields changed
    • addedInput schema / $defs / AmountData / properties / amount / description
      Added value: +"Amount as an integer in the currency's minor unit (EUR cents; JPY whole yen)."
    • addedInput schema / $defs / AmountData / properties / currency / description
      Added value: +"ISO 4217 code of the currency the amount is in."
    • addedInput schema / $defs / DateRangeSchema / properties / max / description
      Added value: +"End of the range, as an ISO 8601 date-time with offset."
    • addedInput schema / $defs / DateRangeSchema / properties / min / description
      Added value: +"Start of the range, as an ISO 8601 date-time with offset."
    • changedInput schema / $defs / DestinationData / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "kind": {
      -        "const": "NONE",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "country": {
      -        "type": "string"
      -      },
      -      "kind": {
      -        "const": "COUNTRY",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "country"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "description": "No destination country.",
      +    "properties": {
      +      "kind": {
      +        "const": "NONE",
      +        "description": "Selects this variant; always `NONE` here.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "A destination country.",
      +    "properties": {
      +      "country": {
      +        "description": "ISO 3166-1 alpha-2 country code.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "const": "COUNTRY",
      +        "description": "Selects this variant; always `COUNTRY` here.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "country"
      +    ],
      +    "type": "object"
      +  }
      +]
    • addedInput schema / $defs / GeographicSearchData / properties / countries / description
      Added value: +"ISO 3166-1 alpha-2 country codes, at most 100; a listing matches when it is located in any of them."
    • addedInput schema / $defs / GeographicSearchData / properties / distanceOrder / description
      Added value: +"Order results by distance from `origin`, `ASC` (nearest first) or `DESC`; requires `origin`."
    • addedInput schema / $defs / GeographicSearchData / properties / mode / description
      Added value: +"Which locations count when measuring distance: `STRICT` (default) only exact premises, `APPROXIMATE` also street, locality and representative points; `APPROXIMATE` needs `origin` with `radius` or `distanceOrder`."
    • addedInput schema / $defs / GeographicSearchData / properties / origin / description
      Added value: +"Point that `radius` and `distanceOrder` measure from; required by either of them."
    • changedInput schema / $defs / GeographicSearchData / properties / radius / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "amount": {
      -        "type": "number"
      -      },
      -      "unit": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "amount",
      -      "unit"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "amount": {
      +        "description": "Distance in `unit`; greater than 0.",
      +        "type": "number"
      +      },
      +      "unit": {
      +        "description": "Unit of `amount`: one of MILES, YARDS, FEET, INCHES, KILOMETERS, METERS, CENTIMETERS, MILLIMETERS, NAUTICAL_MILES.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "amount",
      +      "unit"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / $defs / GeographicSearchData / properties / radius / description
      Added value: +"Only listings within this distance of `origin`, at most 20,000 km."
    • addedInput schema / $defs / GeographicSearchData / properties / subdivisions / description
      Added value: +"ISO 3166-2 subdivision codes, at most 100, that belong to `countries` when those are given; a listing matches when it is located in any of them."
    • addedInput schema / $defs / NumberRangeSchema / properties / max / description
      Added value: +"Highest price to include, as an integer amount in the currency's minor unit."
    • addedInput schema / $defs / NumberRangeSchema / properties / min / description
      Added value: +"Lowest price to include, as an integer amount in the currency's minor unit."
    • addedInput schema / $defs / OriginData / properties / latitude / description
      Added value: +"Latitude in decimal degrees."
    • addedInput schema / $defs / OriginData / properties / longitude / description
      Added value: +"Longitude in decimal degrees."
    • addedInput schema / $defs / ProductListingSearchCursorInputData / properties / fxRateId / description
      Added value: +"Exchange-rate snapshot ID (`fx_…`) from the previous page's `searchAfter`, passed back unchanged."
    • changedInput schema / $defs / ProductListingSearchCursorInputData / properties / searchAfter
      Previous value: -trueNew value: +{
      +  "description": "Opaque sort values from the previous page's `searchAfter`, passed back unchanged."
      +}
    • addedInput schema / $defs / ShippingSearchData / properties / collectionOffered / description
      Added value: +"Only listings that offer collection in person; the only shipping condition that works without a destination country."
    • addedInput schema / $defs / ShippingSearchData / properties / destination / description
      Added value: +"Country the listing must ship to, as `{\"kind\":\"COUNTRY\",\"country\":\"DE\"}`; `{\"kind\":\"NONE\"}` sets no destination."
    • addedInput schema / $defs / ShippingSearchData / properties / interpretation / description
      Added value: +"`WHOLE_COUNTRY_PER_ITEM_V1` (default) or `WHOLE_COUNTRY_PER_ITEM_FX_V1`, which values `maximumPerItem` in its own currency at the request's exchange rates and requires `maximumPerItem`."
    • addedInput schema / $defs / ShippingSearchData / properties / maximumPerItem / description
      Added value: +"Highest acceptable shipping price per item, in the amount's own currency; requires a `destination` country. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents."
    • addedInput schema / $defs / ShippingSearchData / properties / referenceRelease / description
      Added value: +"Version of the ISO 3166 code list the country code comes from; `iso-codes-4.20.1` is the only accepted value and the default."
    • addedInput schema / $defs / ShippingSearchData / properties / service / description
      Added value: +"Shipping service code the terms must include, as free text of at most 128 characters; requires a `destination` country."
    • addedInput schema / properties / auctionId / description
      Added value: +"Only listings that belong to these auctions, given as auction IDs (`auc_…`)."
    • addedInput schema / properties / availability / description
      Added value: +"Only listings in one of these exact availability states; combined with `orderability`, a listing must satisfy both."
    • addedInput schema / properties / created / description
      Added value: +"Range on the listing's creation time, as ISO 8601 date-times with offset; both bounds inclusive."
    • addedInput schema / properties / currency / description
      Added value: +"Currency prices are returned in and `price` is interpreted in, as an ISO 4217 code (default `EUR`)."
    • addedInput schema / properties / enhancedSearchDescription / description
      Added value: +"Optional natural-language description that refines the ranking of `productQuery` results. Only effective together with `productQuery`; on its own it returns unranked, unrelated results."
    • addedInput schema / properties / excludeListingSourceId / description
      Added value: +"Leave out listings from these providers, given as listing source IDs (`ls_…`)."
    • addedInput schema / properties / excludeProductListingId / description
      Added value: +"Listing IDs (`pl_…`) to leave out of the results."
    • addedInput schema / properties / geography / description
      Added value: +"Where listings are located, by country, subdivision or distance from a point; every member given must hold."
    • addedInput schema / properties / includeUnspecifiedAvailability / description
      Added value: +"Also include listings that state no availability (default false)."
    • addedInput schema / properties / language / description
      Added value: +"Language of the returned listing text and of the titles `productQuery` is matched against, as an ISO 639-1 code (default `en`)."
    • addedInput schema / properties / listingSourceId / description
      Added value: +"Only listings from these providers, given as listing source IDs (`ls_…`)."
    • addedInput schema / properties / lotBiddingOpens / description
      Added value: +"Range on the time bidding on the lot opens, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive."
    • addedInput schema / properties / lotScheduledCloses / description
      Added value: +"Range on the lot's scheduled closing time, as ISO 8601 date-times with offset; `min` inclusive, `max` exclusive."
    • addedInput schema / properties / order / description
      Added value: +"Sort direction, `asc` or `desc` (default `desc`); only valid together with `sort`."
    • addedInput schema / properties / orderability / description
      Added value: +"Only listings whose availability falls into one of these orderability groups; combined with `availability`, a listing must satisfy both."
    • addedInput schema / properties / price / description
      Added value: +"Price range in the request's `currency`, with both bounds inclusive. Amounts are always integers in the currency's minor unit when one exists (EUR `119199` = €1,191.99; USD in cents). For currencies without minor units, such as JPY, the amount is whole units (`211453` = ¥211,453). Follow ISO 4217 exponents."
    • addedInput schema / properties / productQuery / description
      Added value: +"Keyword phrases matched against listing titles; every word of one phrase must match, and a listing matches when any phrase does."
    • addedInput schema / properties / searchAfter / description
      Added value: +"Continuation from the previous page: pass back exactly as returned by the previous page, with the same filters and sort."
    • addedInput schema / properties / shipping / description
      Added value: +"Only listings whose advertised shipping terms meet these conditions for a destination country; every member given must hold."
    • changedInput schema / properties / size / description
      Previous value: -"Values are clamped to the existing service-supported range 1..=100."New value: +"Number of results per page, from 1 to 100 (default 21); values outside that range are clamped."
    • addedInput schema / properties / sort / description
      Added value: +"Field to order results by: `score` (relevance), `updated` or `created`; cannot be combined with `geography.distanceOrder`."
    • addedInput schema / properties / updated / description
      Added value: +"Range on the listing's last update time, as ISO 8601 date-times with offset; both bounds inclusive."
    • addedOutput schema / $defs / OriginData / properties / latitude / description
      Added value: +"Latitude in decimal degrees."
    • addedOutput schema / $defs / OriginData / properties / longitude / description
      Added value: +"Longitude in decimal degrees."
  5. Changed4 schema fields changed
    • addedInput schema / properties / created / type
      Added value: +"object"
    • addedInput schema / properties / lotBiddingOpens / type
      Added value: +"object"
    • addedInput schema / properties / lotScheduledCloses / type
      Added value: +"object"
    • addedInput schema / properties / updated / type
      Added value: +"object"
  6. Changed2 schema fields changed
    • changedInput schema / properties / language / enum
      Previous value: -[
      -  "de",
      -  "en",
      -  "fr",
      -  "es",
      -  "it",
      -  "zh",
      -  "pt",
      -  "pl",
      -  "tr",
      -  "nl",
      -  "cs",
      -  "ja",
      -  "ru",
      -  "ar",
      -  "de-DE",
      -  "de-AT",
      -  "de-CH",
      -  "de-LU",
      -  "de-LI",
      -  "en-US",
      -  "en-GB",
      -  "en-AU",
      -  "en-CA",
      -  "en-NZ",
      -  "en_IE",
      -  "fr-FR",
      -  "fr-CA",
      -  "fr-BE",
      -  "fr-CH",
      -  "fr-LU",
      -  "es-ES",
      -  "es-MX",
      -  "es-AR",
      -  "es-CO",
      -  "es-CL",
      -  "es-PE",
      -  "es-VE",
      -  "it-IT",
      -  "it-CH",
      -  "zh-CN",
      -  "zh-Hans",
      -  "pt-PT",
      -  "pt-BR",
      -  "pl-PL",
      -  "tr-TR",
      -  "nl-NL",
      -  "nl-BE",
      -  "cs-CZ",
      -  "ja-JP",
      -  "ru-RU",
      -  "ar-SA",
      -  "ar-EG",
      -  "ar-AE"
      -]New value: +[
      +  "de",
      +  "en",
      +  "fr",
      +  "es",
      +  "it",
      +  "zh",
      +  "pt",
      +  "pl",
      +  "tr",
      +  "nl",
      +  "cs",
      +  "ja",
      +  "ru",
      +  "ar",
      +  "ko",
      +  "el",
      +  "he",
      +  "th",
      +  "hi",
      +  "de-DE",
      +  "de-AT",
      +  "de-CH",
      +  "de-LU",
      +  "de-LI",
      +  "en-US",
      +  "en-GB",
      +  "en-AU",
      +  "en-CA",
      +  "en-NZ",
      +  "en_IE",
      +  "fr-FR",
      +  "fr-CA",
      +  "fr-BE",
      +  "fr-CH",
      +  "fr-LU",
      +  "es-ES",
      +  "es-MX",
      +  "es-AR",
      +  "es-CO",
      +  "es-CL",
      +  "es-PE",
      +  "es-VE",
      +  "it-IT",
      +  "it-CH",
      +  "zh-CN",
      +  "zh-Hans",
      +  "zh-TW",
      +  "zh-Hant",
      +  "zh-HK",
      +  "pt-PT",
      +  "pt-BR",
      +  "pl-PL",
      +  "tr-TR",
      +  "nl-NL",
      +  "nl-BE",
      +  "cs-CZ",
      +  "ja-JP",
      +  "ru-RU",
      +  "ar-SA",
      +  "ar-EG",
      +  "ar-AE",
      +  "ko-KR",
      +  "el-GR",
      +  "he-IL",
      +  "th-TH",
      +  "hi-IN"
      +]
    • changedOutput schema / $defs / LocalizedTextData / properties / language / enum
      Previous value: -[
      -  "de",
      -  "en",
      -  "fr",
      -  "es",
      -  "it",
      -  "zh",
      -  "pt",
      -  "pl",
      -  "tr",
      -  "nl",
      -  "cs",
      -  "ja",
      -  "ru",
      -  "ar"
      -]New value: +[
      +  "de",
      +  "en",
      +  "fr",
      +  "es",
      +  "it",
      +  "zh",
      +  "pt",
      +  "pl",
      +  "tr",
      +  "nl",
      +  "cs",
      +  "ja",
      +  "ru",
      +  "ar",
      +  "ko",
      +  "el",
      +  "he",
      +  "th",
      +  "hi"
      +]
  7. Changed4 schema fields changed
    • addedOutput schema / $defs / ListingTextData
      Added value: +{
      +  "description": "A listing text as the source published it and as shown for the requested language.",
      +  "properties": {
      +    "localized": {
      +      "$ref": "#/$defs/LocalizedTextData",
      +      "description": "Text to show for the requested language. Chosen from the translations and the original in\nthe order requested language, `en`, `de`, then any other language, so it can be the\noriginal itself. Always present; compare its `language` with `original.language` to tell\nwhether the text was translated."
      +    },
      +    "original": {
      +      "anyOf": [
      +        {
      +          "$ref": "#/$defs/LocalizedTextData"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "Text as the source published it, normalized: styled letters and digits are presented as\nordinary text, emoji and ornamental symbols are removed and truncation ellipses remain\nstable. Omitted where the response does not carry the original, such as search and\nsimilar-listing summaries and notification payloads."
      +    }
      +  },
      +  "required": [
      +    "localized"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / $defs / ProductListingImageData / required
      Removed value: -[
      -  "url"
      -]
    • changedOutput schema / $defs / ProductListingSummaryData / properties / title / anyOf
      Previous value: -[
      -  {
      -    "$ref": "#/$defs/LocalizedTextData"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "$ref": "#/$defs/ListingTextData"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / $defs / ProductListingSummaryData / required
      Previous value: -[
      -  "productListingId",
      -  "eventId",
      -  "source",
      -  "sourceListingId",
      -  "priceValuation",
      -  "availability",
      -  "lifecycle",
      -  "url",
      -  "viewUrl",
      -  "images",
      -  "contentPolicy",
      -  "updated"
      -]New value: +[
      +  "productListingId",
      +  "eventId",
      +  "source",
      +  "sourceListingId",
      +  "priceValuation",
      +  "lifecycle",
      +  "url",
      +  "viewUrl",
      +  "images",
      +  "updated"
      +]
  8. First observed

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context: cursor pagination via an opaque searchAfter object, per-scope userState augmentation for signed-in users, referral tagging that is lost if viewLink query parameters are edited, the affiliate-commission meaning of viewLink.affiliate, and the distinction between the shareable provider link and the untagged url. That is real behavioral disclosure beyond structured fields, not repetition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: what is searched, then filters, then return shape, then result-field caveats. It is on the long side and paragraphs of currency minor-unit detail duplicate the schema's AmountData descriptions, but nearly every sentence contributes operational guidance rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value documentation is optional, and the description still usefully explains the userState, viewLink and url fields plus pagination. What is missing is comparative context — how this relates to the watchlist, similar-listings and single-listing tools that sit beside it in the catalog.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the 22-parameter envelope is thoroughly documented in-schema, including enum values and nested objects. The description adds little beyond it: the currency minor-unit rule and 'pass searchAfter unchanged' are both restated from the schema, and the filter parameters (price, dates, availability, provider, auction, location, shipping) are only named, not explained. Baseline 3 is right when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — searching an index of art, antiques and design objects listed by dealers, auction houses, marketplaces and auction platforms — plus the two supported search modes (text and filters). An agent can immediately tell this apart from retrieval siblings like getProductListing or getSimilarProductListings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use it to find listings by text and by filters such as price, dates, availability, provider, auction, location and shipping', which is a purpose restatement rather than routing guidance. It never names an alternative (e.g. getSimilarProductListings or getWatchlistProductListings) or states when not to use this tool, so the agent must infer that this is the broad discovery entry point.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources