HG Insights - RGI

company_hierarchy — corporate ownership tree / subsidiaries / parent company / who owns X / sister companies. Traverses the UCM tree for ONE company by domain or hg_id. company_domain IS LITERAL, not a brand alias: "alphabet.com" = a UK fleet subsidiary, NOT Google — a wrong-but-valid domain returns confident WRONG data with NO error. Holding domains: Alphabet="abc.xyz", Meta="meta.com". No known domain? Resolve via search_companies FIRST. USE WHEN: "who owns X?", subsidiaries, parent chain, or sister companies. Do NOT use for: firmographics only → company_firmographic; a full tech/intent/spend profile → company_enrich; a list of companies → search_companies. DEFAULTS: mode="children", depth=1 (direct children only). MODES: "children"=subtree at matched node · "full"=whole tree from GHQ · "parents"=ancestor chain up to GHQ. BEWARE: (1) Fortune-500 parents return 100–330+ nodes — depth is the size lever. (2) mode:"full" returns the WHOLE parent family; check company_level. (3) depth applies BEFORE filters — pair country_codes/naics/industry filters with depth:5+. (4) UCM may return DUPLICATE nodes; dedupe by id. RECIPES: "who owns X?"→mode:"parents" · all subs→depth:5 · EU entities→country_codes:["DE","FR"],depth:5. Trim returned columns with selected_fields. Matched node always kept even if it fails a filter. hierarchy:null → read no_match_reason. mode:"parents"+already_at_ghq:true → company IS the GHQ. Credit: 0.1/node.

company_install_time_series — technology adoption trend over time / monthly install intensity / is a company growing or declining a product / tech churn. Returns a monthly installation-intensity time series per product for one company. Use for TREND questions — adoption growth, decline, or churn. Identify the company by EITHER company_domain OR hg_id (exactly one required). Do NOT use for a point-in-time answer: for CURRENT installed tech stack use company_technographic; for department/role usage use company_fai; for dollar spend use company_spend. Each data_points[].intensity is an integer 1-31 = days the product was detected that month (null = no detection). Most-recent point is typically null (current month incomplete). For trend analysis use intensity_momentum (positive = growing, negative = declining; magnitude meaningful), not raw intensity; current_intensity is a separate aggregate NOT on the 1-31 scale. Filtering is ID-based only — numeric product_ids/vendor_ids or string category_ids; resolve IDs first. Filter IDs matching nothing return products: [] with HTTP 200 and 0 credits — this tool sets the warning field when filters were provided but nothing matched. Use country_codes with granularity='country' for per-country breakdowns. Credit cost: 3 per product returned; 0 on empty results.

company_intent — buying intent signals / what topics is a company researching / buyer journey stage / competitive displacement signals. Returns merged HG + TrustRadius intent for ONE known company in three optional field groups: summary (active/high-signal topic counts, sources, top context types), topics (score, signal level, buyer-journey stage, context types/dispositions, vendors, products), and activities (TrustRadius buyer activities with evidence URLs). Each present group carries its own total count. Use this when you already have a target company and want to know what it is researching, which buyer-journey stage it is in, or whether it shows competitive/displacement signals (context_type_names + vendor_ids). Do NOT use this to find WHICH companies show intent on a topic — use search_companies with its intent filter block for topic-to-company discovery. Do NOT guess topic_ids — resolve a topic name to its hex ID with list_intent_topics first, then pass it here. Scores are bounded 0–100; signal_level buckets into HIGH/MEDIUM/LOW. DEFAULT: omitting fields returns summary only — topics and activities require explicit opt-in (large enterprises can have 500k+ topic rows). Pass fields:["topics"] plus a small limit when you need detail. Topics are geo-expanded by default (one row per state); pass granularity:"global" to collapse to one row per topic. Filters: signal_level, buyers_journey_names (Researching/Evaluating), context_type_names (e.g. "Displacement"), topic_ids, product_category_ids, vendor_ids/product_ids, signal_date window, limit/offset.

company_operating_signals — operating profile / cloud posture / AI trajectory / GenAI readiness / work model / ESG commitment / IoT posture / network modernization / automation stage. Retrieves a company's profile as categorical STAGE LABELS, rolling up HG mentions and AI-maturity data into two groups. The mentions group derives work_model, cloud_posture, esg_commitment, iot_posture, network_modernization, and automation_stage; the genai_maturity group derives ai_trajectory, cloud_depth, genai_readiness, and intent_adoption_gap. Each attribute carries a stage label (e.g. cloud_posture="private-first", ai_trajectory="ai-leader-growing"), a per-signal breakdown, and an intensity — mentions intensity is UNBOUNDED (detection volume, thousands-scale, within-company only); genai_maturity intensity is BOUNDED 0-100. Call this when a user asks about one company's work model, cloud/IoT/network posture, automation stage, or GenAI readiness as summary labels. Do NOT use this to search or rank many companies — use search_companies. 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 installed tech stack/products — use company_technographic instead; for raw buying-intent topic scores, use company_intent. Missing coverage is signaled via data_available:false + no_data_reason, and per-attribute via stage:"no-signal" — these are normal, not errors.

company_spend — IT spend estimate / how much a company spends on IT / technology budget breakdown in USD by category and country, from HG Insights modeled data. Values are modeled dollar estimates (not invoices) — e.g. "Total IT", "Total External IT", "Services", "Software", each split by country. Accepts a batch: pass hg_ids OR domains (up to 25; mutually exclusive — hg_ids wins when both supplied). One entry per matched company; unmatched omitted. Returns spend.all (snake_case rows: spend, category_name, category_id, country_name, country_code) plus spend.all_count. Filter by category_ids or category_names. WARNING: category_names is case-insensitive substring match (max 10); a non-matching name returns 0 rows — prefer category_ids or resolve names via get_product_category. Paginate with max_results and offset. Credits: 3 per requested company. Do NOT use for cloud-vendor-level spend or which cloud/CDN/hosting vendors a company uses — use company_cloud_spend. Do NOT use for AI/ML platform spend — use company_ai_spend. Do NOT use to list installed software/products — use company_technographic.

company_technographic — tech stack / installed software / what technology does a company use; check if a specific product is installed. Returns installs with product_name, vendor_name, intensity (usage signal — higher = broader use), country_code, 5-level category hierarchy, verification dates, and numeric product_id/vendor_id for chaining. Filter by category_ids (32-char hex from get_product_category), vendor_ids, product_ids, product_attribute_ids, or last_verified_date. To filter without resolving IDs, pass vendor_names/product_names (case-insensitive substring, OR within list); prefer vendor_ids/product_ids when already resolved. Global/unattributed installs (country_code: null) included by default; use granularity or country_codes to change scope. total_installs_count and has_more are returned — if has_more is true the installs are partial; narrow with filters or page via offset. Fortune 500 companies can have 1,000+ installs — filter, keep max_results ≤50, use include_description:false or install_fields to stay compact. company_id signal: UNFILTERED → company_id:"" means not in catalog; with a filter it may mean zero matching installs. Non-empty company_id + empty installs = found, no match. Use only when you already know the company (by domains/hg_ids); to find WHICH companies use a product/vendor/category, use search_companies. Do NOT use for usage trend over time (company_install_time_series), department/role usage (company_fai), or spend (company_spend). Provide domains or hg_ids (up to 25).

Enrich a KNOWN person: return their email, phone, seniority/title, social profiles, and employment history. Sourced from EXTERNAL contact providers — Apollo and ZoomInfo — NOT the HG Insights data API. Requires an Apollo or ZoomInfo integration; provider is auto-selected from org configuration unless you set `provider`. Use this when you already have a specific contact and want their missing details — pass a contactId from contact_search (most accurate), an email, a LinkedIn URL, or a first+last name with company domain/name. Batch up to 25 people via `contacts` for bulk enrichment. Do NOT use this to DISCOVER people you don't know yet (e.g. "find the VPs of Marketing at Cisco") — use contact_search for that, then enrich the best matches by id. USES CREDITS, billed per revealed detail on matched contacts (not per person): 0.2 credits per revealed email + 2 credits per revealed phone. revealPhone is OPT-IN (defaults false) because a phone reveal costs 10x an email — only set it when a phone number is specifically required. No-match calls, and calls revealing neither detail, cost 0. Response metadata.dynamicCreditCost reports the actual charge. Do NOT re-enrich a contact already in context — every call is billed regardless of whether the data changed.

Discover PEOPLE (contacts) at a company by job title, seniority, and location — returns a list of individuals, not company facts. Use this to find contacts at an account (e.g. 'who are the VPs of Marketing at Salesforce', 'find IT decision-makers at Cisco') and identify prospects to reach out to. Do NOT use this when: you already know the specific person and want their email/phone — use contact_enrich; you want company-level firmographics (revenue, size, industry) rather than people — use company_firmographic. PROVIDER DEPENDENCY: results come from an EXTERNAL contact provider — Apollo or ZoomInfo — auto-selected from your org's configured integrations (NOT the HG Insights data API). Coverage and fields depend on which provider is configured; with none configured this tool is unavailable. Returns basic contact info (name, title, seniority, LinkedIn, org). Costs 2 credits per call regardless of result count — batch every filter into ONE call. Filter only via the declared parameters: personTitles, personSeniorities, personLocations, organizationLocations, organizationNumEmployeesRanges, contactEmailStatus. There is NO free-text or keyword search — express intent through personTitles and personSeniorities; unknown params are silently ignored (check metadata.warnings if filters seem to have no effect). LARGE COMPANIES: for big accounts an unfiltered search returns a default page that is NOT meaningfully ranked — always pass personTitles and/or personSeniorities. If a search returns 0 results, STOP and report 'no matches found' — do not retry with different title variations. Limit yourself to 2 searches per request (initial + optional pagination). Use contact_enrich to get email/phone for the best matches.

get_product_attribute — resolve / search capability-theme attribute IDs from the HG Insights taxonomy. Attributes are cross-cutting capability tags (e.g. 'Cloud Computing', 'Security', 'SaaS', 'Open Source') — the semantic layer above individual products. This is a taxonomy lookup, NOT a per-product attribute reader: no `product_id` input; returns global taxonomy rows, not attributes attached to one product, and never returns which companies carry an attribute. Free — no credits consumed. Search by `attributeName` (case-insensitive substring, relevance-ranked) or pass known `attributeIds` to fetch specific rows. Provide at least one. Returns rows: `attribute_id`, `attribute_name`, `attribute_description`, `attribute_parent_id` (0 = root theme), `attribute_level` (1 = root, 2 = sub), `product_count` (breadth signal); plus top-level `count`. Taxonomy is hierarchical: 'Cloud' → root 'Cloud Computing' (level 1) plus children like 'Cloud Workloads' (level 2). Use when you need attribute_id(s) to filter product_search_and_enrich or company_technographic. Browse by searching a broad `attributeName` — do NOT enumerate IDs sequentially. Do NOT use to resolve a product category — use `get_product_category`. Do NOT use to resolve a vendor/company — use `get_vendor_information`.

get_product_category — resolve / look up / search taxonomy category names and IDs before an install query. Free — no credits consumed. Matching: categoryName and treeContains use case-insensitive LIKE substring matching — NOT fuzzy or semantic, so misspellings return zero rows with no warning. Use common partial terms rather than guessing full names. treeContains scans the full root → leaf path to scope to a whole branch. categoryCode / categoryId are exact lookups. Returns category rows (category_id, category_code, category_name, category_name_tree, has_category_installs, product_count) plus a top-level count. product_count covers direct products only, not the subtree. Prefer deeper leaf categories (longer category_name_tree) for precise filtering. Use this when: - You need the exact category name/id to pass to company_technographic (set hasInstalls: true to limit to categories with real install data). - You want to explore the category taxonomy by keyword. Do NOT use this when: - You want vendor details or a vendor_id — use get_vendor_information. - You want product attribute data — use get_product_attribute. - You want warehouse table schemas for SQL query planning — use hg_catalog (not product taxonomy). Requires at least one filter. When both categoryId and categoryCode are given they must match the same record (AND logic); if in doubt provide only categoryId.

Get comprehensive information about a software product including overview, pricing, competitors, and integrations from TrustRadius.

Get customer reviews and feedback for a software product with flexible filtering by rating and date.

get_vendor_information — resolve / look up vendor & product IDs / find HG product IDs by vendor name. Resolves a vendor/company name into its HG Insights `vendor_id` (and metadata) so you can filter other tools by that vendor. Free — no credits consumed. Match by `vendor_name` substring (case-insensitive, relevance-ranked) and/or `description` substring, or look up an exact `vendor_id`. Returns ranked vendor rows: `vendor_id` (UInt64), `vendor_name`, `vendor_url`, `vendor_parent_id` (0 or null if top-level), `vendor_company_description`, and `product_count`. Set `include_products: true` to attach up to `products_limit` products per vendor. Matching is substring, not fuzzy: a single query can return several rows — a parent and its subsidiaries (e.g. 'Oracle' → 'Oracle Corporation' and 'Oracle NetSuite') — so confirm `vendor_name`/`vendor_url` before reusing an id. Use this when you must resolve a vendor by name before filtering technographic/spend data — e.g. pass the returned `vendor_id` into `company_technographic`'s vendor filter, or into `company_spend`. Do NOT use this when you already hold a `vendor_id` — pass it straight to the downstream tool. Do NOT use this for the product category taxonomy (use `get_product_category`) or for product attributes (use `get_product_attribute`). Do NOT call it with no filter — always supply `vendor_name`, `description`, or `vendor_id`.

hg_catalog — browse / inspect the HG Insights data warehouse schema (table/column names, join keys, sql_qualifier) to plan an hg_data_query. Returns schema metadata, NOT data rows. Required first step before writing SQL. Schema is stable — call once per session. TWO MODES: (1) ORIENTATION (default, table_names OMITTED): lightweight index of ALL tables as {name, sql_qualifier, description} only — no columns, join keys, or relationships. Cheap first call. (2) DETAIL (table_names SET): full metadata for named tables (columns, order_by, primary_key, join_keys, common_filters, mandatory_predicate, sample_queries) plus relationship edges touching them. Use this when: - Discovering which tables and columns exist before writing SQL for hg_data_query. - Confirming a column's exact name, type, or join key, or a table's sql_qualifier. - Mapping table relationships to plan a multi-table join. Do NOT use this when: - You want to RUN a query and get rows back — call hg_data_query (this tool returns schema only). - You need product/technology taxonomy VALUES (category, vendor, attribute, or product names/IDs) — call get_product_category, get_vendor_information, or get_product_attribute.

list_fai_departments — resolve FAI department name to hex ID / browse department taxonomy / look up department and role IDs before company_fai. Resolver for the Functional Area Intelligence (FAI) taxonomy: lists valid FAI department and role names (with their hex-encoded IDs) from the official HG Insights catalog. Returns each department's hex ID and name plus its roles (role hex ID and name). The catalog is company-independent — this tool does NOT return any company's technology usage. Use this when you need to discover or confirm the canonical name/ID of a department or role before querying departmental data — for example to resolve a valid department_ids value for company_fai, or to map the departmentId/roleId fields returned by company_fai back to human-readable names. Always look up department and role IDs here rather than guessing or fabricating them. Do NOT use this when you want how a company actually uses products across its departments — call company_fai (actual departmental tech usage) with a company_domain or hg_id instead. Optionally filter by department name (case-insensitive partial match) and page with limit/offset.

list_intent_topics — resolve intent topic name to hex ID / browse buying-signal catalog / look up topic IDs before filtering. Lists valid intent topic names + hex IDs from the official HG Insights catalog (20,000+ topics). Returns each topic's hex ID, name, and category. Intent topics are buying signals / research areas that indicate what technologies companies are actively investigating or planning to purchase. This tool ONLY lists/searches the topic vocabulary — it returns no company or intent data. Use this to resolve a topic name to its hex ID before filtering intent by topic: pass the returned id to company_intent's topic_ids parameter, or to search_companies' intent.topics.ids parameter. ALWAYS look up topic IDs with this tool rather than guessing or fabricating them — a bad ID silently matches nothing. Do NOT use this to find which companies show intent on a topic — resolve the id here, then pass it to search_companies' intent.topics.ids filter (company_intent instead reports the topics of ONE already-known company). Do NOT pass natural-language phrases to name: it is a case-insensitive substring match over catalog topic names, not a semantic/ranked search, so 'cloud security infrastructure management' returns nothing — pass a short keyword like 'security' or 'cloud' instead. Catalog names are lowercased. Omitting name lists the entire 20,000+ topic catalog reverse-alphabetically (not by relevance); page through it with limit/offset only when deliberately browsing.

phoenix_get_artifact — fetch/read/retrieve ONE Phoenix artifact's content or URL by id or run id. Pass either a synthetic artifact_id (`{runId}-html`, `{runId}-pdf`, …) OR a bare run_id (UUID) — not both needed. Returns { found: true } with the artifact type, an absolute webapp URL to open it, and the brief's HTML body when it's small enough to inline (large or non-HTML deliverables return the descriptor + URL only, no inlined content). If the run has no artifact (queued, failed, unknown, or an id that doesn't match the run's real type), returns { found: false } rather than erroring. Use this when you already have a specific artifact/run id and want its content or link. Do NOT use it to discover which artifacts exist — use phoenix_list_artifacts; to check a still-running job use phoenix_get_run_status.

phoenix_get_run_status — check/poll the status of a Phoenix agent run / see if a brief is done. Returns the current status (queued | running | succeeded | partially_failed | failed), any generated artifacts (with absolute URLs), the agent name, inputs, timestamps, and credit cost. Use this once the user asks whether their run/brief is done, or to grab the artifact link after a run succeeds. If the run is still queued or running, return the status and run id to the user rather than calling this tool again in a loop; repeated polling within one turn will exhaust the step budget. Do NOT use this to start a run — use phoenix_invoke_agent; to browse every deliverable the org has (not just one run) use phoenix_list_artifacts, and to inline one artifact's HTML body use phoenix_get_artifact.

phoenix_invoke_agent — run/start/kick off a Phoenix agent or workflow / generate a research brief or deliverable. Kicks off one of THIS org's published orchestration agents (e.g. an Account Research Brief) — does not return company data itself; produces a run whose artifact you retrieve later. Returns a run id (UUID); the run executes asynchronously and can take several minutes. After invoking, do NOT repeatedly poll for status — check phoenix_get_run_status at most once or twice; if the run is still queued or running, tell the user the deliverable is generating and give them the run id to check later. Only keep polling if the user explicitly asks you to wait. Use this when the user wants to actually run an agent/generate a deliverable. Do NOT use this to see which agents exist or find an agent_id — use phoenix_list_agents; do NOT use it to check on or fetch the result of an already-started run — use phoenix_get_run_status.

phoenix_list_agents — discover/browse Phoenix agents & workflows available to invoke. Each row returns the agent's instance id (a UUID), name, description, allowed tools, and input schema — the id and input schema are exactly what phoenix_invoke_agent needs. These are Phoenix's own orchestration agents/workflows (e.g. an Account Research Brief that assembles a cited deliverable), NOT the raw HG data tools and NOT the org's stored artifacts. Use this when you need to discover which agents exist or look up an agent_id / its expected inputs before starting a run. Do NOT use this to query company/firmographic/technographic data (call the relevant HG data tool directly) or to browse already-produced deliverables — use phoenix_list_artifacts.

phoenix_list_artifacts — list/browse/enumerate generated deliverables & artifacts already produced in this Phoenix org. Returns one row per run with its synthetic id, artifact type, source (agent vs uploaded), created/expiry dates, and an absolute webapp URL to open it. Narrow with artifact_type, source, or a specific run_id, and page with limit/offset. Filters are structured only — there is NO free-text or content search, so you cannot search by company name or brief text. Use this to enumerate or find recent deliverables across the org. Do NOT use it to fetch one artifact's HTML body — use phoenix_get_artifact; to check a run that may still be in progress use phoenix_get_run_status; to start a new deliverable use phoenix_invoke_agent.

phoenix_upload_artifact — file/ingest/register an externally-produced PDF or HTML deliverable into Phoenix. Provide a publicly-fetchable https URL; Phoenix server-side fetches it (SSRF-guarded), stores it in S3, and it appears in the org's Artifacts tab tagged "Uploaded" — indistinguishable from an agent-generated deliverable. Returns the upload run id and artifact descriptor. Only PDF (application/pdf) and HTML (text/html) up to 25 MB; URL must be https and reachable without auth. Use this when you already have a finished deliverable hosted somewhere and want it filed in Phoenix. Do NOT use this to generate a deliverable from scratch — use phoenix_invoke_agent; do NOT use it to read back an existing artifact — use phoenix_get_artifact or phoenix_list_artifacts.

product_search_and_enrich — search / discover / hydrate products & technologies from the HG Insights catalog. One tool, two actions. action='search' (free) returns a slim, paginated hit list of product_ids matching name/vendor/category/attribute filters — use it to disambiguate a fuzzy product name or browse products under a vendor/category. action='enrich' (1 credit per successful match) hydrates 1-50 known product_ids into full catalog records: product_details, category_info, vendor_info. Typical flow: search to find the id, then enrich the chosen id(s). Unmatched enrich ids are silently omitted and consume no credits. When filtering by category, prefer resolving the exact category first via get_product_category and passing category_id — category_name does a substring match that can silently pick the wrong category (e.g. 'CRM' can match a BPO/outsourcing category). Same guidance applies to attributes via get_product_attribute (use attribute_ids) and vendors via get_vendor_information (use vendor_id). Do NOT use for pricing, competitor narrative, or user reviews. This tool returns HG catalog taxonomy (category/vendor/attributes/install signals) only.

search_companies — company search: search, find, look up, filter, or list COMPANIES to build a prospect list, target-account list, or ICP segment, using the HG Insights v2 search API. The company-discovery / company-list tool (many companies by criteria), not a single-company lookup. Filter groups are separate optional params combined with AND. Use for: prospect/ICP lists (e.g. "US corporate parents with 1K+ employees using Oracle") · filtering by tech installs, intent, or AI/GenAI maturity · whitespace analysis (exclude known accounts via company_identifiers.company_ids NONE_PRESENT). Do NOT use when you already know the domain or hg_id — call company_firmographic. By name: company_identifiers.name (case-insensitive token substring); with an exact domain, company_identifiers.domains is more precise. Resolve product/vendor/category IDs first — invalid IDs are NOT rejected, they match nothing (total_count 0). GUARDRAIL: broad firmographic-only filters (countries=["US"], revenue/employee alone) match hundreds of thousands to millions of records — always pair with a meaningful installs/intent/industry/geography filter (≥2 groups). ⚠ TOKEN BUDGET: rows are lean (four identity columns); limit capped at 100 (default 10). Use 10–50 for exploration, paginate with offset for bulk; total_count reports matches across all pages. Response: companies[]{hg_id, name, domain, domain_normalized} + total_count. AI-maturity/GenAI scores, revenue, employees, country, and industry are filterable/sortable but NOT returned — call company_firmographic with hg_id for those.

search_federal_contracts — broad search of U.S. federal contract awards / signed obligations / USAspending.gov cross-recipient discovery. Combine any filters — awarding agency, NAICS code, PSC code, keywords, obligation value range, contract start-date range, small-business set-aside type, recipient name/UEI — and get back matching awards with recipient, agency/sub-agency, obligated dollar amount, contract type, dates, and place of performance. Results are ranked by amount or date. Use this when you want to discover awards by criteria rather than for one known company — e.g. "which vendors won DoD cybersecurity contracts over $10M?", "recent NAICS 541512 awards", "small-business set-aside awards from the VA", or "who holds contracts with the Department of Energy?". Do NOT use this when: (1) you already know the company and want ITS contract footprint — use company_contracts; (2) you want OPEN solicitations / RFPs still open for bids — use search_gov_opportunities or company_gov_opportunities; (3) you want a company's prime/sub teaming network — use company_gov_relationships. Requires the SAM.gov (Data.gov) integration to be configured.

search_gov_opportunities — broad market search of OPEN U.S. federal solicitations / RFPs / RFQs / SAM.gov opportunities by criteria. Covers solicitations, presolicitations, and sources-sought notices actively seeking bids. Filter by keyword, NAICS code, PSC/classification code, awarding agency, small-business set-aside type, posting-date window, or response-deadline window — without needing a specific vendor. Returns title, agency, notice type, set-aside, NAICS, posting date, response deadline, days-until-deadline, place of performance, and SAM.gov link, plus total count for pagination. Do NOT use when you have a SPECIFIC company and want opportunities relevant to them — use company_gov_opportunities (one company's bid pipeline by NAICS/incumbency). Do NOT use to look up AWARDED/historical contracts (who won, dollar amounts) — use search_federal_contracts. Note: keywords match opportunity TITLES only (not full-notice text); keep them short and general. Requires the SAM.gov (Data.gov) integration to be configured.

search_industries_naics_sic — resolve / translate industry names and codes (NAICS, SIC, HG industry_id) to feed into `search_companies` (`industry_ids`, `naics_codes`, `sic_codes`). Searches across HG industry (23 buckets), NAICS 2012 (~2,200 codes), and SIC 1987 (~1,500 codes) in one call. Use when you have an industry NAME or colloquial term ("fintech", "software publishers") and need its code(s) before an industry-scoped company search — resolve here first. Do NOT use to find companies — that is `search_companies` (pass the codes you resolve). Do NOT use to find what industry a specific company belongs to — call `company_firmographic`; this searches taxonomy definitions, not company records. Do NOT use for technology/product categories ("IaaS","CRM","cloud infrastructure") — use get_product_category. Use cases: q=name fragment · q=code crosswalk · q=numeric prefix→sector+descendants · q="software,saas" multi-term OR · taxonomy=naics|sic|industry for deduped rows · naics_leaf_only=true for 6-digit leaves. Colloquial terms (fintech, saas, etc.) expanded server-side — alias_expansions shows what ran. Zero-result: up to 5 suggestions for near-miss q. NAICS: hierarchy_level + is_leaf — only leaves safe for downstream filters. Downstream: use sic.sic_standard_code ("7372") not sic.sic_code ("I7372"). HG quirk: no Software bucket — 511210/7372→Computer Mfg; 541511/518210→Professional Services. Use NAICS/SIC for tech. Paging: offset_exceeds_total flags paging-past-end. Max limit 500. Free.

sec_filing_section — read a specific SEC filing section / 10-K risk factors / MD&A text / 8-K event disclosure for one company by ticker. Fetches full clean text of one named section from a 10-K (annual), 10-Q (quarterly), or 8-K (current event). Supply ticker, filing type, and section code (topic-to-code mapping in the "section" parameter). Returns the single most recent matching filing. USE when you already know WHICH section of WHICH company to read — e.g. "Microsoft's risk factors", "Apple's MD&A", "AAPL's latest earnings 8-K", "Tesla's legal proceedings". Do NOT use to search filings by keyword or across companies — use sec_full_text_search. For company background use company_enrich or company_firmographic; for non-SEC web info use web_search. SCOPE: US domestic issuers only (10-K / 10-Q / 8-K). Foreign issuers (Barclays, BP, SAP, Toyota) file 20-F / 6-K / 40-F — use sec_full_text_search with filingTypes: ["20-F"] or ["6-K"] for those. FISCAL FILTERING: fiscalYear narrows by calendar year; quarter-precise filtering is NOT supported — use dateFrom/dateTo instead. PROXY STUBS: 10-K sections 10–14 (Directors, Compensation, Security Ownership, Related Party, Accountant Fees) often return a short stub referencing the DEF 14A Proxy Statement — full data not available here if content is under 100 words. 8-K EXHIBIT NOTE: Items like 2.02 (earnings) often return a stub referencing Exhibit 99.1 — for full earnings narrative use sec_full_text_search.

sec_full_text_search — search EDGAR filing content / full-text index for specific terms or phrases across SEC filings. Thin wrapper around the sec-api.io full-text-search API. Accepts ticker symbols and resolves them to CIKs automatically. Use when the user wants filings that mention a term/phrase. Supports AND, OR, NOT, wildcards (*), and exact phrases ("quoted"). Generic words like "award" also match boilerplate (stock awards) — prefer exact phrases. DO NOT USE to extract a named section ("risk factors", "MD&A") from a specific filing — use sec_filing_section (it calls this concept filingType, a singular enum, not formTypes). For company background use company_enrich; for non-SEC web info use web_search. DOMAIN→TICKER: accepts tickers only. Resolve a domain or name to a ticker first (via web_search or company_firmographic). SCOPING: omitting BOTH tickers and formTypes searches the entire EDGAR corpus (~10,000-result flood). Always pass tickers (preferred) or at least formTypes unless a cross-company sweep is intended. DATES: startDate defaults to last 30 days. Annual filings (10-K, 20-F, 40-F) need startDate "2020-01-01" or you get zero results. Returns up to 100 filings per page with direct EDGAR URLs. If resolvedCiks in searchParams is empty after passing tickers, the ticker filter was NOT applied — check it and warnings before treating results as company-specific.

web_search — live web search / browse the internet / find recent news or public facts not in HG Insights' data. Runs a live Tavily search and returns results (title, URL, snippet) plus an optional AI answer summary. Cost: 0.05 credits (basic) or 0.10 credits (advanced, higher relevance). Use when: you need current/breaking news, background on a person or topic, or any fact on the open web rather than HG's structured data. Do NOT use when a purpose-built HG tool covers the request — reach for company_enrich/company_firmographic (profile/size/HQ/industry), company_technographic (installed tech), company_intent (buying signals), or search_companies instead, since those return richer structured HG data. Do NOT use to search SEC filing text — use sec_full_text_search. Do NOT use for general knowledge you already know. OPERATORS: boolean exclusion (-term) is NOT honored — filter unwanted results yourself. VERBOSITY: includeRawContent=true returns the full cleaned page body (no extra cost) but can add ~10KB+ per result — cap with maxContentLength, keep max_results low, and restrict sources with allowedDomains. searchDepth='advanced' improves relevance and snippet quality (not raw-page extraction) at 2x cost.