company_hierarchy next channel

Status: Renamed from get_company_hierarchy on next This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-hierarchy.md.

Traverse the UCM corporate hierarchy tree (parents, subsidiaries, sister companies) for ONE company by HG id or domain. The former get_company_hierarchy tool key is gone on next — migrate to company_hierarchy.

Warning: company_domain is literal, never a brand alias. "alphabet.com" is a UK BMW fleet subsidiary, NOT Google — a wrong-but-valid domain returns confident wrong data with no error. Holding domains: Alphabet → "abc.xyz", Meta → "meta.com".

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

Parameters

Parameter	Type	Required	Default	Description
company_domain	string	Optional	—	Company domain, e.g. "microsoft.com". Either company_domain or hg_id is required; if both are provided, hg_id takes precedence. Interpreted literally — not a brand alias.
hg_id	string	Optional	—	HG Insights company ID (31–32 alphanumeric characters). When provided, overrides company_domain.
mode	"full" | "children" | "parents"	Optional	"children"	"children" returns the subtree rooted at the matched node. "full" returns the complete subtree rooted at the GHQ (matched node marked selected:true). "parents" returns the ancestor chain from matched node up to the GHQ.
selected_fields	string[]	Optional	—	Optional fields to include on each node beyond the always-present set (id, name, children, country_code, company_level, parent_id). Allowed: domain, domain_normalized, global_hq_id, global_hq_name, corporate_parent_id, corporate_parent_name, domestic_parent_id, domestic_parent_name, country_name, city_name, state_name, employees_total, employees_band, revenue_total, revenue_band, industry_name, naics_code, naics_name, sic_codes, sic_names, country_code, company_level, parent_id.
all_fields	boolean	Optional	false	When true, every optional field is loaded on each node. Significantly increases payload size; prefer selected_fields with a short explicit list.
country_codes	string[]	Optional	—	ISO alpha-2 country codes to include (e.g. ["DE","GB"]). Ancestor nodes outside the filter are kept as bridge nodes.
exclude_country_codes	string[]	Optional	—	ISO alpha-2 country codes to exclude. Applied after country_codes include.
naics_codes	string[]	Optional	—	NAICS code prefixes to include (e.g. ["51"] for Information). Prefix-matched. Pair with depth:5+ so matches deeper in the tree aren't missed.
exclude_naics_codes	string[]	Optional	—	NAICS code prefixes to exclude. Applied after naics_codes include.
industry_names	string[]	Optional	—	Case-insensitive substrings to match against each node's industry_name field. Pair with depth:5+.
exclude_industry_names	string[]	Optional	—	Case-insensitive substrings to exclude on industry_name. Applied after industry_names include.
depth	integer	Optional	—	Cap on levels of children from the root. In "children" mode, depth:0 = node only, depth:1 = direct children (API default). Important: depth is applied BEFORE the filters — always pair filter calls with an explicit depth:5+ to avoid missing matches deeper in the tree.
include_nulls	boolean	Optional	false	If true, fields with null values are kept on each node. Default false strips nulls — significantly reduces payload size on large trees.

Response Format

{
  "hierarchy": {
    "id": "…",
    "name": "Microsoft Corporation",
    "country_code": "US",
    "company_level": "Group HQ",
    "parent_id": null,
    "children": [
      {
        "id": "…",
        "name": "Microsoft Ireland",
        "country_code": "IE",
        "company_level": "Subsidiary",
        "parent_id": "…",
        "children": []
      }
    ]
  },
  "node_count": 142,
  "total_count_in_scope": 28
}

Response fields

Field	Meaning
hierarchy	Root node of the corporate hierarchy tree (recursive). Null when no match or tree fully pruned by filters.
node_count	Total nodes in the returned tree.
total_count_in_scope	Nodes directly matching the country_codes filter (excludes bridge-node connectors). Null when no country filter is active.

Credits

0.1 credits per node returned (dynamic; 0 for an unresolved/empty tree).

Example Usage

{
  "tool": "company_hierarchy",
  "parameters": {
    "company_domain": "microsoft.com",
    "mode": "children",
    "depth": 2,
    "selected_fields": ["domain", "country_name", "employees_band"]
  }
}

Full tree filtered to German subsidiaries:

{
  "tool": "company_hierarchy",
  "parameters": {
    "company_domain": "microsoft.com",
    "mode": "full",
    "depth": 5,
    "country_codes": ["DE"]
  }
}

Related Tools

• company_firmographic — firmographic details for a company or batch; faster and cheaper when you don't need the tree.
• search_companies — find companies by filters before traversing their hierarchies.

Changelog

2026-07-31 — Breaking: params and envelope fields renamed to snake_case

Availability: live on the private next MCP channel for allow-listed orgs. The public /api/mcp contract is unchanged.

	Before (on next)	After
Domain param	companyDomain	company_domain
ID param	hgId	hg_id
Field selection	selectedFields / allFields	selected_fields / all_fields
Country filters	countryCodes / excludeCountryCodes	country_codes / exclude_country_codes
NAICS filters	naicsCodes / excludeNaicsCodes	naics_codes / exclude_naics_codes
Industry filters	industryNames / excludeIndustryNames	industry_names / exclude_industry_names
Null retention	includeNulls	include_nulls

Output before: { "hierarchy": …, "nodeCount": 3, "totalCountInScope": 2 }

Output after: { "hierarchy": …, "node_count": 3, "total_count_in_scope": 2 }

getCacheSchemaVersion() is bumped by +2 relative to the v1 twin (get_company_hierarchy) to prevent cross-channel cache collisions. All depth/country/NAICS/industry filtering is applied client-side after fetching the full tree from upstream.

2026-07-30 — Breaking: tool renamed to company_hierarchy; inputs and response shape changed

Why this changed: the corporate-hierarchy tool now uses the same parameter and output vocabulary as every other company tool. The nested hierarchy: { id, domain } identifier is replaced by flat top-level params.

Breaking change: get_company_hierarchy is renamed to company_hierarchy

	Before	After
Tool key	get_company_hierarchy	company_hierarchy
Identifier	nested hierarchy: { id, domain } (exactly one)	flat company_domain / hg_id (at least one; hg_id wins)
All filter params	snake_case	camelCase (then renamed back to snake_case in 2026-07-31 pass)
Envelope	count / total_count_in_scope	node_count / total_count_in_scope

Migration: call the tool as company_hierarchy instead of get_company_hierarchy. Replace the nested hierarchy object with a top-level company_domain or hg_id. Example: {"hierarchy": {"domain": "microsoft.com"}} → {"company_domain": "microsoft.com"}.