`company_operating_signals` next channel

Status: Modified (output-shape change: company_domain widened to nullable; company_name now populated; clearer missing-identifier error; when-to/NOT-to-use description guidance) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-operating-signals.md.

Retrieve company operating signals as categorical stage labels, combining mentions-derived attributes (work_model, cloud_posture, esg_commitment, iot_posture, network_modernization, automation_stage) and GenAI maturity attributes (ai_trajectory, cloud_depth, genai_readiness, intent_adoption_gap). Call this when a user asks about a company's work model, cloud/IoT/network modernization posture, automation stage, or GenAI readiness/trajectory as summary labels (e.g. remote-heavy, cloud-native, ai-leader-accelerating).

Do not use this for raw AI-maturity scores/ranks or per-provider cloud intensity numbers — use company_ai_maturity instead. Do not use this for a company's installed technology stack/products — use company_technographic instead.

Provide a company domain (e.g., "cisco.com") or an HG Insights company ID (hg_id). Missing coverage is signalled per-section via data_available: false + no_data_reason, and per-attribute via stage: "no-signal" — these are normal results, not errors.

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

Parameters

At least one of companyDomain or hg_id is required. If neither is supplied, the tool throws companyDomain or hg_id is required. before any upstream call (previously this surfaced as a misleading HTTP 422 "upstream service issue").

Parameter	Type	Required	Default	Description
`companyDomain`	`string`	Optional	—	The company domain to look up (e.g., `"example.com"`), 1–253 chars. Either `companyDomain` or `hg_id` is required. Protocol prefixes (`http://`, `https://`), leading `www.`, and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
`hg_id`	`string`	Optional	—	HG Insights company ID (32 alphanumeric characters). When provided, this overrides `companyDomain`.

Response Format

{
  "company_name": "Cisco Systems",
  "company_domain": "cisco.com",
  "organization_id": "3AB6196C…",
  "mentions": {
    "data_available": true,
    "no_data_reason": null,
    "work_model": {
      "stage": "remote-heavy",
      "intensity": 1450,
      "last_verified_at": "2026-07-28",
      "signals": { "Remote Work": 1450 }
    },
    "cloud_posture": {
      "stage": "multi-cloud",
      "intensity": 3200,
      "last_verified_at": "2026-07-30",
      "signals": { "Public Cloud": 1800, "Private Cloud": 900, "Hybrid Cloud": 500 }
    },
    "esg_commitment": { "stage": "committed", "intensity": 220, "last_verified_at": "2026-07-15", "signals": { "…": 0 } },
    "iot_posture": { "stage": "connected-edge", "intensity": 640, "last_verified_at": "2026-07-20", "signals": { "…": 0 } },
    "network_modernization": { "stage": "next-gen", "intensity": 900, "last_verified_at": "2026-07-22", "signals": { "…": 0 } },
    "automation_stage": { "stage": "intelligent", "intensity": 1100, "last_verified_at": "2026-07-25", "signals": { "…": 0 } }
  },
  "genai_maturity": {
    "data_available": true,
    "no_data_reason": null,
    "ai_trajectory": {
      "stage": "ai-leader-accelerating",
      "intensity": 82,
      "signals": { "ai_maturity_score": 7.2, "ai_maturity_6m_delta": 0.8 }
    },
    "cloud_depth": {
      "stage": "cloud-native",
      "intensity": 95,
      "signals": { "gcp_intensity": 120, "aws_intensity": 260, "azure_intensity": 180 }
    },
    "genai_readiness": {
      "stage": "genai-ready",
      "intensity": 88,
      "signals": { "genai_intent_score": 7500, "ai_product_use": true, "data_maturity_score": 42 }
    },
    "intent_adoption_gap": {
      "stage": "ai-champion",
      "intensity": 90,
      "signals": { "genai_intent_score": 7500, "ai_product_use": true, "ai_maturity_score": 7.2 }
    }
  }
}

Response fields

Field	Meaning
`company_name`	Resolved company name from HG Insights firmographics; `null` if the company was not matched or has no firmographic name. Now populated on the `next` channel (was always `null` on base).
`company_domain`	The resolved company domain. Populated regardless of whether the lookup used `companyDomain` or `hg_id`; `null` when queried by `hg_id` and the upstream returns no domain, or when the company was not matched. Never the raw `hg_id`.
`organization_id`	HG company identifier. Empty string (`""`) when the company was not matched.
`mentions`	Mentions-derived operating signal attributes group.
`mentions.data_available`	Whether mentions-derived attributes were found.
`mentions.no_data_reason`	Reason when mentions data is unavailable; `null` when data is available.
`mentions.work_model` / `cloud_posture` / `esg_commitment` / `iot_posture` / `network_modernization` / `automation_stage`	Mention attribute objects (or `null` when the section has no data). Each has `stage`, `intensity`, `last_verified_at`, and `signals`.
`mentions.*.stage`	Derived categorical stage label (e.g. `remote-heavy`, `multi-cloud`, `intelligent`, or `no-signal`).
`mentions.*.intensity`	Unbounded sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — not the 0–100 scale used by `genai_maturity` attributes, and not a percentage or currency. Comparable within a company, not across companies.
`mentions.*.last_verified_at`	Most recent verification date (`string` or `null`).
`mentions.*.signals`	Breakdown of individual mention intensities by product/keyword (`{ [name]: number }`).
`genai_maturity`	Derived GenAI maturity attributes group.
`genai_maturity.data_available`	Whether GenAI maturity data was found.
`genai_maturity.no_data_reason`	Reason when GenAI maturity data is unavailable; `null` when available.
`genai_maturity.ai_trajectory`	Direction and speed of AI journey — current maturity combined with 6-month momentum. Stages: `ai-leader-accelerating`, `ai-leader-growing`, `ai-leader-plateau`, `ai-adopter-accelerating`, `ai-adopter-growing`, `ai-adopter-plateau`, `ai-beginner-growing`, `ai-beginner-stalled`, `ai-dormant`.
`genai_maturity.cloud_depth`	Total cloud infrastructure investment across all providers combined. Stages: `cloud-native`, `cloud-heavy`, `cloud-moderate`, `cloud-light`, `no-cloud`.
`genai_maturity.genai_readiness`	Preparedness to adopt or expand Generative AI. Stages: `genai-ready`, `genai-interested`, `genai-exploring`, `genai-aware`, `genai-curious`, `genai-inactive`.
`genai_maturity.intent_adoption_gap`	Gap between GenAI interest signals and actual adoption. Stages: `ai-champion`, `active-explorer`, `intent-no-action`, `moderate-adopter`, `warming-up`, `quiet-user`, `disengaged`.
`genai_maturity.*.intensity`	Intensity score on a 0–100 scale for each GenAI maturity attribute.
`genai_maturity.*.signals`	Raw input signals used for the derivation (varies by attribute).

No-signal / no-data is normal. When a company has no coverage for a section, that section returns data_available: false with a human-readable no_data_reason and null attributes; a covered section with no detected signal for a given attribute returns stage: "no-signal". Neither is an error — treat them as expected results.

Example Usage

By domain:

{
  "tool": "company_operating_signals",
  "parameters": {
    "companyDomain": "cisco.com"
  }
}

By HG Insights company ID (company_domain in the response resolves to the real domain or null, never the hg_id):

{
  "tool": "company_operating_signals",
  "parameters": {
    "hg_id": "3AB6196C0000000000000000000000AA"
  }
}

company_ai_maturity — use this for raw AI-maturity scores/ranks and per-provider cloud intensity numbers (this tool returns categorical stage labels instead).
company_technographic — use this for a company's installed technology stack/products.

Changelog

2026-08-12 — Identifier + company_name correctness fixes, moved to next-only (PR 1/2)

Availability: live on next only (allow-listed orgs via POST /api/mcp/next). The v1 base tool is byte-identical to master; this entry graduates to the public channel when promoted in PR 2/2.

Why this changed: A live audit found three defects: (1) calling the tool with neither companyDomain nor hg_id produced a misleading HTTP 422 "upstream service issue" instead of a caller-fixable validation error; (2) on hg_id lookups the tool echoed the hg_id back under company_domain, so downstream chains ingested an id as a "domain"; (3) company_name was always null because the firmographics section was never requested. The description also lacked when-to/NOT-to-use guidance, overlapping with company_ai_maturity and company_technographic.

Breaking change — output shape: `company_domain` nullable, `company_name` now required

company_domain widens from string to string | null (null when queried by hg_id and the upstream returns no domain, or when the company was not matched — never the raw hg_id).
company_name is added to the output schema required list and is populated from the firmographics section (was always null).
Migration: treat company_domain as possibly null and stop using it as a stand-in for the queried hg_id. Read company_name for the resolved legal name.

Additive

Missing-identifier validation error: throws companyDomain or hg_id is required. before any upstream call when neither identifier is supplied (previously surfaced as a confusing 422).
Requests the firmographics field group: the upstream /data-api/v2/companies/enrich call now includes firmographics alongside ai_maturity and mentions so company_name can be populated.
when-to-use / when-NOT-to-use description guidance: adds STAGE-LABELS framing and explicit anti-triggers (use company_ai_maturity for raw scores/ranks, company_technographic for the installed tech stack). Documents that missing coverage (data_available: false / stage: "no-signal") is normal, not an error.

What stayed the same

Parameters (companyDomain, hg_id) and the hginsights_v2__data_api integration are unchanged.
Tool key (company_operating_signals) and credit cost are unchanged.
The mentions-derived + GenAI-maturity derivation logic is unchanged.

The Redis cache schema version was bumped 2 → 3 so a next caller is never served a v1-shaped cached payload (output shape changed: company_domain nullable, company_name required).

Parameters​

Response Format​

Response fields​

Example Usage​

Related Tools​

Changelog​

2026-08-12 — Identifier + company_name correctness fixes, moved to next-only (PR 1/2)​

Breaking change — output shape: company_domain nullable, company_name now required​

Additive​

What stayed the same​