`company_fai` next channel

Status: Modified (v2 API rewrite; role filtering; snake_case params; limit raised to 1000) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-fai.md.

Retrieve Functional Area Intelligence (FAI) for ONE company — where detected technologies are used across departments and locations, with decision-maker / influencer signals. Provide exactly one company selector: a company_domain OR an hg_id.

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. `"cisco.com"`). Provide exactly one of `company_domain` or `hg_id`. Protocol prefixes and trailing paths are stripped automatically.
`hg_id`	`string`	Optional	—	HG Insights company ID (32 alphanumeric characters). Provide exactly one of `company_domain` or `hg_id`. Obtain from a previous `company_search` / `company_firmographic` result.
`product_ids`	`integer[]`	Optional	—	HG Insights numeric product IDs to filter FAI rows to specific products. Get from `product_id` field in `company_technographic` results. There is no product-name filter — resolve names to IDs first.
`vendor_ids`	`integer[]`	Optional	—	HG Insights numeric vendor IDs — keep only FAI rows for products from these vendors. Resolve via `get_vendor_information`.
`department_ids`	`string[]`	Optional	—	FAI department IDs (hex). Call `list_fai_departments` first to discover valid IDs — do not guess or fabricate them. Omit to include all departments. Cannot be combined with `sort_field` — the upstream API rejects that combination.
`role_ids`	`string[]`	Optional	—	FAI role IDs (hex-encoded). Narrows results to specific roles. Obtain role IDs from the `role_id` field of a prior `company_fai` response.
`country`	`string[]`	Optional	—	ISO 3166-1 alpha-2 country codes (e.g. `["US", "CA"]`) — keep only rows where the signal was detected in these countries.
`has_decision_maker`	`boolean`	Optional	—	When `true`, keep only rows where a decision maker is present.
`has_influencer`	`boolean`	Optional	—	When `true`, keep only rows where an influencer is present.
`last_verified_date`	`string`	Optional	—	ISO 8601 date (YYYY-MM-DD). Keep only rows whose `last_verified_at` is on or after this date.
`sort_field`	`string`	Optional	—	Field to sort results by: `department_usage_share`, `department_signal_strength`, `role_usage_share`, `role_signal_strength_at_location`, `product_name`, `department_name`, `role_name`, `country_name`. Cannot be combined with `department_ids`.
`sort_direction`	`"ASC" \| "DESC"`	Optional	`"DESC"`	Sort direction. Only applied when `sort_field` is provided.
`limit`	`integer`	Optional	`50`	Maximum number of FAI rows to return (default: 50, max: 1000). Paginate with `offset`; `total_count` gives the total before pagination.
`offset`	`integer`	Optional	`0`	Pagination offset (default: 0, maximum: 10 000). For large companies where `total_count` exceeds 10 000, apply filters to reduce `total_count` before paginating.

Response Format

{
  "company": { "id": "…", "domain": "cisco.com", "name": "Cisco" },
  "total_count": 142,
  "data": [
    {
      "country_name": "United States",
      "state_name": "California",
      "city_name": "San Jose",
      "department_id": "a1b2…",
      "department_name": "Sales",
      "department_signal_strength": 1200,
      "department_usage_share": 0.58,
      "has_decision_maker": true,
      "has_influencer": false,
      "decision_maker_titles": ["VP of Sales"],
      "influencer_titles": [],
      "first_verified_at": "2022-01-01",
      "last_verified_at": "2024-06-01",
      "product_id": 12345,
      "product_name": "Salesforce",
      "vendor_id": 678,
      "vendor_name": "Salesforce Inc.",
      "role_id": "c3d4…",
      "role_name": "Account Executive",
      "role_signal_strength_at_location": 850,
      "role_usage_share": 0.42
    }
  ]
}

Role fields (new in 2026-08-04)

Field	Type	Description
`role_id`	`string \| null`	FAI role ID (hex-encoded). `null` when the row has no role-level signal.
`role_name`	`string \| null`	Human-readable role name. `null` when `role_id` is null.
`role_signal_strength_at_location`	`number \| null`	Detection confidence for this role at this location. Can be `0` when role presence is detected but no usage-share data exists.
`role_usage_share`	`number \| null`	Percentage of role holders at this location using the product.

Example Usage

{
  "tool": "company_fai",
  "parameters": {
    "company_domain": "cisco.com",
    "has_decision_maker": true,
    "limit": 100
  }
}

Filter by role:

{
  "tool": "company_fai",
  "parameters": {
    "company_domain": "cisco.com",
    "role_ids": ["c3d4e5f6…"],
    "sort_field": "role_usage_share"
  }
}

list_fai_departments — discover valid department IDs to use in department_ids.
company_technographic — resolve product names to numeric product_ids.
get_vendor_information — resolve vendor names to numeric vendor_ids.

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.

Additive (no action required for existing calls):

role_ids — array of hex FAI role IDs; forwarded to the upstream as filters.roles.ids to restrict results to specific roles.
limit max raised from 200 to 1000.
Four role-level fields now appear on every FAI row in data[]: role_id, role_name, role_signal_strength_at_location, role_usage_share.

The cache schema version is bumped by +2 over the v1 base value.

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`
Product filter	`productIds`	`product_ids`
Vendor filter	`vendorIds`	`vendor_ids`
Department filter	`departmentIds`	`department_ids`
Decision maker	`hasDecisionMaker`	`has_decision_maker`
Influencer	`hasInfluencer`	`has_influencer`
Date filter	`lastVerifiedDate`	`last_verified_date`
Sort field	`sortField` (camelCase enum values)	`sort_field` (snake_case enum values)
Sort direction	`sortDirection`	`sort_direction`

Sort field enum renames: "departmentUsageShare" → "department_usage_share", "departmentSignalStrength" → "department_signal_strength", "roleUsageShare" → "role_usage_share", "roleSignalStrengthAtLocation" → "role_signal_strength_at_location", "productName" → "product_name", "departmentName" → "department_name", "roleName" → "role_name", "countryName" → "country_name".

2026-07-30 — Breaking: v2 API alignment; response envelope changed

Why this changed: company_fai now calls the official HG Insights v2 API directly (POST /v2/companies/functional-areas), giving callers access to richer filters and pagination. Product-name fuzzy matching was removed in favour of exact numeric IDs.

Breaking changes

products (name-based), provider, fields, and full params removed.
productIds is the only product filter (numeric IDs from company_technographic).
New filters: vendorIds, departmentIds, country, hasDecisionMaker, hasInfluencer, lastVerifiedDate, sortField, sortDirection, limit (1–200), offset (max 10 000).
Response envelope changed: data.enriched.records[*] → data.data[*], signalCountryName → country_name, isDecisionMaker → has_decision_maker, per-row totalCount → top-level data.total_count.

Constraints: offset is capped at 10 000 by the upstream API. departmentIds and sort_field cannot be combined — apply department filtering OR sorting, not both.

Parameters​

Response Format​

Role fields (new in 2026-08-04)​

Example Usage​

Related Tools​

Changelog​

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

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

2026-07-30 — Breaking: v2 API alignment; response envelope changed​

Breaking changes​