company_firmographic next channel

Status: Modified (batch selectors; dropped found/message; snake_case params; Group HQ field stripping) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-firmographic.md.

Call this when a user asks about a company's firmographics — name, location, industry, employee/revenue size, or corporate hierarchy. Use this (not company_enrich) for firmographic-only questions — it is faster and returns a smaller payload. Accepts a batch of up to 25 companies.

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

Parameters

Parameter	Type	Required	Default	Description
hg_ids	string[]	Optional	—	HG Insights company IDs for batch firmographic lookup (up to 25). Provide hg_ids or domains (at least one is required); both may be combined.
domains	string[]	Optional	—	Company domains for batch firmographic lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically.

Response Format

{
  "companies": [
    {
      "company_id": "3AB6196C…",
      "company_domain": "cisco.com",
      "firmographics": {
        "name": "Cisco Systems",
        "domain": "cisco.com",
        "city_name": "San Jose",
        "state_name": "California",
        "country_code": "US",
        "country_name": "United States",
        "employees_total": 80000,
        "employees_band": "50,001-100,000",
        "revenue_total": 52000000000,
        "revenue_band": "> $10B",
        "industry_name": "Technology",
        "naics_code": "334118",
        "company_level": "Group HQ",
        "fortune_500_rank": 60,
        "forbes_2000_rank": 125,
        "it_spend": 5000000000
      },
      "customer_data": { "…": "…" }
    }
  ]
}

Response notes

• Unmatched companies are omitted from the array — do not assume positional alignment with your input.
• A miss is signalled by company_id: "" with an empty firmographics.
• Group HQ field stripping: for any company whose company_level equals "Group HQ", all global_hq_* fields are silently removed before the result is returned. A Group HQ is its own ultimate parent; these fields are byte-identical to the base fields and carry zero information. For all other company levels, the global_hq_* block is preserved.
• customer_data is the org's own account record joined by domain from Snowflake (present only when a Snowflake integration is configured and a row matched).
• For a subsidiary, chain enrichment tools on global_hq_id (not company_id) to reach the ultimate parent.

Example Usage

{
  "tool": "company_firmographic",
  "parameters": {
    "domains": ["cisco.com", "salesforce.com", "microsoft.com"]
  }
}

Related Tools

• company_hierarchy — traverse the corporate hierarchy tree for parent/subsidiary relationships.
• company_enrich — multi-section enrichment including firmographics + other sections in a single call.
• search_companies — discover companies by filters, then pass hg_ids here for firmographic detail.

Changelog

2026-08-04 — Unified API PR #326 alignment

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

Why this changed: aligns company_firmographic with the additive batch capability shipped in unified API PR #326.

Breaking change — company selection is now batch-only

• The singular hg_id / company_domain selectors are removed. Select companies with batch arrays: hg_ids (array, ≤25) and/or domains (array, ≤25). At least one is required.
• The output is now a { companies: [...] } array.
• Migration: hg_id: "abc" → hg_ids: ["abc"], company_domain: "cisco.com" → domains: ["cisco.com"], then read response.companies[].

The Snowflake customer_data enrichment block now runs per returned company (each entry in companies[] carries its own customer_data).

Output shaping: for any company whose company_level equals "Group HQ", all global_hq_* fields are silently removed. This roughly halves the per-entry payload for those companies.

The Redis cache schema version was bumped 7 → 8 so pre-#326 cached payloads are not served.

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

Output before: { "companyId": "abc123", "companyDomain": "cisco.com", "firmographics": { … }, "customerData": { … } }

Output after: { "company_id": "abc123", "company_domain": "cisco.com", "firmographics": { … }, "customer_data": { … } }

2026-07-30 — Breaking: hg_id renamed to hgId; dropped found / message

Why this changed: the removed found boolean was unreliable — it could report true alongside an empty companyId and empty firmographics, letting consumers proceed with no data — so a miss is now signalled purely by an empty companyId.

Breaking change

• hg_id → hgId (subsequently renamed to hg_id in the 2026-07-31 snake_case pass).
• found and message output fields removed. Detect a miss with companyId === "" (and/or empty firmographics) instead of found === false.