Skip to main content

company_intent next channel

Status: Modified (v2 rewrite; geo granularity; no-data result handling; snake_case params) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-intent.md.

Get a broad overview of buying-intent signals for a specific company. Provide a company_domain (e.g. "cisco.com") or an HG Insights hg_id. Returns summary, topics, and activities field groups, each a { count, data } object.

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​

ParameterTypeRequiredDefaultDescription
company_domainstringOptional—Company domain (e.g. "cisco.com"). Either company_domain or hg_id is required. Protocol prefixes and trailing paths are stripped automatically.
hg_idstringOptional—HG Insights company ID (32-character hex). When provided, overrides company_domain.
fieldsstring[]Optional—Which field groups to return: any subset of "summary", "topics", "activities". Omit to return all three.
signal_dateobjectOptional—Inclusive signal-date range filter { from, to } (YYYY-MM-DD). Omit for the upstream default window.
signal_level("HIGH" | "MEDIUM" | "LOW")[]Optional—Filter topics by signal level (HG topics only).
buyers_journey_names("Researching" | "Evaluating")[]Optional—Filter topics by buyer-journey stage. Only "Researching" and "Evaluating" are accepted — the tool rejects out-of-enum values up front.
context_type_namesstring[]Optional—Filter topics by context type (e.g. ["Displacement", "Whitespace", "Expansion", "Complementary"]).
topic_idsstring[]Optional—Filter to specific hex-encoded topic IDs (32-char Int128). Obtain from list_intent_topics.
granularity"global" | "region" | "country" | "state"Optional—Geographic granularity for topic results. At finer granularities, country_name / region_name / state_name are populated on each returned topic (a topic can repeat once per geography).
product_category_idsstring[]Optional—Filter TrustRadius activities to specific product category IDs (hex-encoded).
vendor_idsinteger[]Optional—Filter to specific vendor IDs (integers).
product_idsinteger[]Optional—Filter to specific product IDs (integers).
limitintegerOptional—Max records per section (1–200). Defaults to the upstream page size (50).
offsetintegerOptional—Records to skip per section for pagination (default 0).

Response Format​

Normal response:

{
  "company": { "id": "…", "name": "Cisco", "domain": "cisco.com" },
  "summary": {
    "active_topics_count": 5,
    "high_signal_topics_count": 2,
    "latest_signal_date": "2026-06-15",
    "sources": { "hg": 5, "trustradius": 3 },
    "top_context_types": { "Whitespace": 2, "Expansion": 1 }
  },
  "topics": {
    "count": 12,
    "data": [
      {
        "name": "Cloud Security",
        "score": 84,
        "signal_level": "HIGH",
        "buyers_journey_name": "Evaluating",
        "context_type_names": ["Whitespace"],
        "vendor_names": ["CrowdStrike"],
        "last_seen_at": "2026-06-15",
        "source": "hg"
      }
    ]
  },
  "activities": {
    "count": 3,
    "data": [
      {
        "activity_date": "2026-06-10",
        "activity_type": "Review",
        "products": ["Okta"],
        "vendors": ["Okta"]
      }
    ]
  }
}

No-data response (company not in HG dataset):

{
  "company": { "domain": "xage.com" },
  "data_available": false,
  "no_data_reason": "No intent data found for xage.com",
  "topics": { "count": 0, "data": [] },
  "activities": { "count": 0, "data": [] }
}

No-data handling​

A confirmed "company not found" now returns a successful no-data result instead of throwing an error:

  • data_available — false only on a no-data answer; absent on populated results, so existing consumers see no change.
  • no_data_reason — names the identifier that returned nothing.
  • topics / activities are always present as empty collections (never null).

Real failures still fail — 401 / 403 / 429 / 5xx still raise classified errors.

Example Usage​

{
  "tool": "company_intent",
  "parameters": {
    "company_domain": "cisco.com",
    "fields": ["topics"],
    "signal_level": ["HIGH"],
    "buyers_journey_names": ["Evaluating"]
  }
}

Country-level breakdown:

{
  "tool": "company_intent",
  "parameters": {
    "company_domain": "cisco.com",
    "granularity": "country",
    "fields": ["topics"]
  }
}

Changelog​

2026-08-04 — "Company not found" is now a no-data result, not an error​

Availability: this change lands on both the private next channel and the public /api/mcp contract — the two implementations had the identical defect and were fixed together.

Why this changed: when HG Insights had no intent data for a company, the tool failed with an error stating "This is an upstream service issue." That was factually wrong — a real no-data answer was relayed as a service outage.

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 — geo granularity: new granularity param ("global", "region", "country", or "state").

Breaking (minor) — buyers_journey_names is now an enum. Restricted to ["Researching", "Evaluating"]. Requests already sending only those values are unaffected.

2026-07-31 — Breaking: params 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
Signal levelsignalLevelsignal_level
Signal datesignalDatesignal_date
Journey filterbuyersJourneyNamesbuyers_journey_names
Context filtercontextTypeNamescontext_type_names
Topic filtertopicIdstopic_ids
Category filterproductCategoryIdsproduct_category_ids
Vendor filtervendorIdsvendor_ids
Product filterproductIdsproduct_ids

hg_id was already correct and is unchanged.

Null-section cleanup: the upstream echoes summary, topics, and activities as null (not absent) for field groups the caller did not request. The tool deletes these null sections before returning.

2026-07-30 — Breaking: v2 rewrite onto unified intent endpoint​

Why this changed: company_intent now maps one-to-one onto POST /data-api/v2/intent/enrich.

Breaking changes​

BeforeAfter
Signal-level filterintent_level (single value "High")signalLevel (array, "HIGH"/"MEDIUM"/"LOW")
Buyer-journey filterbuyers_journey (single string)buyersJourneyNames (array)
Context-type filtercontext_type (single string)contextTypeNames (array)
Date windowstart_date + end_date (flat)signalDate object { from, to }
Vendor / product filtervendor_name / product_name (fuzzy strings)vendorIds / productIds (integer ID arrays)
Activity-search modeseparate signal/products/group_by paramsremoved — activities returned inline

Output: topics and activities are now { count, data[] } objects. Per-topic fields renamed: topic_name → name, intent_level → signal_level, buyers_journey → buyers_journey_name. The top-level window object was removed.