Get Product Category

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Resolve a term to the exact HG Insights taxonomy category name/id needed by company_technographic before an install query. Free — no credits consumed.

Matching: categoryName and treeContains use case-insensitive LIKE substring matching — NOT fuzzy or semantic, so misspellings return zero rows with no warning. Use common partial terms rather than guessing full names. treeContains scans the full root → leaf path to scope to a whole branch. categoryCode / categoryId are exact lookups. Per-parameter behaviour is documented on each parameter.

Returns category rows (category_id, category_code, category_name, category_name_tree, has_category_installs, product_count) plus a top-level count of total matches across all pages. product_count covers direct products only, not the subtree, so parent nodes look small. Prefer deeper leaf categories (longer category_name_tree) for precise filtering.

Use this when:

• You need the exact category name/id to pass to company_technographic (set hasInstalls: true to limit to categories with real install data).
• You want to explore the category taxonomy by keyword.

Do NOT use this when:

• You want vendor details or a vendor_id — use get_vendor_information.
• You want product attribute data — use get_product_attribute.
• You want warehouse table schemas for SQL query planning — use hg_catalog (not product taxonomy).

Requires at least one filter. When both categoryId and categoryCode are given they must match the same record (AND logic); if in doubt provide only categoryId.

Credits

Free — No credits consumed. See the full credit table for how AI Credits work.

Parameters

Name	Type	Default	Description
categoryName	string	-	Case-insensitive LIKE substring match on category_name (NOT fuzzy/semantic — misspellings return 0 rows). Activates relevance ranking. Use common partial terms, e.g. 'CRM', 'Security', 'Cloud'. Note: the taxonomy root is 'Security' — 'Cyber Security'/'Cybersecurity' return 0 rows.
treeContains	string	-	Case-insensitive LIKE substring scanned across every node in category_name_tree (root → leaf). Use to scope to a whole branch, e.g. 'Sales and Marketing' returns all categories under that parent.
categoryCode	string	-	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	-	Exact match on category_id (uppercase 32-char Int128 hex).
hasInstalls	boolean	-	true = only categories with at least one install signal; false = catalog-only categories. Omit to return all.
sortBy	string	relevance	Sort order: 'relevance' (best match first; only sent when categoryName or treeContains is present — auto-dropped for exact categoryCode/categoryId lookups so they don't 422), 'category_name' (A→Z), 'product_count' (desc).
limit	integer	10	Maximum number of category rows to return (1–50).
offset	integer	0	Pagination offset.

Required Integrations

This tool is only available when your organization has the following integration configured in the Phoenix Integrations settings:

• HG Insights (Data API) (hginsights_v2__data_api)

Use Cases

• Find the exact category name/id for a term to use in a company_technographic query
• Explore all sub-categories under a taxonomy branch (e.g. 'Sales and Marketing')
• Look up a category by its code to get its full tree path and confirm its name
• Filter to only categories with real install signals (hasInstalls: true) before a technographic query
• Disambiguate an ambiguous term (e.g. 'Security' returns multiple nodes) to pick the right leaf

Example Usage

Categories matching 'Cloud' with install data

{
  "tool": "get_product_category",
  "arguments": {
    "categoryName": "Cloud",
    "hasInstalls": true,
    "sortBy": "product_count",
    "limit": 10
  }
}

Scope to a taxonomy branch

{
  "tool": "get_product_category",
  "arguments": {
    "treeContains": "Sales and Marketing",
    "hasInstalls": true
  }
}

Exact lookup by category code

{
  "tool": "get_product_category",
  "arguments": {
    "categoryCode": "SW010"
  }
}

Response Format

Field	Type	Description
categories	array	Matching category rows, ordered by sortBy.
categories[].category_id	string	Uppercase 32-char Int128 hex. Use in downstream tool calls.
categories[].category_code	string | null	Stable short code, e.g. 'SW049'. Null for some top-level categories.
categories[].category_name	string
categories[].category_parent_id	string | null	Null at the taxonomy root.
categories[].category_id_tree	array
categories[].category_name_tree	array
categories[].has_category_installs	boolean
categories[].product_count	integer | null
count	integer	Total matching categories across all pages (not the page size). Compare to limit+offset to detect further pages.

Related Tools

company_technographic, get_vendor_information, get_product_attribute, hg_catalog