Catalogs tools

search_discovery_catalogs: List the catalogs in your account, or fetch one by name.
get_discovery_catalog_config: Get a catalog's attribute configuration.
search_discovery_catalog_products: List the products in a catalog, or fetch one by ID.
search_discovery_catalog_product_variants: List the variants for a product, or fetch one by ID.
search_discovery_catalog_jobs: List the feed and index jobs for a catalog, or fetch one by ID.
get_discovery_catalog_reserved_attributes: Get the reserved attribute names for a catalog.

search_discovery_catalogs

Searches the catalogs in your account, or fetches one by name. A catalog holds the products and variants that power search and category pages. Omit catalog_name to list all catalogs, each with its name, language, environment (production or staging), and statistics such as document counts and index refresh timestamps.

Pass catalog_name to fetch a single catalog's details, including its statistics, properties, and Data hub properties for the chosen environment. The catalog name is required by most other catalog tools, so start here. Set account_name if you have access to more than one account.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str \| null`	No	The catalog name. Omit to list all catalogs; provide to fetch one.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`. Only applies when `catalog_name` is set.

Response parameters

The tool returns a DiscoveryCatalogsResponse when catalog_name is omitted, or a DiscoveryCatalogResponse when it's provided.

The DiscoveryCatalogsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogSummary]`	The catalogs in your account.
`error`	`str \| null`	Error message if the request failed.

The DiscoveryCatalogResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogSummary \| null`	The catalog details.
`error`	`str \| null`	Error message if the request failed.

The CatalogSummary object has the following fields:

Field	Type	Description
`name`	`str`	The catalog name. Pass this to the other catalog tools.
`language`	`str \| null`	The catalog language code, for example `en`.
`environment`	`str \| null`	The environment: `production` or `staging`.
`stats`	`CatalogStats \| null`	Catalog statistics: document counts and index timestamps.
`properties`	`any \| null`	Catalog properties.
`data_hub_properties`	`any \| null`	Data hub integration properties.

The CatalogStats object has the following fields:

Field	Type	Description
`last_index_refresh_at`	`str \| null`	ISO timestamp of the last index refresh.
`last_keyword_suggest_refresh_at`	`str \| null`	ISO timestamp of the last keyword suggest refresh.
`product_doc_count`	`int \| null`	The number of product documents.
`product_doc_byte_count`	`int \| null`	The size of product documents, in bytes.
`variant_doc_byte_count`	`int \| null`	The size of variant documents, in bytes.
`catalog_searchable_byte_count`	`int \| null`	The size of searchable catalog data, in bytes.
`catalog_displayable_byte_count`	`int \| null`	The size of displayable catalog data, in bytes.
`catalog_facetable_manual_byte_count`	`int \| null`	The size of manually-facetable catalog data, in bytes.
`catalog_facetable_auto_byte_count`	`int \| null`	The size of auto-facetable catalog data, in bytes.

get_discovery_catalog_config

Returns the latest attribute configuration for a catalog. The configuration defines which attributes are searchable, displayable, facetable (manual and auto), and sortable. Use it to understand what attributes a catalog exposes and how they're set up for search and merchandising.

The configuration is a large freeform JSON object. Use search_discovery_catalogs to find catalog names.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name, for example `ucg_automation_com`.
`environment`	`str`	No	The environment: `production` or `staging`. Defaults to `production`.

Response parameters

The tool returns a DiscoveryCatalogConfigResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The catalog configuration, as freeform JSON: searchable, displayable, facetable, and sortable attribute definitions.
`error`	`str \| null`	Error message if the request failed.

search_discovery_catalog_products

Searches the products in a catalog, or fetches one by ID. Omit product_id to list products: paginated records, each with the product ID, its attribute key-value pairs, and a variant count. Pages are 1-based, so the first page is 1.

Pass product_id to fetch a single product's full attribute set and variant count. Use search_discovery_catalog_product_variants to list a product's variants.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `search_discovery_catalogs`.
`product_id`	`str \| null`	No	The product ID. Omit to list all products; provide to fetch one.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`. Ignored when `product_id` is set.
`limit`	`int`	No	Results per page. Defaults to `10`. Ignored when `product_id` is set.

Response parameters

The tool returns a DiscoveryCatalogProductsResponse when product_id is omitted, or a DiscoveryCatalogProductResponse when it's provided.

The DiscoveryCatalogProductsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogProduct]`	The products in the catalog.
`count`	`int \| null`	The total number of products.
`error`	`str \| null`	Error message if the request failed.

The DiscoveryCatalogProductResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogProduct \| null`	The product details.
`error`	`str \| null`	Error message if the request failed.

The CatalogProduct object has the following fields:

Field	Type	Description
`id`	`str`	The product ID.
`attributes`	`dict \| null`	The product's attribute key-value pairs.
`variant_record_count`	`int \| null`	The number of variants for this product.

search_discovery_catalog_product_variants

Searches the variants for a product in a catalog, or fetches one by ID. Omit variant_id to list variants: paginated records, each with the variant ID and its attribute key-value pairs. Pages are 1-based, so the first page is 1.

Pass variant_id to fetch a single variant's full attribute set. Use search_discovery_catalog_products to find product IDs.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `search_discovery_catalogs`.
`product_id`	`str`	Yes	The product ID returned by `search_discovery_catalog_products`.
`variant_id`	`str \| null`	No	The variant ID. Omit to list all variants; provide to fetch one.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`. Ignored when `variant_id` is set.
`limit`	`int`	No	Results per page. Defaults to `10`. Ignored when `variant_id` is set.

Response parameters

The tool returns a DiscoveryCatalogVariantsResponse when variant_id is omitted, or a DiscoveryCatalogVariantResponse when it's provided.

The DiscoveryCatalogVariantsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogVariant]`	The variants for the product.
`count`	`int \| null`	The total number of variants.
`error`	`str \| null`	Error message if the request failed.

The DiscoveryCatalogVariantResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogVariant \| null`	The variant details.
`error`	`str \| null`	Error message if the request failed.

The CatalogVariant object has the following fields:

Field	Type	Description
`id`	`str`	The variant ID.
`attributes`	`dict \| null`	The variant's attribute key-value pairs.

search_discovery_catalog_jobs

Searches the feed and index jobs for a catalog, or fetches one by ID. Jobs process catalog feeds and rebuild the search index. Omit job_id to list jobs: paginated records, each with the job status, type, timestamps, and document-count statistics. Filter by status, visibility, or a creation-date range. Pages are 1-based, so the first page is 1.

Pass job_id to fetch a single job's full details, including its status, timestamps, properties, and statistics. To find jobs that failed, set status to failure.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `search_discovery_catalogs`.
`job_id`	`str \| null`	No	The job ID. Omit to list all jobs; provide to fetch one.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`. Ignored when `job_id` is set.
`limit`	`int`	No	Results per page. Defaults to `50`. Ignored when `job_id` is set.
`status`	`str \| null`	No	Status filter: `running`, `queued`, `success`, `failure`, `failed`, `killed`, or `skipped`. Ignored when `job_id` is set.
`visibility`	`str \| null`	No	Visibility filter: `external`, `internal`, or `all`. Ignored when `job_id` is set.
`created_at_min`	`str \| null`	No	ISO 8601 timestamp lower bound for the job creation date. Ignored when `job_id` is set.
`created_at_max`	`str \| null`	No	ISO 8601 timestamp upper bound for the job creation date. Ignored when `job_id` is set.

Response parameters

The tool returns a DiscoveryCatalogJobsResponse when job_id is omitted, or a DiscoveryCatalogJobResponse when it's provided.

The DiscoveryCatalogJobsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogJob]`	The feed and index jobs for the catalog.
`count`	`int \| null`	The total number of jobs.
`error`	`str \| null`	Error message if the request failed.

The DiscoveryCatalogJobResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogJob \| null`	The job details.
`error`	`str \| null`	Error message if the request failed.

The CatalogJob object has the following fields:

Field	Type	Description
`id`	`str`	The job ID.
`type`	`str \| null`	The job type: `feed`, `index`, or `suggest`.
`status`	`str \| null`	The job status: `running`, `queued`, `success`, `failure`, `failed`, `killed`, or `skipped`.
`status_message`	`str \| null`	A human-readable status message.
`created_at`	`str \| null`	ISO timestamp of when the job was created.
`started_at`	`str \| null`	ISO timestamp of when the job started.
`stopped_at`	`str \| null`	ISO timestamp of when the job stopped.
`visibility`	`str \| null`	The job visibility: `external`, `internal`, or `all`.
`properties`	`JobProperties \| null`	Job properties: feed type, mode, and input source.
`stats`	`JobStats \| null`	Job statistics: document counts.

The JobProperties object has the following fields:

Field	Type	Description
`feed_data_type`	`str \| null`	The feed data type: `products`, `ae`, `qd`, `ltr`, or `product_vectors`.
`feed_mode`	`str \| null`	The feed mode: `full` or `delta`.
`input_source`	`str \| null`	The input source: `sftp_file_upload` or `api_request_body`.
`input_filenames`	`list[str] \| null`	The input file names.
`config_etag`	`str \| null`	The config ETag at the time the job ran.
`index_mode`	`str \| null`	The index mode: `update`, `refresh`, or `export`.
`ignore_count_drop`	`bool \| null`	Whether count-drop protection was bypassed.

The JobStats object has the following fields:

Field	Type	Description
`patch_operation_count`	`int \| null`	The number of patch operations.
`product_doc_count`	`int \| null`	The number of product documents processed.
`variant_doc_count`	`int \| null`	The number of variant documents processed.
`search_variant_count`	`int \| null`	The number of search variant documents.
`search_product_count`	`int \| null`	The number of search product documents.
`deleted_parent_count`	`int \| null`	The number of deleted parent documents.

get_discovery_catalog_reserved_attributes

Returns the reserved attribute names for a catalog. Reserved attributes are system-defined names that you can't use as custom attribute names in a catalog feed. Using a reserved name as a custom attribute causes feed ingestion errors.

Check this list before you add new attributes to your feed to avoid naming conflicts. Use search_discovery_catalogs to find catalog names.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name, for example `ucg_automation_com`.
`environment`	`str`	No	The environment: `production` or `staging`. Defaults to `production`.

Response parameters

The tool returns a DiscoveryReservedAttributesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The reserved attribute names, as freeform JSON.
`error`	`str \| null`	Error message if the request failed.