Item Retrieval

This section details the Model Context Protocol (MCP) tools for retrieving product information. These tools allow agents to fetch full product records or group variant details from the catalog.

get_item MCP tool

Retrieves the full record for a single product. This tool is ideal for fetching detailed information about a specific product variant after it has been identified through search or a product group listing.

Purpose

Returns the full record for a single item, addressed by its ID. This is the detail counterpart to get_item_group: get_item_group lists the variants of a product (the matrix and the attributes that vary), and get_item returns one chosen variant’s complete record — its id, entity_type, images, and attributes. Pass an id from a search result or from a get_item_group member; optionally pass columns to restrict the returned attributes. The response carries no siblings and no preferred_image; an unknown ID yields item: null. To resolve several IDs in one call, use get_items, the batch sibling.

Request: GetItemRequest

{
  "properties": {
    "columns": {
      "description": "Catalog columns to materialize into the item's `attributes`. Omit for the full set of columns visible here; a requested column outside that set is ignored rather than returned.",
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "id": {
      "description": "The merchant's product id whose full record to return. This is the same `id` carried on a search result and on each member of a `get_item_group` response.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "GetItemRequest",
  "type": "object"
}

Response: GetItemResponse

{
  "properties": {
    "item": {
      "anyOf": [
        {
          "$ref": "#/$defs/McpItem"
        },
        {
          "type": "null"
        }
      ],
      "description": "The full record for the requested product, or `null` when no product has that id. Carries the product's `id`, `entity_type`, image gallery, and its `attributes`; it never carries `siblings` or a `preferred_image`. To list the product's variants, call `get_item_group`."
    }
  },
  "title": "GetItemResponse",
  "type": "object"
}

The McpItem definition is located in Model Context Protocol Data Types.

get_items MCP tool

Retrieves full records for multiple products in a single batch request. This is useful for fetching details for a list of products obtained from search results or product group listings.

Purpose

Returns the full records for multiple items, addressed by a list of IDs — the batch sibling of get_item. Pass up to 100 ids (from search results or get_item_group members); each resolves to one record in items, carrying its id, entity_type, images, and attributes, exactly as get_item returns for a single ID. Optionally pass columns to restrict the returned attributes, applied uniformly to every item. Duplicate IDs are collapsed, and an ID with no matching product is listed in missing (omitted when every ID resolves) rather than failing the call. The records carry no siblings and no preferred_image; to list a product’s variants, use get_item_group.

Request: GetItemsRequest

{
  "properties": {
    "columns": {
      "description": "Catalog columns to materialize into each item's `attributes`. Omit for the full set of columns visible here; a requested column outside that set is ignored rather than returned. Applies uniformly to every returned item.",
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "ids": {
      "description": "The merchant product ids whose full records to return — the batch form of `get_item`'s `id`. Each is the same `id` carried on a search result and on every member of a `get_item_group` response. At most 100 ids per request; duplicate ids are collapsed; an id with no matching product is reported in `missing`.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "ids"
  ],
  "title": "GetItemsRequest",
  "type": "object"
}

Response: GetItemsResponse

{
  "properties": {
    "items": {
      "description": "The resolved products, one full record per matched id, in request order (first occurrence). Each carries the product's `id`, `entity_type`, image gallery, and its `attributes`; like `get_item` it never carries `siblings` or a `preferred_image`. Ids that matched no product are listed in `missing`.",
      "items": {
        "$ref": "#/$defs/McpItem"
      },
      "type": "array"
    },
    "missing": {
      "description": "The requested ids that matched no product, deduplicated and in request order. Omitted entirely when every requested id resolved.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "GetItemsResponse",
  "type": "object"
}

The McpItem definition is located in Model Context Protocol Data Types.

get_item_group MCP tool

Retrieves the complete set of variants for a given item group ID, presented as a variant matrix. This tool helps in understanding the full range of product options available within a group.

Purpose

Returns every member of the item group designated by the item_group_id. Use it to answer “which variants of this product exist?”. The response is a matrix, not full records: attributes holds the group-constant item_group_* columns (e.g., item_group_title, item_group_link); options lists the attributes that vary and their distinct values; items is every member, slimmed to its varying-attribute values plus images. Full per-item detail (description, title, price, …) comes from get_item.

Request: GetItemGroupRequest

{
  "properties": {
    "item_group_id": {
      "description": "The merchant's item-group id whose complete set of variants to return. This is the same `item_group_id` carried on a search result and inside a result's `siblings`.",
      "type": "string"
    }
  },
  "required": [
    "item_group_id"
  ],
  "title": "GetItemGroupRequest",
  "type": "object"
}

Response: GetItemGroupResponse

{
  "properties": {
    "attributes": {
      "additionalProperties": true,
      "description": "Attributes shared by every member of the group — constant across the variants — under their own (prefixed) names, e.g. `item_group_title`, `item_group_link`. Distinct from each item's own `attributes`, which carry that variant's varying-attribute values. Absent when the catalog holds no such group-level columns.",
      "type": "object"
    },
    "item_group_id": {
      "description": "The merchant's item-group id, echoed from the request — the key every member of this group shares.",
      "type": "string"
    },
    "items": {
      "description": "Every member of the group, including the one you already have — the complete set of variants. Each member carries only the attributes that vary across the group plus its images; for full per-item detail, use `get_item`.",
      "items": {
        "$ref": "#/$defs/McpItem"
      },
      "type": "array"
    },
    "options": {
      "description": "The attributes that vary across the group, each with the distinct values it takes (for example `color: [red, blue]`) — a summary of the variation, not a matrix of the combinations that exist. May be empty.",
      "items": {
        "$ref": "#/$defs/McpVaryingAttribute"
      },
      "type": "array"
    }
  },
  "required": [
    "item_group_id",
    "items"
  ],
  "title": "GetItemGroupResponse",
  "type": "object"
}

The McpItem and McpVaryingAttribute definitions are located in Model Context Protocol Data Types.