hg_data_query next channel

Status: Modified (description-only; parameters, output shape, and credit cost unchanged from v1) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/hg-data-query.md.

Execute read-only SQL SELECT queries against the HG Insights data warehouse. Call the hg_catalog tool first to discover available tables and columns before writing queries. Queries must be SELECT-only (no INSERT, UPDATE, DELETE, DROP, etc.) and SELECT * is rejected — list explicit columns. Returns rows, column names, row count, and credits consumed. Prefer search_companies for vendor/product/category lookups, company counts, and firmographic filters; reach for hg_data_query only for multi-table joins, time-series, or aggregations search_companies cannot express.

The only change on the next channel is a shorter tool description: the base description exceeded the ~2,048-char limit the deployed connector enforces, so ToolSearch was truncating it mid-sentence and dropping the TAM (total-addressable-market) guidance. The description was trimmed to ≤1,600 chars and the two Splunk worked examples were moved into the query parameter's own description, where a caller composing SQL will see them. Behaviour, parameters, output, and cost are identical to v1.

Integration required: hginsights_db_query (deliberately opt-in — not auto-seeded into orgs, so warehouse SQL stays gated; the stored value is the same HG v2 API key) Cache schema version: super.getCacheSchemaVersion() + 1 (differs from base — bumped so the description version is reflected in cache keys and the manifest invariant stays green; the output shape is unchanged, so v1-cached payloads remain correct)

Credit cost: SCAN-BASED, not row-based — cost depends on the volume of data scanned, not the number of rows returned. A query returning 0 rows can still consume roughly 50 credits; add WHERE predicates to narrow scans. The actual credits consumed are reported by the upstream API and returned in credits_consumed.

Parameters

Parameter	Type	Required	Default	Description
query	string	Required	—	Read-only SQL query to execute. Must start with SELECT or WITH. The next-channel describe() text carries two worked TAM examples (Splunk installed-base count and competitive displacement) inline.
max_rows	integer	Optional	1000	Maximum number of rows to return (min 1, max 10000).

Response Format

{
  "rows": [
    { "company_id": 12345, "name": "Acme Corp" }
  ],
  "columns": ["company_id", "name"],
  "row_count": 1,
  "credits_consumed": 50
}

Response fields

Field	Meaning
rows	Array of row objects. Each key is a column name; values are the row's cell values.
columns	Column names returned by the query, in order.
row_count	Number of rows returned.
credits_consumed	Credits consumed by this query (scan-based; reported by the upstream API).

Example Usage

{
  "tool": "hg_data_query",
  "parameters": {
    "query": "SELECT COUNT(DISTINCT cl.company_id) FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.product_id IN (<splunk_product_ids>) AND cl.country_name IN ('United States', 'Canada') AND cl.employees_min >= 100 AND cl.employees_max <= 1000",
    "max_rows": 1000
  }
}

For TAM analyses, first call get_vendor_information to capture the product IDs, then filter install_global by product_id. The query parameter description includes the full installed-base and competitive-displacement examples.

Related Tools

• hg_catalog — discover the warehouse tables and columns before writing a query.
• search_companies — prefer this for vendor/product/category lookups, company counts, and firmographic filters (no SQL needed).
• get_vendor_information — resolve a vendor to its product IDs to anchor a TAM query.

Changelog

2026-08-12 — Description truncation fix (PR 1/2)

Availability: live on next only (allow-listed orgs via POST /api/mcp/next). This entry graduates to the public channel when promoted in PR 2/2.

Why this changed: A live audit found the tool description exceeded the ~2,048-char limit the deployed connector enforces, so ToolSearch was truncating it mid-sentence and dropping the TAM guidance that tells the model how to combine get_vendor_information with install_global. The two Splunk worked examples were also embedded in the main description rather than where a caller writing a query would see them.

What changed:

• Description trimmed to ≤1,600 chars — condensed so it renders in full on the deployed connector (no mid-sentence truncation), preserving the scan-based-credit warning, the search_companies preference, the SELECT-only constraints, and the key-column reference.
• TAM worked examples moved into the query param describe() — the two Splunk examples (installed-base count and competitive displacement) now live in the query parameter description, where a caller composing SQL is most likely to read them.

What stayed the same:

• All parameters are unchanged (only the query param describe() text was enriched).
• Output shape (rows, columns, row_count, credits_consumed) is unchanged.
• Tool key (hg_data_query), the scan-based credit cost, and the warehouse upstream are identical to v1.

The cache schema version is bumped (super.getCacheSchemaVersion() + 1) as required by the manifest invariant even for a description-only override.