Product Search & Enrich

product_search_and_enrich is a single MCP tool that proxies two endpoints of the HG Insights v2 product catalog API behind one action discriminator:

• action: "search" → POST /v2/products/search — free. Discovers product_ids by name, vendor, category, attributes, or install signal.
• action: "enrich" → POST /v2/products/enrich — 1 credit per successfully matched product_id. Hydrates 1-50 ids with full catalog details (product_details, category_info, vendor_info).

Typical flow: call search to disambiguate, then enrich the chosen product_id(s).

Parameters

The action field selects the branch and determines which other fields are valid. Action-conditional invariants (e.g. products is required for enrich, forbidden for search) are enforced at runtime.

Shared

Name	Type	Required	Description
action	"search" | "enrich"	Yes	Selects which HG endpoint to call.

action: "search"

Name	Type	Required	Default	Description
filters	object	No	—	Flat HG catalog filters (see below). Unknown keys are rejected.
sort	array (max 3)	No	—	Up to 3 sort specs.
limit	int (1-100)	No	50	Page size.
offset	int (≥ 0)	No	0	Pagination offset.

filters keys

All optional, AND-combined:

Key	Type	Description
product_name	string	Substring match on product name.
description	string	Substring match on product description.
category_name	string	Substring match on category name.
attribute_name	string	Substring match on attribute name.
vendor_name	string	Substring match on vendor name.
category_id	string (32-char uppercase hex)	Exact category UUID.
attribute_ids	int[]	One or more numeric attribute IDs (AND-combined).
vendor_id	int	Exact numeric vendor ID.
has_install	boolean	Restrict to products with at least one HG install signal.

sort spec

Each entry is an object { field, order }:

• field ∈ relevance, product_name, vendor_name, category_name, last_verified_at.
• order ∈ asc, desc.

action: "enrich"

Name	Type	Required	Description
products	array of { product_id: int } (1-50)	Yes	The product_ids to hydrate. Duplicates are deduped by upstream.

filters, sort, limit, and offset are rejected for enrich.

Required Integrations

• hginsights_v2

Credit Cost

Branch	Cost
search	Free — never consumes credits regardless of result count.
enrich	1 credit per matched product_id. Unmatched ids return a per-row NO_MATCH_FOUND error at HTTP 200 and do not consume a credit.

The pre-check estimates enrich cost as min(products.length, 50) so an organization at its hard cap can still call the free search branch.

Example Usage

Search by name

{
  "tool": "product_search_and_enrich",
  "parameters": {
    "action": "search",
    "filters": { "product_name": "Snowflake" },
    "limit": 10
  }
}

Search with sort and attribute filter

{
  "tool": "product_search_and_enrich",
  "parameters": {
    "action": "search",
    "filters": { "category_name": "Cloud Data Warehouse", "has_install": true },
    "sort": [{ "field": "last_verified_at", "order": "desc" }],
    "limit": 50
  }
}

Enrich known product_ids

{
  "tool": "product_search_and_enrich",
  "parameters": {
    "action": "enrich",
    "products": [{ "product_id": 12345 }, { "product_id": 67890 }]
  }
}

Response Format

search

{
  "results": [
    {
      "product_id": 12345,
      "product_name": "Snowflake",
      "product_description": "Cloud data warehouse...",
      "vendor_id": 678,
      "vendor_name": "Snowflake Inc.",
      "category_id": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
      "category_name": "Cloud Data Warehouse"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0, "has_more": false },
  "credits_consumed": 0
}

enrich

{
  "products": [
    {
      "input_key": { "product_id": 12345 },
      "product_id": 12345,
      "product_name": "Snowflake",
      "product_details": { "...": "..." },
      "category_info": { "...": "..." },
      "vendor_info": { "...": "..." },
      "error": null
    },
    {
      "input_key": { "product_id": 99999999 },
      "product_id": null,
      "product_name": null,
      "product_details": null,
      "category_info": null,
      "vendor_info": null,
      "error": { "code": "NO_MATCH_FOUND", "message": "No product matched product_id=99999999" }
    }
  ],
  "credits_consumed": 1
}

credits_consumed reflects only the rows where error is null.

Error Handling

• NO_MATCH_FOUND (per-row, HTTP 200): the product_id does not exist in the HG catalog. Not billed.
• HTTP 422 (whole request): malformed filter or sort spec — surface as InvalidParameters with the upstream message.
• HTTP 401: the hginsights_v2 API key is missing or invalid.

Related Tools

• list_product_categories — browse the category taxonomy used by filters.category_id / filters.category_name.
• list_product_attributes — discover attribute_ids and attribute_name values.
• get_vendor_information — look up vendor_id / vendor_name for filtering.
• company_technographic — once you have product_ids, see which companies use them.

Next Steps

• View all tools
• Browse product categories
• List product attributes