Product catalogs and recommendations tools

list_catalogs: List the catalogs in a project.
get_catalog: Get the field definitions for a catalog.
list_catalog_items: Search items inside a catalog.
get_catalog_item: Get a single item from a catalog by its item ID.
get_catalog_configuration: Get the attribute schema for a catalog.
list_catalog_jobs: List the import and update jobs for a catalog.
get_catalog_usages: See which campaigns and engines reference a catalog.
list_recommendations: List the recommendation engines in a project.
get_recommendation: Get the full configuration of a recommendation engine.

list_catalogs

Lists every v2 catalog in a project. Catalogs store product or generic data that's used for recommendations and personalization. The response gives you the name, display name, type (generic, product, or variant), and metadata. Field definitions are not included here — use get_catalog for those.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns a CatalogsResponse object with the following parameters:

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

The CatalogSummary object has the following fields:

Field	Type	Description
`id`	`str`	The catalog's unique ID.
`name`	`str`	The machine-readable catalog name (lowercase with underscores).
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	A description of the catalog.
`type`	`str \| null`	The catalog type: `generic`, `product`, or `variant`.
`created`	`any \| null`	Unix timestamp of when the catalog was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

get_catalog

Returns the full definition of a single catalog, including every field's name and data type.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.

Response parameters

The tool returns a CatalogResponse object with the following parameters:

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

The Catalog object adds the following field on top of the summary record:

Field	Type	Description
`fields`	`list[CatalogFieldDef]`	The field definitions for this catalog. Each entry has a `name`, a `type` (`string`, `number`, `boolean`, `date`, and so on), and a `searchable` flag.

list_catalog_items

Searches and lists items inside a catalog. Items are the Elasticsearch-backed records used for recommendations and Discovery. Each item is returned as a flat dictionary of field values keyed by field name. You can search across all fields or restrict the search to a specific field.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.
`query`	`str`	No	Search text. Defaults to an empty string. When `field` is not set, the search runs across all fields.
`field`	`str \| null`	No	A specific field name to search within. Omit to search all fields.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`count`	`int`	No	Number of items to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CatalogItemsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[dict[str, any]]`	The catalog items, each as a flat dictionary keyed by field name.
`total`	`int`	The total number of items in the catalog.
`matched`	`int`	The number of items matching the search query.
`limit`	`int`	The maximum number of items returned.
`skip`	`int`	The pagination offset that was applied.
`error`	`str \| null`	Error message if the request failed.

get_catalog_item

Returns a single item from a catalog by its item ID. The item is returned as a flat dictionary of field values; the item ID is in the _id field. If no item matches, success is false and the response includes an error message.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.
`item_id`	`str`	Yes	The item's ID, for example `A5` or `prod-12345`.

Response parameters

The tool returns a CatalogItemResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, any] \| null`	The catalog item fields as a flat dictionary. The item ID is in the `_id` field.
`error`	`str \| null`	Error message if the request failed or the item was not found.

get_catalog_configuration

Returns the attribute schema for a catalog: custom attributes the user has defined (with name, type, and the catalog column they map to) and reserved system attributes (such as product_id, title, and price). Also returns a configuration_hash you can use to detect schema drift between snapshots.

Returns a 404 if the catalog has no configuration yet, for example because no configuration-update job has run.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.

Response parameters

The tool returns a CatalogConfigurationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogConfigurationData \| null`	The catalog's attribute schema.
`error`	`str \| null`	Error message if the request failed.

The CatalogConfigurationData object has the following fields:

Field	Type	Description
`catalog_id`	`str`	The catalog's ID.
`project_id`	`str`	The project ID.
`configuration_hash`	`str`	A SHA256 hash of the configuration. Useful for detecting schema drift between versions.
`custom_attribute_definitions`	`list[CatalogAttributeDefinition]`	User-defined attribute definitions, sorted alphabetically by name.
`reserved_attribute_mappings`	`list[CatalogAttributeDefinition]`	System reserved attribute mappings (such as `product_id`, `title`, `price`, and `brand`), sorted in their standard order.

The CatalogAttributeDefinition object has the following fields:

Field	Type	Description
`name`	`str`	The attribute's name.
`record_field_name`	`str`	The catalog record field this attribute maps to.
`searchable`	`bool \| null`	Whether the attribute is included in full-text search.
`attribute_value_definition`	`CatalogAttributeValueDefinition`	Type information for the attribute.

The CatalogAttributeValueDefinition object has the following fields:

Field	Type	Description
`type`	`str`	One of `String`, `Integer`, `Float`, `Boolean`, `Date`, `Datetime`, `List.String`, `List.Integer`, or `List.Float`.

list_catalog_jobs

Lists the job history for a catalog. Jobs represent data ingestion and update operations: imports, parses, items-updates, configuration-updates, and so on. Useful for checking data freshness or diagnosing upload failures.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`count`	`int`	No	Number of jobs to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CatalogJobsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogJob]`	The catalog jobs, most recent first.
`total`	`int`	The total number of jobs for this catalog.
`matched`	`int`	The number of jobs matching the query.
`matched_limited`	`bool`	Whether the match count was capped by a server limit.
`limit`	`int`	The maximum number of jobs returned.
`skip`	`int`	The pagination offset that was applied.
`error`	`str \| null`	Error message if the request failed.

The CatalogJob object has the following fields:

Field	Type	Description
`id`	`str`	The job's unique ID.
`catalog_id`	`str`	The catalog ID.
`project_id`	`str`	The project ID.
`type`	`str`	The job type: `import`, `parse`, `download`, `items-update`, `configuration-update`, or `delete-catalog`.
`state`	`str`	The job state: `pending`, `running`, `success`, `fail`, or `canceled`.
`status_code`	`int`	The status code: 102 (processing), 200 (success), 210 (success with warnings), 305 (no-op), 310 (skipped), 400 (bad definition), 440 (pre-condition failure), 450 (post-condition failure), 500 (error), or 550 (fatal).
`stats`	`dict[str, any]`	Job statistics such as `records_total`, `items_total`, `records_added_total`, `records_deleted_total`, `items_updated_total`, `items_deleted_total`, `feed_total_ops`, and `feed_total_bytes`.
`properties`	`dict[str, any]`	Job properties. The shape varies by job type.
`logs`	`list[any]`	Job log entries.
`details`	`list[any]`	Job detail messages.
`created`	`str \| null`	ISO 8601 timestamp of when the job was created.
`created_by_id`	`str`	The user ID of the person who created the job.
`created_by_display_name`	`str`	Display name of the job's creator.
`edited`	`str \| null`	ISO 8601 timestamp of the last edit.
`started`	`str \| null`	ISO 8601 timestamp of when the job started running.
`requested_cancel`	`str \| null`	ISO 8601 timestamp of when cancellation was requested.
`runnable`	`str \| null`	ISO 8601 timestamp of when the job became runnable.

get_catalog_usages

Returns the cross-references for a catalog: which scenarios, recommendation engines, email campaigns, SMS campaigns, banners, experiments, in-app messages, and surveys reference it, plus whether the catalog is used in the project's custom data mapping.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `list_catalogs`.

Response parameters

The tool returns a CatalogUsagesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`used_by`	`CatalogUsedBy`	Cross-references grouped by resource type.
`used_by_data_mapping`	`bool`	Whether the catalog is referenced in the project's custom data mapping.
`error`	`str \| null`	Error message if the request failed.

The CatalogUsedBy object has the following fields:

Field	Type	Description
`scenarios`	`list[CatalogUsageEntry]`	Scenarios using this catalog.
`recommendations`	`list[CatalogUsageEntry]`	Recommendation engines using this catalog.
`email_campaigns`	`list[CatalogUsageEntry]`	Email campaigns using this catalog.
`sms_campaigns`	`list[CatalogUsageEntry]`	SMS campaigns using this catalog.
`banners`	`list[CatalogUsageEntry]`	Weblayer banners using this catalog.
`experiments`	`list[CatalogUsageEntry]`	A/B experiments using this catalog.
`in_app_messages`	`list[CatalogUsageEntry]`	In-app messages using this catalog.
`surveys`	`list[CatalogUsageEntry]`	Surveys using this catalog.
`other`	`list[CatalogUsageEntry]`	Other resources using this catalog.

The CatalogUsageEntry object has the following fields:

Field	Type	Description
`id`	`str`	The resource's ID.
`name`	`str`	The resource's display name.

list_recommendations

Lists every recommendation engine in a project. Recommendation engines power personalized product suggestions using collaborative filtering, neural models, or rule-based algorithms. The response gives you the name, status, tags, archived flag, and initiative assignment. The engine configuration is not included here — use get_recommendation for that.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns a RecommendationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[RecommendationSummary]`	The recommendation engine summaries.
`error`	`str \| null`	Error message if the request failed.

The RecommendationSummary object has the following fields:

Field	Type	Description
`id`	`str`	The recommendation engine's unique ID.
`name`	`str`	The engine's display name.
`status`	`str`	One of `draft`, `active`, or `inactive`.
`archived`	`bool`	Whether the engine has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this engine belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the engine was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

get_recommendation

Returns the full configuration of a single recommendation engine: algorithm type, the catalog it reads from, event mapping, filters, and output settings.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`recommendation_id`	`str`	Yes	The recommendation engine ID returned by `list_recommendations`.

Response parameters

The tool returns a RecommendationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Recommendation \| null`	The full engine definition.
`error`	`str \| null`	Error message if the request failed.

The Recommendation object adds the following field on top of the summary record:

Field	Type	Description
`definition`	`any \| null`	The engine configuration: model type (collaborative filtering, neural, or rule-based), the catalog, event mapping, filters, and output settings.