get_product_attribute next channel

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

Search for product attributes 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
attributeName	string	Optional	—	Case-insensitive substring match on attribute_name (LIKE). Activates relevance ranking. Use to search attributes by name, e.g. 'SaaS', 'Open Source', 'Cloud'.
attributeIds	integer[]	Optional	—	Resolve a specific set of known attribute_ids. Returns the matching rows in one call.
sortBy	"relevance" | "attribute_name" | "product_count"	Optional	"relevance"	Sort order: 'relevance' (best match first, only meaningful with attributeName), 'attribute_name' (A→Z), 'product_count' (desc). On next, unknown values return HTTP 422 (previously fell back to default silently).
limit	integer	Optional	10	Maximum number of attribute rows to return (1–50).
offset	integer	Optional	0	Pagination offset.

Response Format

{
  "attributes": [
    {
      "attribute_id": 42,
      "attribute_name": "SaaS",
      "attribute_description": "Software-as-a-Service delivery model",
      "attribute_parent_id": null,
      "attribute_level": 1,
      "product_count": 4200
    }
  ],
  "count": 1
}

Output changes from base tool

	Base tool (public)	next channel
Envelope	{ attributes, total, has_more, credits_consumed }	{ attributes, count }
Total match count	total	count
Pagination hint	has_more	(removed)
Credits	credits_consumed: 0	(removed — the tool is free)

Per-row fields unchanged: attribute_id, attribute_name, attribute_description, attribute_parent_id, attribute_level, product_count. Note: attribute_level, attribute_parent_id, and product_count may now be null.

Example Usage

{
  "tool": "get_product_attribute",
  "parameters": {
    "attributeName": "Open Source",
    "sortBy": "product_count",
    "limit": 20
  }
}

Related Tools

• company_technographic — filter installs by product_attribute_ids from here.
• product_search_and_enrich — filter products by attribute_ids in search.
• get_product_category — search for product categories.

Changelog

2026-08-06 — Breaking: direct data-api/v2 migration + new { attributes, 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_attribute now calls POST /data-api/v2/products/attributes/search directly (api.hginsights.com, Authorization: Bearer, integration key hginsights_v2__data_api) instead of the unified-API proxy (X-API-Key, key hginsights_v2). 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)

Any org that configured the old key must add a credential entry under the new key name.

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

Output envelope change

The output envelope changed from { attributes, total, has_more, credits_consumed } to { attributes, count }. Read count instead of total; derive pagination status from count vs offset + attributes.length.

Error handling

• 401 / 403 — re-thrown as UpstreamApiError with message "HG Insights V2 API authentication failed. Please check that your API key is valid and correctly configured.".
• 422 — thrown as InvalidParametersError with the upstream field-path error body included.

What stayed the same

Tool name, parameters (attributeName, attributeIds, sortBy, limit, offset), credit cost (free), and per-row attribute fields. The "at least one of attributeName / attributeIds" validation rule is unchanged. Cache schema version is bumped by +1 relative to the base tool to force-invalidate prior cached responses.