product_search_and_enrich next channel

Status: Modified (direct data-api/v2 migration; new response model for search and enrich) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/product-search-and-enrich.md.

Discover and hydrate products from the HG Insights product catalog. Use action='search' to find product_ids by name/vendor/category/attributes (free). Use action='enrich' to hydrate 1–50 product IDs with full catalog details (1 credit per successful match).

Integration required: hginsights_v2__data_api Cache schema version: 2 (differs from base — stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
action	"search" | "enrich"	Required	—	'search' lists matching products by name/vendor/category (free). 'enrich' hydrates 1–50 product_ids with full catalog details (1 credit per successful match).
filters	object	Optional	—	search-only. Flat HG catalog filters: product_name, description, category_name, attribute_name, vendor_name, category_id (uppercase hex), attribute_ids, vendor_id, has_install. Unknown keys and legacy nested shapes are rejected. Note: filters.description is silently renamed to product_description on the wire (the data-api schema rejects a key literally named description) — pass filters.description as you always would.
sort	object[]	Optional	—	search-only. Up to 3 sort specs. field ∈ {relevance, product_name, vendor_name, category_name, last_verified_at}, order ∈ {asc, desc}.
limit	integer	Optional	—	search-only. Page size (1–100). Server default: 50.
offset	integer	Optional	—	search-only. Pagination offset (>= 0). Server default: 0.
products	object[]	Optional	—	enrich-only. 1–50 product_ids to hydrate. Duplicates are deduped by upstream. Unmatched ids are omitted from the response and do not consume credits.

Response Format

action: "search"

{
  "products": [
    {
      "product_id": 26434,
      "product_name": "Snowflake",
      "product_description": "Cloud data platform…",
      "vendor_id": 678,
      "vendor_name": "Snowflake Inc.",
      "category_id": "A1B2C3D4…",
      "category_name": "Data Warehouse"
    }
  ],
  "count": 1
}

action: "enrich"

{
  "products": [
    {
      "product_id": 26434,
      "product_name": "Snowflake",
      "product_description": "…",
      "vendor_id": 678,
      "vendor_name": "Snowflake Inc.",
      "category_id": "A1B2C3D4…",
      "category_name": "Data Warehouse",
      "product_details": { "…": "…" },
      "category_info": { "…": "…" },
      "vendor_info": { "…": "…" }
    }
  ]
}

Output changes from base tool

	Base tool (public)	next channel
search envelope	{ results, pagination:{ total, limit, offset, has_more }, credits_consumed }	{ products, count }
enrich per-row input_key	present	removed
enrich per-row error (NO_MATCH_FOUND)	present at HTTP 200	removed
enrich unmatched ids	returned as an error row	omitted from products entirely
Credits (enrich)	credits_consumed from upstream body	1 per returned row (= products.length)

Billing for enrich: because unmatched ids are now omitted, the charge equals products.length. Callers should reconcile requested vs. returned ids to detect misses — there is no longer a per-row error marker.

Example Usage

Search:

{
  "tool": "product_search_and_enrich",
  "parameters": {
    "action": "search",
    "filters": {
      "vendor_name": "Snowflake",
      "has_install": true
    },
    "limit": 10
  }
}

Enrich:

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

Related Tools

• company_technographic — get product_id values from install records; use this tool to enrich those IDs.
• company_install_time_series — filter time series by product_ids; resolve them here first.
• get_vendor_information — resolve vendor names to vendor_ids.

Changelog

2026-08-06 — Breaking: direct data-api/v2 migration + new response model

Availability: live on the private next MCP channel (POST /api/mcp/next) for allow-listed orgs. The public /api/mcp contract is unchanged until the promotion PR lands.

Why this changed: product_search_and_enrich now calls POST /data-api/v2/products/search and POST /data-api/v2/products/enrich directly (api.hginsights.com, Authorization: Bearer, integration key hginsights_v2__data_api) instead of the unified-API proxy. Removes a network hop and adopts the new data-api response model. Part of PHX-1476 Phase 2c.

Integration key change (operator action required)

	Before	After (on next)
Integration key	hginsights_v2	hginsights_v2__data_api
Auth header	X-API-Key	Authorization: Bearer

Output changes — action: "search"

	Before	After
Envelope	{ results, pagination:{ total, limit, offset, has_more }, credits_consumed }	{ products, count }
Rows	results[]	products[] (same row fields)
Total	pagination.total	count
Credits	credits_consumed: 0	(removed — search is free)

Output changes — action: "enrich"

	Before	After
Envelope	{ products:[{ input_key, product_id, …, error }], credits_consumed }	{ products:[{ product_id, product_name, … }] }
Per-row input_key	present	removed
Per-row error (NO_MATCH_FOUND)	present	removed
Unmatched ids	returned as error row	omitted from products entirely

Error handling

• 401/403 — translated into "HG API authentication failed. Verify the HGInsights v2 API key is configured.".
• 422 — upstream field-path detail forwarded as InvalidParametersError.

What stayed the same

Tool name, parameters, the free/paid split (search free, enrich 1 credit per match), and the pre-check credit estimate. Cache schema version bumped by +1.