get_product_category next channel

Status: Modified (direct data-api/v2 migration; new { categories, count } output model; category_parent_id added) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/get-product-category.md.

Search for product categories in the HG Insights taxonomy. Free — no credits consumed.

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
categoryName	string	Optional	—	Case-insensitive substring match on category_name (LIKE). Activates relevance ranking.
treeContains	string	Optional	—	Case-insensitive substring scanned across every node in category_name_tree. Useful for scoping to a branch, e.g. 'Sales and Marketing' returns all categories under that parent.
categoryCode	string	Optional	—	Exact match on category_code, e.g. 'SW049'. Note: many intermediate and some top-level categories have a null category_code — if a prior call returned a null code, use categoryId instead.
categoryId	string	Optional	—	Exact match on category_id (uppercase 32-char Int128 hex).
hasInstalls	boolean	Optional	—	true = only categories with at least one install signal; false = catalog-only categories. Omit to return all.
sortBy	"relevance" | "category_name" | "product_count"	Optional	"relevance"	Sort order: 'relevance' (best match first, only meaningful with categoryName or treeContains), 'category_name' (A→Z), 'product_count' (desc).
limit	integer	Optional	10	Maximum number of category rows to return (1–50).
offset	integer	Optional	0	Pagination offset.

Response Format

{
  "categories": [
    {
      "category_id": "A1B2C3D4…",
      "category_code": "SW049",
      "category_name": "CRM",
      "category_parent_id": "F5E6D7C8…",
      "category_id_tree": ["ROOT_HEX", "SW_HEX", "SW049HEX"],
      "category_name_tree": ["Software", "Sales", "CRM"],
      "has_category_installs": true,
      "product_count": 142
    }
  ],
  "count": 1
}

New field: category_parent_id

category_parent_id is a new field in the next-channel output schema. It is null for root-level categories. This field did not appear in the base tool's output.

Output changes from base tool

	Base tool (public)	next channel
Envelope	{ categories, total, has_more, credits_consumed }	{ categories, count }
Total match count	total	count
Pagination hint	has_more	(removed — derive from count vs offset + categories.length)
Credits	credits_consumed: 0	(removed — the tool is free)
New field	(absent)	category_parent_id (string | null)

product_count may now be null (the base tool typed it non-null).

Example Usage

{
  "tool": "get_product_category",
  "parameters": {
    "categoryName": "CRM",
    "sortBy": "product_count",
    "limit": 10
  }
}

Scope to a branch of the taxonomy:

{
  "tool": "get_product_category",
  "parameters": {
    "treeContains": "Security",
    "hasInstalls": true,
    "limit": 20
  }
}

Related Tools

• company_technographic — filter installs by category_ids from here.
• company_install_time_series — filter time series by category_ids.
• search_companies — filter companies by installs.product_categories.

Changelog

2026-08-06 — Breaking: direct data-api/v2 migration + new { categories, count } 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: get_product_category now calls POST /data-api/v2/products/categories/search directly (api.hginsights.com, Authorization: Bearer, integration key hginsights_v2__data_api) instead of the unified-API proxy. Removes a network hop and aligns with 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: <key>	Authorization: Bearer <key>

Any org still presenting the old hginsights_v2 key will receive a 401/403.

Output envelope change

• { categories, total, has_more, credits_consumed } → { categories, count }.
• count is the total number of matching categories before pagination (same value total held).
• has_more removed — derive pagination from count vs offset + categories.length.
• credits_consumed removed — the tool remains free.
• New per-row field: category_parent_id (string | null) — null at the taxonomy root.
• product_count may now be null.

What stayed the same

Tool name, parameters, credit cost (free), carried-over per-row fields (category_id, category_code, category_name, category_id_tree, category_name_tree, has_category_installs, product_count). 422 validation errors still surface the upstream field-path in the error message. Cache schema version bumped by +1 relative to the base tool.