HG Momentum Signals

When to use

• Detecting companies where product usage is growing or declining.
• Queries such as "companies using X but less and less" or "companies ramping up on Y".
• Time-series analysis to validate a trend on one account.

Momentum (growing vs declining) is not recency (current vs stale). For recency, see hg-recent-signals.

Which path is available

hg_data_query may be unavailable even when hg_catalog is listed. Check your tool list first.

Situation	Path
hg_data_query available, list-level question	SQL on the momentum tables below
hg_data_query absent, plain-English list question	market_data_agent (async: start it, check status once or twice, fetch the result set with phoenix_get_artifact)
Any org, known accounts	company_install_time_series per account

search_companies has no momentum filter. Use it to build the account pool (installs, firmographics), then read momentum per account.

Three tables, three granularities

Table	Field	Granularity	Use
install_intensity_momentum_global	intensity_momentum	Single score per product × company	Quick filter: declining vs growing
install_intensity_trending_global	intensity_trending	Trending direction	Confirm direction when momentum is ambiguous
install_time_series_global	weighted_score × date_verified	Monthly snapshots	Granular trend analysis and charting

Momentum interpretation bands

intensity_momentum	Interpretation
-20 or below	Declining: active pullback, displacement window
-20 to -10	Early decline: watch
-10 to +20	Stable: no clear directional signal
+20 or above	Growing: the company is investing more in this product

The bands match observed data, but treat them as guidance, not a published scale.

SQL rules

1. Filter by id. Resolve product_id values with get_vendor_information or product_search_and_enrich (free); never filter on name strings you typed.
2. Apply the catalog's mandatory filters shown by hg_catalog (table_names mode) for every table you touch.
3. DISTINCT on install rows. They can repeat.
4. Bound date_verified on the time-series table, and always filter product_id.
5. is_ghq = true keeps global-HQ rows only; installs recorded only at subsidiary level drop out.
6. LIMIT plus max_rows, both explicit. See hg-data-query-discipline.

Query pattern: declining usage

SELECT DISTINCT cl.name, cl.country_name, cl.revenue_min,
       m.intensity_momentum, ig.intensity
FROM install_intensity_momentum_global m
JOIN install_global ig ON m.url_id = ig.url_id AND m.product_id = ig.product_id
JOIN company_locations cl ON m.url_id = cl.url_id
WHERE m.product_id IN (<product_ids>)
  AND cl.is_ghq = true
  AND m.intensity_momentum <= -20
  -- plus every mandatory predicate hg_catalog lists for these tables
ORDER BY m.intensity_momentum ASC
LIMIT 100

Call with max_rows: 100.

Query pattern: growing usage in a category

Derive the category from a resolved anchor product instead of typing a category name:

SELECT DISTINCT cl.name, cl.country_name, cl.revenue_min,
       ig.vendor_name, m.intensity_momentum, ig.intensity
FROM install_intensity_momentum_global m
JOIN install_global ig ON m.url_id = ig.url_id AND m.product_id = ig.product_id
JOIN company_locations cl ON m.url_id = cl.url_id
WHERE ig.category_leaf_name IN (
        SELECT DISTINCT category_leaf_name FROM install_global
        WHERE product_id IN (<anchor_product_ids>))
  AND cl.is_ghq = true
  AND m.intensity_momentum >= 20
  -- plus every mandatory predicate hg_catalog lists for these tables
ORDER BY m.intensity_momentum DESC
LIMIT 100

Query pattern: monthly series

SELECT DISTINCT url_id, product_id, date_verified, weighted_score
FROM install_time_series_global
WHERE product_id IN (<product_ids>)
  AND date_verified >= '2025-10-01'
  -- plus every mandatory predicate hg_catalog lists for this table
ORDER BY url_id, date_verified
LIMIT 1000

Per-account tool: company_install_time_series

{ "company_domain": "acme.com", "product_ids": [12345], "time_range": "last_12_months" }

• One selector (company_domain or hg_id) plus resolved integer product_ids or vendor_ids. Ids that match nothing return products: [] at 0 credits with a warning.
• data_points[].intensity = days detected in the month (1 to 31); a mid-series null = no detection that month.
• Drop partial months: the trailing null (current month), the month containing product_last_verified_date unless that date is at month end, and anything after it.
• Adoption strength: average detection days over the last 3 complete, loaded months (20 or more heavy, 5 to 19 regular, under 5 sparse). Core products saturate at 28 to 31, so read direction from intensity_momentum.
• current_intensity is an all-time aggregate, not on the 1 to 31 scale. is_active = verified within 90 days.

Credit implications

• hg_data_query: depends on data scanned, reported in credits_consumed; can be non-zero with 0 rows.
• market_data_agent: metered separately, billed through the run.
• company_install_time_series: 3 per product row returned, 0 if empty. Unfiltered, the default 10 products costs 30 and the maximum of 50 costs 150; granularity:"country" bills per product per country.
• hg_catalog, get_vendor_information, product_search_and_enrich search: free.

Common pitfalls

1. Filtering by name strings. A typo returns 0 rows silently.
2. Skipping the mandatory filters or the date_verified bound.
3. No DISTINCT on install joins. Counts inflate.
4. Reading the partly loaded last month as a decline.
5. Assuming hg_data_query exists.

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/hg-data-query
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/hg-catalog
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-install-time-series
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, hg-data-query-discipline, hg-recent-signals, hg-search-companies, time-series-plotting