{ "version": "v2", "tools": [ { "name": "company_ai_maturity", "description": "Scores how advanced a batch of companies is at AI and data, their GenAI buying intent, and which cloud provider each centers on — call it when a user asks any of those about one or more named companies. Returns the raw HG Insights AI-maturity signals per company: ai_maturity_score (0-100 composite), ai_maturity_rank (1 = highest, lower is stronger), ai_maturity_6m_delta (6-month score change, may exceed single digits), ai_product_use (has an AI product installed), genai_intent_score (GenAI buying intent — UNBOUNDED, real values reach the tens of thousands, not a percentage), data_maturity_level (LOW/MEDIUM/HIGH) and data_maturity_score (0-100), plus cloud_centricity (dominant provider) and cloud_intensity (per-provider aws/azure/gcp rolled-up detection volume — UNBOUNDED, values in the thousands are normal, NOT 0-100 scores or dollar amounts; compare providers within a company, never across companies). These are the raw scores as HG returns them — no derived stage labels. Accepts a batch: pass hg_ids and/or domains (up to 25 companies) and receive one entry per matched company under companies[]. IMPORTANT — a company that is not found or has no AI-maturity coverage is omitted from companies[] and echoed in not_found[]. Do NOT use this for AI spend in dollars (use company_ai_spend), for derived AI-adoption stage labels or a broader operating-signals rollup (use company_operating_signals), for full AI/ML tech-stack detail (use company_technographic), or for topic-level buying-intent evidence (use company_intent).", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$" }, "maxItems": 25, "description": "HG Insights company identifiers for a batch AI-maturity lookup (up to 25). Each is 31-32 letters/digits only (hex-like) — not a domain, DUNS, or ticker — obtained from the `id` field of a prior search_companies result or another HG tool. Provide hg_ids and/or domains (at least one is required); both may be combined and are unioned upstream." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 25, "description": "Company registered web domains for a batch AI-maturity lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25) — domains, not company names or tickers. Protocol prefixes (http://, https://), a leading www., and trailing paths/queries are stripped automatically and case is lowercased, so 'https://www.Cisco.com/products' resolves to 'cisco.com'. If you only have a company name, resolve it to a domain with search_companies first. Provide hg_ids and/or domains (at least one is required); both may be combined and are unioned upstream." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company identifier (hex). Empty string when the company is not found." }, "company_domain": { "type": "string", "description": "The company domain that was queried." }, "ai_maturity": { "anyOf": [ { "type": "object", "properties": { "ai_maturity_score": { "type": "number", "description": "Composite AI maturity score (0-100)." }, "ai_maturity_rank": { "type": "number", "description": "Rank by score (1 = highest)." }, "ai_maturity_6m_delta": { "type": "number", "description": "6-month score change." }, "ai_product_use": { "type": "boolean", "description": "Whether the company has an AI product installed." }, "cloud_centricity": { "type": [ "string", "null" ], "description": "Dominant cloud provider (null when unknown)." }, "cloud_intensity": { "type": "object", "properties": { "aws": { "type": "number" }, "azure": { "type": "number" }, "gcp": { "type": "number" } }, "additionalProperties": true, "description": "Per-provider cloud intensity volumes (aws/azure/gcp). UNBOUNDED rolled-up detection volumes (routinely in the thousands) — NOT a 0-100 score or percentage. Comparable within a company, not across companies." }, "data_maturity_level": { "type": [ "string", "null" ], "description": "Data maturity level (null when unknown)." }, "data_maturity_score": { "type": "number", "description": "Data maturity score (0-100)." }, "genai_intent_score": { "type": "number", "description": "GenAI buying-intent score." } }, "additionalProperties": true }, { "type": "null" } ], "description": "The AI-maturity signals for the company, or null when unavailable." } }, "required": [ "company_id", "company_domain", "ai_maturity" ], "additionalProperties": true } }, "not_found": { "type": "array", "items": { "type": "string" }, "description": "Requested domains/hg_ids that HG could not match or has no AI-maturity coverage for." } }, "required": [ "companies", "not_found" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_ai_spend", "description": "Estimated annual AI spend (USD) for companies, broken down by AI category and country, from HG Insights v2. Each row carries an estimated annual dollar amount (spend), the AI category (category_name / category_id — e.g. \"Total AI Spend\", \"AI Software\", \"AI Services\", \"AI Hardware\", with a category_description), and the country (country_name / country_code). Use this when a user asks how much a company spends on AI or GenAI overall, or within a specific AI-spend category. Accepts a batch: pass hg_ids OR domains (up to 25 companies — the HG spend batch cap); the two selectors are mutually exclusive, and when both are supplied hg_ids wins. Returns one entry per matched company under companies[] (unmatched companies are omitted). Filter to specific AI categories with category_ids or category_names. WARNING: category_names is a case-insensitive substring match (max 10 names); a name that is not a substring of any catalog category returns 0 rows — prefer category_ids or resolve exact names via the spend-categories catalog (GET /data-api/v2/catalog/spend_categories). Paginate rows with max_results (1–25) and offset. Credits: 2 per requested company, charged regardless of match or row count. Do NOT use this for total/overall IT spend across all categories — use company_spend. Do NOT use this for cloud-vendor spend breakdowns (AWS/Azure/GCP) — use company_cloud_spend. Do NOT use this for AI adoption/maturity scores (this returns dollar spend, not scores) — use company_ai_maturity.", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 25, "description": "HG Insights company IDs for batch AI-spend lookup (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids OR domains (at least one is required); the two are mutually exclusive — if both are supplied, hg_ids takes precedence." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "minItems": 1, "maxItems": 25, "description": "Company domains for batch AI-spend lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized. Provide hg_ids OR domains; the two are mutually exclusive — if both are supplied, hg_ids takes precedence." }, "category_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter AI-spend rows to these HG AI-category IDs (string array of hex ids, e.g. from get_product_category). Exact-match and the reliable filter — prefer over category_names. Forwarded as `filters.ai_spend.categories.ids` to the upstream." }, "category_names": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Filter AI-spend rows by AI-category name (string array, max 10 — the upstream cap), e.g. [\"AI Software\",\"AI Services\"]. Case-insensitive substring match: a name that is not a substring of any catalog category returns 0 rows — prefer category_ids or resolve exact names via the spend-categories catalog (GET /data-api/v2/catalog/spend_categories). Forwarded as `filters.ai_spend.categories.names` to the upstream." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of AI-spend rows to return (1–25 — the HG spend pagination cap). Forwarded as `pagination.ai_spend.limit` to the upstream." }, "offset": { "type": "integer", "minimum": 0, "description": "Zero-based row offset for pagination. Forwarded as `pagination.ai_spend.offset` to the upstream." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company id (hex). Empty string when not found." }, "company_domain": { "type": "string", "description": "The resolved company domain." }, "ai_spend": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Array of AI-spend rows (snake_case v2 passthrough)." }, "all_count": { "type": "number", "description": "Total number of AI-spend rows in this response." } }, "required": [ "all", "all_count" ], "additionalProperties": true, "description": "AI-spend section from the HG v2 API — thin upstream passthrough. Rows are snake_case (e.g. category_name, country_name, spend)." }, "credits_consumed": { "type": "number", "description": "Credits consumed for this company: a fixed 2 charged per requested company, regardless of whether the company matched or returned any AI-spend rows." } }, "required": [ "company_id", "company_domain", "ai_spend", "credits_consumed" ], "additionalProperties": true } } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_cloud_spend", "description": "Map a company's cloud and internet-infrastructure vendor footprint (HG Insights v2). Use when a user asks WHICH cloud/CDN/hosting/DNS/SaaS vendors a company uses, grouped by service category, when each vendor was first detected, and the company's geographic web-traffic split (North America / EMEA / Asia Pacific / Latin America percentages). Identify the company by company_domain (required) — e.g., 'cisco.com'; hg_id is NOT supported by this v2 endpoint. Returns three parts: company (name/website/logo), traffic_distribution (regional web-traffic %, may be null), and technology_services (each a service_name with a vendors[] list of vendor_name, vendor_logo, and first_seen adoption date). IMPORTANT: despite the 'spend' name, the response contains NO dollar figures — it lists vendors and adoption dates, not billed amounts. Do NOT use for dollar-amount spend: for category-level $ spend use company_spend; for on-premise/general software installs (CRM, databases, security) use company_technographic. Use product_list to filter to specific vendor/product names (server-side fuzzy matching). Default response is capped at 10 vendors per service (vendors_per_service_limit, max 50) and 100 vendors total to keep responses under ~30 KB; raise limit (service categories, default 50, max 200) or set full=true to bypass all caps (may exceed 90 KB on large accounts). The fields param projects each vendor row to a subset of: vendor_name (always included), vendor_logo, first_seen. Requires the hginsights_v2 integration.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Registered/primary web domain of the company to look up cloud vendors for (e.g., 'cisco.com'). Required — this v2 endpoint is domain-only and does NOT accept hg_id. Protocol prefixes (http://, https://), a leading www., and any trailing path/query/fragment are accepted and stripped automatically; case is normalized to lowercase. Max 253 chars. Must resolve to a company in HG's cloud-vendor database or the call returns a 'Company not found' error." }, "product_list": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Optional vendor/product names to narrow the results to (e.g., ['Amazon EC2', 'OpenDNS']). Matched fuzzily server-side against detected vendor names, so approximate names still match; service categories with no matching vendor are dropped. Omit or pass [] to return every detected vendor." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of technology_services (service-category) entries to return (default: 50, max: 200). Ignored when full=true." }, "vendors_per_service_limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of vendors to include per technology_services (service-category) entry (default: 10, max: 50). Ignored when full=true. The total vendor count across all services is also capped at 100 to keep responses small." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_name", "vendor_logo", "first_seen" ] }, "description": "Project each vendor row to this subset of fields. vendor_name is always included regardless of this list. Ignored when full=true." }, "full": { "type": "boolean", "default": false, "description": "When true, return the full payload with no limit, no per-service vendor cap, no total-vendor budget, and no field projection. Default: false (all caps apply). Use full=true only when you genuinely need the unbounded payload — large accounts may exceed 90 KB." } }, "required": [ "company_domain" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name" }, "website": { "type": "string", "description": "Company website" }, "logo": { "type": [ "string", "null" ], "description": "Company logo URL (null when unavailable)" } }, "required": [ "name", "website" ], "additionalProperties": true, "description": "Company information" }, "traffic_distribution": { "anyOf": [ { "type": "object", "properties": { "north_america_percent": { "type": [ "number", "null" ], "description": "Percentage of traffic from North America" }, "emea_percent": { "type": [ "number", "null" ], "description": "Percentage of traffic from EMEA" }, "asia_pacific_percent": { "type": [ "number", "null" ], "description": "Percentage of traffic from Asia Pacific" }, "latin_america_percent": { "type": [ "number", "null" ], "description": "Percentage of traffic from Latin America" } }, "additionalProperties": true }, { "type": "null" } ], "description": "Geographic distribution of company's web traffic (may be null for some companies)" }, "technology_services": { "type": "array", "items": { "type": "object", "properties": { "service_name": { "type": "string", "description": "Name of the technology service category" }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "vendor_name": { "type": "string", "description": "Name of the vendor" }, "vendor_logo": { "type": [ "string", "null" ], "description": "Vendor logo URL (null when unavailable; omitted when projected away via fields)" }, "first_seen": { "type": [ "string", "null" ], "description": "Date when vendor was first detected (may be null; omitted when projected away)" } }, "required": [ "vendor_name" ], "additionalProperties": true } } }, "required": [ "service_name", "vendors" ], "additionalProperties": true }, "description": "Technology services and vendors used by the company" } }, "required": [ "company", "traffic_distribution", "technology_services" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_contracts", "description": "Retrieve contract intelligence for a specific company — ICT outsourcing deals (via GSIs such as Accenture, IBM, Cognizant) and U.S. federal government contract awards (USAspending.gov). Accepts a batch: pass hg_ids and/or domains (up to 25 companies) and receive one entry per company under companies[]. Returns vendor name, deal value, contract title/summary, dates, service lines, pricing, and customer context. Federal enrichment (include_federal_contracts) is single-company only — pass exactly one hg_id or domain. IMPORTANT: with include_federal_contracts=true, company_name (exact legal entity, e.g. \"Booz Allen Hamilton\") is REQUIRED when the domain does not resolve to an HG record (empty organization_id) — without it federal search can return contracts_found:0; recommended otherwise. Data is from publicly announced contracts and is not comprehensive. Federal data is OFF by default — enable it for defense/government IT vendors or any suspected federal awardee (requires the datagov integration). Note: in federal records, vendor_name is the awarding agency, not a commercial vendor. Use this when a user asks: which IT vendors or GSIs a company works with; what outsourcing contracts a company has awarded; what U.S. federal awards a specific company has won. Do NOT use when: searching across many companies for federal contracts by keyword, NAICS code, or agency — use search_federal_contracts instead. Looking for prime/subcontract teaming relationships on government deals — use company_gov_relationships instead. Estimating a company's vendor spend by category — use company_spend instead. Looking for open solicitations a company might bid on (not past awards) — use company_gov_opportunities instead. Do NOT use for company size, industry, revenue, or HQ location — use company_firmographic instead.", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$" }, "maxItems": 25, "description": "HG Insights company IDs for batch contract lookup (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids or domains (at least one is required); both may be combined. NOTE: include_federal_contracts requires exactly one company across hg_ids+domains." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 25, "description": "Company domains for batch contract lookup (e.g. [\"salesforce.com\", \"cisco.com\"], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized. Provide hg_ids or domains; both may be combined. NOTE: include_federal_contracts requires exactly one company." }, "company_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Legal or common name of the company (e.g., \"Booz Allen Hamilton\", \"Palantir Technologies\"). For federal lookups (include_federal_contracts=true): REQUIRED on the name-only path — i.e. when the domain does not resolve to an HG record (empty organization_id) such as many defense contractors — since providing the exact legal entity name is what enables federal data when domain resolution fails. When the company resolves in HG, company_name is recommended as a safety net (the tool otherwise derives the federal search key from the resolved record)." }, "active_only": { "type": "boolean", "default": false, "description": "When true, returns only currently active contracts (end_date >= today or no end_date). When false (default), returns all contracts regardless of status." }, "vendor_name": { "type": "string", "description": "Restrict to contracts with this counterparty vendor/GSI (e.g. \"Accenture\", \"Microsoft\"). Sent server-side as an upstream vendor-name filter, so pass the full vendor name rather than a fragment." }, "min_deal_value": { "type": "number", "description": "Only return contracts whose total deal value is at least this many USD (e.g. 1000000 for $1M+). Applied client-side to the returned page." }, "max_deal_value": { "type": "number", "description": "Only return contracts whose total deal value is at most this many USD. Applied client-side to the returned page." }, "start_date_after": { "type": "string", "description": "Filter contracts starting after this date (ISO format YYYY-MM-DD, e.g., \"2022-01-01\"). Applied to the start_date field." }, "start_date_before": { "type": "string", "description": "Filter contracts starting before this date (ISO format YYYY-MM-DD, e.g., \"2024-12-31\"). Applied to the start_date field." }, "end_date_before": { "type": "string", "description": "Filter contracts ending before this date (ISO format YYYY-MM-DD, e.g., \"2025-12-31\")." }, "end_date_after": { "type": "string", "description": "Filter contracts ending after this date (ISO format YYYY-MM-DD, e.g., \"2025-01-01\")." }, "limit": { "type": "number", "default": 50, "description": "Maximum number of contracts to return (default: 50, max: 100)." }, "offset": { "type": "number", "default": 0, "description": "Pagination offset — skip the first N contracts (default: 0). Use when has_more:true in a result: re-call with offset = previous_offset + limit to fetch the next page. In batch calls (multiple hg_ids or domains), offset applies uniformly to all requested companies." }, "include_federal_contracts": { "type": "boolean", "default": false, "description": "Include U.S. federal government contract data from USAspending.gov. Requires the datagov integration (SAM.gov API key) to be configured. Always set to true for defense contractors, government IT vendors, and any company suspected of having federal awards. Pass company_name (exact legal name) alongside this flag: it is REQUIRED on the name-only path (domain does not resolve to an HG record / empty organization_id), where omitting it lets the federal search key degrade to the bare domain and can silently return 0 contracts; it is recommended as a safety net when the company resolves in HG. Federal lookup requires the domain to resolve to an HG company record (non-empty organization_id). If organization_id is empty in the response, the domain is not in the HG database and federal data cannot be fetched regardless of this flag — use search_federal_contracts with recipientName instead for those companies. Note: naics_code and psc_code in returned federal records are often empty. When enabled, response includes federal awards merged with HG contracts, SAM.gov entity data (UEI, CAGE code, business types), and federal data status metadata." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "The company domain that was queried (empty string when the request was keyed by hg_id and the upstream did not return a domain — see requested_hg_id in that case)" }, "requested_hg_id": { "type": "string", "description": "Echo of the requesting hg_id, present only when this row was keyed by an hg_id and the upstream omitted the domain (so callers can key the result back without a fabricated domain)" }, "organization_id": { "type": "string", "description": "The HG Insights company identifier" }, "contract_count": { "type": "number", "description": "Number of contracts on the RETURNED PAGE (after limit + client-side filters). For the full matching total, use total_matching_contracts" }, "total_contract_value": { "type": [ "string", "null" ], "description": "Total value of the contracts on the RETURNED PAGE, formatted as currency (null when unavailable). Not the grand total across all pages" }, "total_contract_value_amount": { "type": "number", "description": "Total value of the contracts on the RETURNED PAGE as a numeric amount. Not the grand total across all pages" }, "total_matching_contracts": { "type": "number", "description": "Total number of contracts matching the query server-side (upstream count), across all pages. contract_count is the page-scoped subset of this" }, "contracts": { "type": "array", "items": { "type": "object", "properties": { "contract_id": { "type": "string", "description": "Contract identifier (upstream id field)" }, "vendor_name": { "type": "string", "description": "Primary vendor name (from primary_vendor.name)" }, "title": { "type": "string", "description": "Headline summary of the deal" }, "summary": { "type": "string", "description": "Long-form description of the deal" }, "deal_value": { "type": "string", "description": "Deal value formatted as currency" }, "deal_value_amount": { "type": "number", "description": "Deal value in USD" }, "start_date": { "type": "string", "description": "Contract start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "description": "Contract end date (YYYY-MM-DD)" }, "announcement_date": { "type": "string", "description": "Date the deal was announced (YYYY-MM-DD)" }, "contract_term_months": { "type": "number", "description": "Contract term in months" }, "customer_name": { "type": "string", "description": "Legal name of the customer company" }, "signing_country": { "type": "string", "description": "Country the contract was signed in" }, "customer_drivers": { "type": "string", "description": "Stated business driver for the contract" }, "contract_structure": { "type": "string", "description": "e.g. \"Single Vendor\"" }, "contract_event": { "type": "string", "description": "e.g. \"New\"" }, "bid_process": { "type": "string", "description": "e.g. \"Competitive\"" }, "service_lines": { "type": "array", "items": {}, "description": "Service line detail" }, "performance_criteria": { "type": "array", "items": { "type": "string" }, "description": "Performance-criteria clauses for the contract." }, "pricing_structure": { "type": "string", "description": "Contract pricing-structure description." }, "larger_contract": { "type": "boolean", "description": "Whether this record is part of a larger contract." }, "source": { "type": "string", "enum": [ "hg", "usaspending" ], "description": "Data source (present when include_federal_contracts=true)" }, "federal_data": { "type": "object", "properties": { "award_id": { "type": "string" }, "awarding_agency": { "type": "string" }, "awarding_sub_agency": { "type": "string" }, "funding_agency": { "type": "string" }, "contract_type": { "type": "string" }, "set_aside_type": { "type": "string" }, "naics_code": { "type": "string" }, "naics_description": { "type": "string" }, "psc_code": { "type": "string" }, "psc_description": { "type": "string" }, "place_of_performance": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true, "description": "Federal contract details (only when source='usaspending')" } }, "required": [ "contract_id", "vendor_name", "deal_value", "deal_value_amount" ], "additionalProperties": true }, "description": "List of contracts" }, "has_more": { "type": "boolean", "description": "Whether there are more contracts available beyond the returned set; re-call with offset = previous_offset + limit to fetch the next page" }, "sam_entity": { "type": "object", "properties": { "uei": { "type": "string", "description": "Unique Entity Identifier" }, "cage_code": { "type": "string", "description": "Commercial and Government Entity code" }, "legal_business_name": { "type": "string" }, "registration_status": { "type": "string", "enum": [ "Active", "Inactive" ] }, "business_types": { "type": "array", "items": { "type": "string" }, "description": "e.g., Large Business, 8(a), HUBZone" }, "naics_codes": { "type": "array", "items": { "type": "string" } }, "psc_codes": { "type": "array", "items": { "type": "string" } }, "sam_registration_date": { "type": "string" }, "sam_expiration_date": { "type": "string" } }, "additionalProperties": true, "description": "SAM.gov entity registration data (present when include_federal_contracts=true and entity is resolved)" }, "federal_data_status": { "type": "object", "properties": { "resolved": { "type": "boolean", "description": "Whether the federal data fetch completed" }, "sam_entity_found": { "type": "boolean", "description": "Whether a SAM.gov entity was found" }, "contracts_found": { "type": "number", "description": "Number of federal contracts found" }, "data_as_of": { "type": "string", "description": "Date of data freshness" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Any errors during federal data fetch" } }, "additionalProperties": true, "description": "Metadata about the federal data fetch (present when include_federal_contracts=true)" } }, "required": [ "company_domain", "organization_id", "contract_count", "total_contract_value", "total_contract_value_amount", "total_matching_contracts", "contracts", "has_more" ], "additionalProperties": true } } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_enrich", "description": "Enrich a BATCH of up to 25 companies with multiple data sections in a single call, returned as { companies: [...] }. Select companies with hg_ids and/or domains (at least one required; both may be combined and are unioned). Companies with no match are omitted from the array — do not assume positional alignment with your input. Choose sections with fields: firmographics (name, location, industry, size, hierarchy), spend (IT spend by category), ai_spend (AI spend by category — opt-in, request explicitly), technographics (installed tech stack), contracts (contract records), ai_maturity (AI/data maturity scores), cloud_maturity (per-provider cloud footprint), statistics (aggregated summaries), market_benchmarks (peer-group positioning). Defaults to firmographics + technographics + spend when fields is omitted. The same fields/filters/pagination apply to every company in the batch; credit cost scales with the number of companies returned. contracts/statistics/market_benchmarks are entitlement-gated — if your org lacks access they are omitted and listed under unavailableSections rather than failing the call. Use this when you have a known set of companies (by hg_id or domain) and need 2+ data sections — a broad profile — in one round-trip. Do NOT use when: you only need firmographics for one company or a simple lookup — use company_firmographic (faster, cheaper, smaller payload, and accepts a batch too); you are discovering/filtering companies you do not yet have identifiers for — use search_companies; you need the full multi-level ownership tree (subsidiaries, siblings) — use company_hierarchy; you need exactly one section — prefer the dedicated single-section tool (company_firmographic, company_technographic, company_spend). The interactive dashboard renders the first returned company (batches show a banner).", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$" }, "maxItems": 25, "description": "HG Insights company IDs for batch enrichment (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids or domains (at least one is required); both may be combined and are unioned." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 25, "description": "Company domains for batch enrichment (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are stripped automatically; case is normalized. Provide hg_ids or domains; both may be combined." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "firmographics", "spend", "ai_spend", "technographics", "contracts", "ai_maturity", "cloud_maturity", "statistics", "market_benchmarks" ] }, "description": "Which data sections to return. One or more of: firmographics, spend, ai_spend, technographics, contracts, ai_maturity, cloud_maturity, statistics, market_benchmarks. Defaults to ['firmographics','technographics','spend'] when omitted (ai_spend is opt-in — request it explicitly). contracts/statistics/market_benchmarks are entitlement-gated and are omitted (with unavailableSections noting them) if your org lacks access." }, "filters": { "type": "object", "properties": { "spend": { "type": "object", "properties": { "categories": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "ai_spend": { "type": "object", "properties": { "categories": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "technographics": { "type": "object", "properties": { "country": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "codes" ], "additionalProperties": false }, "installs": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "global", "country" ] }, "localized": { "type": "boolean" } }, "additionalProperties": false }, "product_attributes": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "ids" ], "additionalProperties": false }, "product_categories": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "product_last_verified_date": { "type": "object", "properties": { "min": { "type": "string" }, "max": { "type": "string" } }, "additionalProperties": false }, "products": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "vendors": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "names": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Optional upstream filters, forwarded verbatim. `spend.categories.{ids,names}`, `ai_spend.categories.{ids,names}` and `technographics.{country,installs,product_attributes,product_categories,product_last_verified_date,products,vendors}` — see the /v2/companies/enrich contract. Filters only apply to the matching section. IMPORTANT: category and product `names` filters require EXACT catalog strings (e.g. \"Infrastructure-as-a-Service (IaaS)\", not \"Cloud Infrastructure\"; \"Cloud Services\", not \"Cloud Infrastructure\") — resolve canonical names via get_product_category or get_vendor_information first when unsure. A non-matching name silently returns no data for that section, indistinguishable from a true empty result." }, "pagination": { "type": "object", "properties": { "spend": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ai_spend": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "technographics": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Optional independent pagination for the nested spend, ai_spend and technographics arrays: `{ spend?: {limit,offset}, ai_spend?: {limit,offset}, technographics?: {limit,offset} }`. limit is 0-100." }, "contracts": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "active_only": { "type": "boolean" }, "vendor_names": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "additionalProperties": false }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "description": "Optional contracts request block `{ filters?: {active_only, vendor_names (max 10)}, limit?, offset? }`. Requires 'contracts' in fields AND the contracts entitlement — providing this block alone does not return contracts." }, "full": { "type": "boolean", "default": false, "description": "When true, return every row per section (technographic installs, spend/ai_spend rows, contract records) instead of the default per-section caps that keep a call under the 40KB inline limit. Use only when you need the complete section arrays. Default: false." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company id (hex)." }, "company_domain": { "type": "string", "description": "The resolved company domain." }, "found": { "type": "boolean", "description": "Always true for entries present in the array (unmatched companies are omitted)." }, "header": { "type": "object", "properties": { "company_name": { "type": "string", "description": "The company's name from firmographics; falls back to the company domain when firmographics wasn't requested (always a non-empty string)." }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "employee_count": { "type": [ "string", "number", "null" ] }, "revenue": { "type": [ "string", "number", "null" ] }, "location": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "website": { "type": [ "string", "null" ] }, "founded_year": { "type": [ "number", "null" ] }, "company_type": { "type": [ "string", "null" ] } }, "additionalProperties": true, "description": "Company header (drives the dashboard). Populated from firmographics when requested; other fields fall back to null when firmographics was not fetched." }, "key_metrics": { "type": "object", "properties": { "it_spend": { "type": [ "number", "null" ] }, "fortune_500_rank": { "type": [ "number", "null" ] }, "forbes_2000_rank": { "type": [ "number", "null" ] }, "top_tech_categories": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The sections requested." }, "unavailableSections": { "type": "array", "items": { "type": "string" }, "description": "Requested sections that were dropped because the org is not entitled to them." }, "firmographics": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Firmographic record (upstream passthrough, snake_case)." }, "spend": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "IT spend: { all: [...], all_count }." }, "ai_spend": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "AI spend: { all: [...], all_count } (opt-in; only present when ai_spend is in fields)." }, "technographics": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Tech installs: { installs: [...], installs_count }." }, "contracts": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Contracts: { count, records: [...] } (records passed through unchanged)." }, "ai_maturity": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "AI/data maturity scores (upstream passthrough)." }, "cloud_maturity": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Cloud footprint counts/percentages (upstream passthrough)." }, "statistics": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Aggregated summaries (upstream passthrough)." }, "market_benchmarks": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Peer-group positioning (upstream passthrough)." } }, "required": [ "company_id", "company_domain", "found", "header", "key_metrics", "fields" ], "additionalProperties": true }, "description": "One enriched company per matched selector." } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true, "title": "Company Enrich" } }, { "name": "company_fai", "description": "Functional Area Intelligence (FAI): the DEPARTMENTAL / functional-area breakdown of technology usage at ONE company — which departments, roles, and locations use detected technologies, with per-department usage share and signal strength, per-role usage share, and decision-maker / influencer presence and titles. Provide exactly one company selector: a company domain (e.g. \"cisco.com\") OR an HG Insights company ID (hg_id). Narrow results with product_ids and/or vendor_ids (numeric HG IDs — resolve these via company_technographic before calling; do NOT guess numeric IDs), plus optional country, department_ids and role_ids (hex IDs from list_fai_departments — do NOT guess), has_decision_maker, has_influencer, and last_verified_date filters. MUTEX: department_ids and sort_field cannot be used together — the upstream rejects that combination; filter by departments OR sort, not both. Sort with sort_field + sort_direction; paginate with limit / offset (total_count in the response is the total matches before pagination). USE this when the user asks which departments, roles, or locations at a company use a specific technology, or wants decision-maker / influencer contacts by department. Do NOT use this to check whether a company uses a technology at all, or for whole-company install counts — use company_technographic (it also returns the product_id values to feed back in here). Do NOT use this to resolve or list valid FAI department / role IDs and names — use list_fai_departments first.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to analyze (e.g., \"cisco.com\"). Provide exactly one of company_domain or hg_id. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company ID (32 alphanumeric characters). Provide exactly one of company_domain or hg_id. Obtain from a previous company_search / company_firmographic result." }, "product_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 20, "description": "HG Insights numeric product IDs — keep only FAI rows for these products (max 20). Get them from the product_id field of a company_technographic result for this same company. There is no product-name filter here; resolve names to IDs first. Omit to include all products." }, "vendor_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 20, "description": "HG Insights numeric vendor IDs — keep only FAI rows for products from these vendors (max 20). Resolve via get_vendor_information / vendor lookups. Omit to include all vendors." }, "department_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "FAI department IDs (hex). Call list_fai_departments first to discover valid IDs — do NOT guess or fabricate them. Omit to include all departments." }, "role_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "FAI role IDs (hex-encoded). Narrows results to specific roles. Obtain role IDs from the role_id field of a prior company_fai response." }, "country": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "minItems": 1, "maxItems": 20, "description": "ISO 3166-1 alpha-2 country codes (e.g. [\"US\", \"CA\"]) — keep only rows where the signal was detected in these countries. Case-insensitive (normalized to upper)." }, "has_decision_maker": { "type": "boolean", "description": "When true, keep only rows where a decision maker for the product is present (see the row's decision_maker_titles). Omit to include rows regardless." }, "has_influencer": { "type": "boolean", "description": "When true, keep only rows where an influencer for the product is present (see the row's influencer_titles). Omit to include rows regardless." }, "last_verified_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO 8601 date (YYYY-MM-DD, e.g. \"2024-01-01\"). Keep only rows whose last_verified_at is on or after this date." }, "sort_field": { "type": "string", "enum": [ "department_usage_share", "department_signal_strength", "role_usage_share", "role_signal_strength_at_location", "product_name", "department_name", "role_name", "country_name" ], "description": "Field to sort results by. One of: department_usage_share, department_signal_strength, role_usage_share, role_signal_strength_at_location, product_name, department_name, role_name, country_name. role_usage_share = % of role holders at that location using the product. role_signal_strength_at_location = detection confidence at that location (can be 0 when role presence is detected but no usage-share data exists)." }, "sort_direction": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "description": "Sort direction (default DESC). Only applied when sort_field is provided." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum number of FAI rows to return (default: 50, max: 1000). Paginate with offset; total_count gives the total before pagination." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset (default: 0, maximum: 10 000). Use with limit to page through results. The upstream API caps offset at 10 000 regardless of total_count. For large companies where total_count exceeds 10 000, apply filters (department_ids, product_ids, country, last_verified_date) to reduce total_count before paginating." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string", "description": "HG Insights company ID (hex-encoded)." }, "domain": { "type": [ "string", "null" ], "description": "Company domain." }, "name": { "type": [ "string", "null" ], "description": "Company name." } }, "additionalProperties": true, "description": "Company context (omitted when upstream returns none)." }, "total_count": { "type": "number", "description": "Total matching FAI records before pagination." }, "data": { "type": "array", "items": { "type": "object", "properties": { "country_name": { "type": "string" }, "state_name": { "type": "string" }, "city_name": { "type": "string" }, "department_id": { "type": "string", "description": "Department ID (hex-encoded)." }, "department_name": { "type": "string" }, "department_signal_strength": { "type": "number" }, "department_usage_share": { "type": "number" }, "has_decision_maker": { "type": "boolean" }, "has_influencer": { "type": "boolean" }, "decision_maker_titles": { "type": "array", "items": { "type": "string" } }, "influencer_titles": { "type": "array", "items": { "type": "string" } }, "first_verified_at": { "type": "string" }, "last_verified_at": { "type": "string" }, "product_id": { "type": "number" }, "product_name": { "type": "string" }, "vendor_id": { "type": "number" }, "vendor_name": { "type": "string" }, "role_id": { "type": [ "string", "null" ] }, "role_name": { "type": [ "string", "null" ] }, "role_signal_strength_at_location": { "type": [ "number", "null" ] }, "role_usage_share": { "type": [ "number", "null" ] } }, "additionalProperties": true }, "description": "FAI rows — one per department/product/location/role combination." } }, "required": [ "total_count", "data" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_firmographic", "description": "Batch firmographic lookup for one or more known companies. Call this when the user asks about a company's firmographics — name, location, industry, employee/revenue size, corporate hierarchy, or global HQ — or wants the same facts for a short list of companies. Use this (not company_enrich) for firmographic-only questions: it is faster and returns a smaller payload than a full profile. Each entry returns the HG record with name, industry_name, employees_total/band, revenue_total/band, city/state/country, NAICS/SIC codes, Fortune 500 / Forbes 2000 rank, it_spend, company_level, and the corporate-parent / global_hq_* hierarchy. company_id is that entry's HG company id (hex); for a subsidiary or intermediate parent, chain on global_hq_id to reach the ultimate parent (equal to company_id for a Group HQ, where the duplicate global_hq_* fields are dropped). Selection is batch-only: pass hg_ids OR domains (mutually exclusive — not both; up to 25 each). The response is always { companies: [...] }, one entry per matched company, with no found/message flag. No-match sentinel: unmatched companies are omitted, so a fully unmatched request returns an empty array ({ companies: [] }) — check that each requested id/domain has a corresponding entry. When the org has a Snowflake integration configured, its own account record for each company is attached as customer_data. Do NOT use this when: the firmographic data is already in context (e.g. from a prior company_enrich call); you need the full multi-level ownership tree (subsidiaries, siblings, depth traversal) — use company_hierarchy; you need a full multi-signal profile (technographic + intent + spend) — use company_enrich; or you are discovering companies you lack ids or domains for — use search_companies.", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$" }, "maxItems": 25, "description": "HG Insights company IDs to look up, as a batch array (up to 25). Each id is 31-32 alphanumeric/hex chars, obtained from a prior search_companies or company_enrich result. Each returns one entry under companies[], in request order; ids that upstream cannot match are omitted. Provide EITHER hg_ids OR domains — exactly one selector is required, they are mutually exclusive, and passing both is rejected." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 25, "description": "Company domains to look up, as a batch array (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes (http://, https://), a leading www., and trailing paths/queries are stripped automatically, and case is normalized. Each domain resolves to the matching HG entity (e.g. linkedin.com → LinkedIn Corporation, company_level \"Corporate Parent\", with Microsoft surfaced under global_hq_*) and returns one entry under companies[]; domains that upstream cannot match are omitted. Provide EITHER hg_ids OR domains — exactly one selector is required, they are mutually exclusive, and passing both is rejected." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company identifier (hex). Empty string when no company matched the query." }, "company_domain": { "type": "string", "description": "The company domain that was queried (or the domain returned by the provider)." }, "firmographics": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name." }, "domain": { "type": [ "string", "null" ], "description": "Company domain (null when unavailable)." }, "domain_normalized": { "type": "string", "description": "Normalized company domain." }, "city_name": { "type": "string", "description": "HQ city." }, "state_name": { "type": "string", "description": "HQ state/province." }, "country_code": { "type": [ "string", "null" ], "description": "HQ ISO country code (null when unavailable)." }, "country_name": { "type": "string", "description": "HQ country name." }, "continent_name": { "type": "string", "description": "HQ continent." }, "subcontinent_name": { "type": "string", "description": "HQ subcontinent." }, "geopolitical_name": { "type": "string", "description": "HQ geopolitical region." }, "postal_code": { "type": "string", "description": "HQ postal/zip code." }, "employees_total": { "type": [ "number", "null" ], "description": "Exact employee count (null if only a band is available)." }, "employees_band": { "type": "string", "description": "Banded employee range (e.g. \"10,001-50,000\")." }, "revenue_total": { "type": [ "number", "null" ], "description": "Annual revenue in USD (null if only a band is available)." }, "revenue_band": { "type": "string", "description": "Banded revenue range." }, "industry_id": { "type": [ "number", "string" ], "description": "HG industry id." }, "industry_name": { "type": "string", "description": "HG industry name." }, "naics_code": { "type": "string", "description": "NAICS classification code." }, "naics_name": { "type": "string", "description": "NAICS classification name." }, "sic_codes": { "type": "array", "items": { "type": "string" }, "description": "SIC classification codes." }, "sic_names": { "type": "array", "items": { "type": "string" }, "description": "SIC classification names." }, "forbes_2000_rank": { "type": [ "number", "null" ], "description": "Forbes 2000 ranking (null if not ranked)." }, "fortune_500_rank": { "type": [ "number", "null" ], "description": "Fortune 500 ranking (null if not ranked)." }, "it_spend": { "type": [ "number", "null" ], "description": "Estimated IT spend in USD (null if not available)." }, "company_level": { "type": "string", "description": "UCM level (Group HQ, Corporate Parent, Domestic Parent, Site, Subsidiary)." }, "corporate_parent_id": { "type": [ "string", "null" ], "description": "Corporate parent hex id (null for a top-level/GHQ company)." }, "corporate_parent_name": { "type": [ "string", "null" ], "description": "Corporate parent name (null for a top-level/GHQ company)." }, "global_hq_id": { "type": "string", "description": "Ultimate-parent (global HQ) hex company id — the chaining target for a subsidiary. Omitted for a Group HQ, where it equals company_id. " }, "global_hq_name": { "type": "string", "description": "Global HQ company name." }, "global_hq_country_code": { "type": "string", "description": "Global HQ ISO country code." } }, "additionalProperties": true, "description": "Firmographic record passed through from the HG v2 API (snake_case fields). global_hq_* fields carry the ultimate-parent record for a subsidiary; for a Group HQ they duplicate the base fields and are omitted. company_level indicates the entity tier: Group HQ, Corporate Parent, Domestic Parent, Site, or Subsidiary. For a subsidiary, chain enrichment tools on global_hq_id (not company_id) to reach the ultimate parent." }, "customer_data": { "type": "object", "properties": {}, "additionalProperties": true, "description": "The org's own account record for this company, joined by domain from Snowflake (present only when a Snowflake integration is configured and a row matched)." } }, "required": [ "company_id", "company_domain", "firmographics" ], "additionalProperties": true } } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_gov_opportunities", "description": "Find open U.S. federal solicitations (RFPs) that ONE named company — given by its domain — is positioned to bid on, either as the likely incumbent or a probable bidder. Resolves the domain to a SAM.gov entity (UEI/CAGE + registered NAICS codes), pulls the company's existing federal awards from USAspending.gov, then searches active SAM.gov opportunities on the entity's top 3 NAICS codes and labels each match incumbent / likely_bidder / unknown by whether the company already holds awards with that agency and/or is registered for that NAICS. Returns opportunity title, agency, response deadline, days until deadline, match reason, and SAM.gov link. Requires the SAM.gov (Data.gov) integration to be configured.\n\nUse when a user names ONE specific company and asks about ITS bid pipeline — whether it holds or could win federal contracts, is an incumbent, or has open solicitations to bid on.\n\nDo NOT use for cross-company opportunity browsing by keyword/agency/NAICS with no target company — use search_gov_opportunities. Do NOT use for prime/subcontractor teaming relationships or a company's past agency award history — use company_gov_relationships. For a company's existing awarded contracts already held (not open opportunities) use company_contracts.\n\nRESULT INTERPRETATION: check resolutionStatus. \"resolved\" means the company was found in SAM.gov (matchedEntityName holds its canonical legal name); a \"resolved\" company with totalOpportunities: 0 is NORMAL and expected for most companies — do NOT retry or invent a reason. \"not_found\" (matchedEntityName null) means the company is not registered in SAM.gov, so no opportunity search ran.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to look up (e.g., \"boozallen.com\"). Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "includeIncumbentOnly": { "type": "boolean", "default": false, "description": "When true, return ONLY opportunities classified \"incumbent\" (company already holds awards with that agency AND is registered for the opportunity's NAICS) — the highest-confidence matches. When false (default), also include \"likely_bidder\" and \"unknown\" NAICS-overlap matches." }, "daysUntilDeadline": { "type": "number", "minimum": 1, "maximum": 365, "description": "Deadline window in days from now; keeps only opportunities whose SAM.gov response deadline falls within the next N days (e.g. 90 = closing within ~3 months). Omit for no deadline cutoff. Whole days, 1-365." }, "limit": { "type": "number", "minimum": 1, "maximum": 50, "default": 25, "description": "Maximum opportunities to return after incumbent/likely-bidder ranking (highest-confidence first). Integer 1-50, default 25." } }, "required": [ "companyDomain" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Resolved company name from SAM.gov" }, "companyDomain": { "type": "string", "description": "The company domain that was looked up" }, "samEntity": { "type": "object", "properties": { "uei": { "type": "string" }, "cageCode": { "type": "string" }, "legalBusinessName": { "type": "string" } }, "additionalProperties": true, "description": "SAM.gov entity registration details" }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "opportunityId": { "type": "string" }, "title": { "type": "string" }, "agency": { "type": "string" }, "responseDeadline": { "type": "string" }, "daysUntilDeadline": { "type": "number" }, "incumbentStatus": { "type": "string", "enum": [ "incumbent", "likely_bidder", "unknown" ] }, "matchReason": { "type": "string" }, "link": { "type": "string" } }, "additionalProperties": true }, "description": "Matching federal opportunities with incumbent status" }, "totalOpportunities": { "type": "number", "description": "Total number of matching opportunities" }, "resolutionStatus": { "type": "string", "enum": [ "resolved", "not_found" ], "description": "Whether the company was resolved in the SAM.gov registry. \"resolved\" = found (matchedEntityName populated); \"not_found\" = could not resolve (no opportunity search ran)." }, "matchedEntityName": { "type": [ "string", "null" ], "description": "Canonical SAM.gov legal business name when resolved; null when the company could not be resolved. Distinct from the companyDomain echo." } }, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_gov_relationships", "description": "Map a single company's federal teaming partners from USAspending.gov subaward records. Given a company domain, it resolves the company to its SAM.gov entity (UEI, CAGE code), then aggregates two directions: as a subcontractor, which prime contractors pass work down to it; and as a prime, which subcontractors it passes work down to. Each partner rollup includes contract count, total subaward value, and the largest recent award. Trigger on questions like \"who does team with on federal contracts?\", \"which primes subcontract to ?\", or \"who are 's subcontractors on government work?\". Use this when you want a company's partner/teaming network on federal deals. Do NOT use this to find OPEN solicitations a company should bid on — use company_gov_opportunities (incumbent/likely-bidder opportunities for one company) or search_gov_opportunities (broad SAM.gov RFP/RFQ search by keyword/NAICS/agency). Do NOT use this for a company's commercial ICT/outsourcing (GSI) contracts — use company_contracts instead. Only covers subaward (prime↔sub) relationships, not top-level prime award totals. Requires the SAM.gov (Data.gov) integration to be configured.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to look up (e.g., \"palantir.com\"). Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "relationshipType": { "type": "string", "enum": [ "prime", "sub", "both" ], "default": "both", "description": "Which teaming direction to return: \"prime\" = the company's own subcontractors (company acts as prime); \"sub\" = the primes that subcontract to the company (company acts as sub); \"both\" (default) returns both directions." }, "minAmount": { "type": "number", "description": "Only include subawards worth at least this many USD, e.g. 100000 for $100K+. Applied per subaward before partner rollups are computed. Omit to include all." }, "fiscalYearStart": { "type": "number", "description": "Earliest federal fiscal year to search, as a 4-digit year, e.g. 2020. Defaults to the current year minus 5. Data is aggregated from this year to the present." }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of distinct partner companies returned per direction, ranked by total subaward value descending (1-100, default 50)." } }, "required": [ "companyDomain" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Resolved company name from SAM.gov" }, "companyDomain": { "type": "string", "description": "The company domain that was looked up" }, "samEntity": { "type": "object", "properties": { "uei": { "type": "string" }, "cageCode": { "type": "string" }, "legalBusinessName": { "type": "string" } }, "additionalProperties": true, "description": "SAM.gov entity registration details" }, "asSubcontractor": { "type": "object", "properties": { "totalValue": { "type": "number" }, "totalValueFormatted": { "type": "string" }, "primeContractors": { "type": "array", "items": { "type": "object", "properties": { "partnerName": { "type": "string" }, "contractCount": { "type": "number" }, "totalValue": { "type": "number" }, "totalValueFormatted": { "type": "string" }, "agencies": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "additionalProperties": true, "description": "Relationships where this company acts as a subcontractor" }, "asPrimeContractor": { "type": "object", "properties": { "totalValue": { "type": "number" }, "totalValueFormatted": { "type": "string" }, "subcontractors": { "type": "array", "items": { "type": "object", "properties": { "partnerName": { "type": "string" }, "contractCount": { "type": "number" }, "totalValue": { "type": "number" }, "totalValueFormatted": { "type": "string" }, "agencies": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "additionalProperties": true, "description": "Relationships where this company acts as the prime contractor" } }, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_hierarchy", "description": "Traverse the UCM corporate ownership tree (parents, subsidiaries, sister companies) for ONE company by HG id or domain.\n\ncompany_domain IS LITERAL, never 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 the brand via search_companies FIRST.\n\nUSE WHEN: \"who owns X?\", subsidiaries, parent chain, or sister companies. Do NOT use for: firmographics only → company_firmographic (cheaper); a full tech/intent/spend profile → company_enrich; a list of companies → search_companies.\n\nDEFAULTS: mode=\"children\", depth=1 (direct children only, NOT the full subtree), no optional fields, nulls stripped. MODES: \"children\"=subtree at matched node · \"full\"=whole tree from GHQ (matched=selected:true) · \"parents\"=ancestor chain up to GHQ.\n\nBEWARE: (1) Fortune-500 parents return 100–330+ nodes and can OVERFLOW — depth is the size lever. (2) acquired co + mode:\"full\" returns the WHOLE parent family; check company_level, use mode:\"children\" if not \"Group HQ\". (3) depth applies BEFORE filters — pair country_codes/naics/industry filters with depth:5+. (4) UCM may return DUPLICATE nodes; dedupe by id, not name.\n\nRECIPES: \"who owns X?\"→mode:\"parents\" · all subs→depth:5 · EU entities→country_codes:[\"DE\",\"FR\"],depth:5 · revenue→depth:0,selected_fields:[\"revenue_total\"].\n\nMatched node is always kept even if it fails a filter. hierarchy:null → read no_match_reason. mode:\"parents\"+already_at_ghq:true → the company IS the GHQ. Credit: 0.1/node.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "Company domain, e.g. \"microsoft.com\". Either company_domain or hg_id is required; if both are provided, hg_id takes precedence. Interpreted literally — not a brand alias. Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company ID (31-32 alphanumeric characters). Either company_domain or hg_id is required. When provided, this overrides company_domain. Obtain from a previous search_companies result." }, "mode": { "type": "string", "enum": [ "full", "children", "parents" ], "default": "children", "description": "Default \"children\". \"children\" returns the subtree rooted at the MATCHED node — the matched node is the root, so depth:1 = direct children. \"full\" returns the complete subtree rooted at the GHQ; matched node marked selected:true (usually NOT the root — \"google.com\" → tree rooted at Alphabet Inc.). \"parents\" returns the ancestor chain from matched node up to the GHQ; returns just the node itself if it is already the GHQ. company_level values: \"Group HQ\", \"Corporate Parent\", \"Domestic Parent\", \"Site\", \"Subsidiary\". \"Domestic Parent\" nodes are often regional/legal shells. There is NO server-side company_level filter param — to keep only \"real\" businesses, filter the returned nodes client-side on the always-present company_level field." }, "selected_fields": { "type": "array", "items": { "type": "string", "enum": [ "domain", "domain_normalized", "global_hq_id", "global_hq_name", "corporate_parent_id", "corporate_parent_name", "domestic_parent_id", "domestic_parent_name", "country_name", "city_name", "state_name", "employees_total", "employees_band", "revenue_total", "revenue_band", "industry_name", "naics_code", "naics_name", "sic_codes", "sic_names", "country_code", "company_level", "parent_id" ] }, "maxItems": 20, "description": "Optional fields to include on each node beyond the always-present set (id, name, children, country_code, company_level, parent_id; plus selected:true on the matched node). Default null = no optional fields are returned. Always-present fields (country_code, company_level, parent_id) are accepted here as no-ops. Prefer a short explicit list; use all_fields:true only when you genuinely need every field. Many optional fields are sparse — nulls stripped unless include_nulls:true. Allowed values: domain, domain_normalized, global_hq_id, global_hq_name, corporate_parent_id, corporate_parent_name, domestic_parent_id, domestic_parent_name, country_name, city_name, state_name, employees_total, employees_band, revenue_total, revenue_band, industry_name, naics_code, naics_name, sic_codes, sic_names, country_code, company_level, parent_id." }, "all_fields": { "type": "boolean", "default": false, "description": "When true, every optional field is loaded on each node (equivalent to listing all values in selected_fields). Default false. Significantly increases payload size; prefer selected_fields with a short explicit list. Combine with depth:0 for a single-node firmographic snapshot without traversing children — but if you only need firmographics (no tree), company_firmographic is faster and cheaper." }, "country_codes": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "ISO alpha-2 country codes to INCLUDE (e.g. [\"DE\",\"GB\"]). Ancestor nodes outside the filter are kept as BRIDGE NODES when they have a passing descendant — use the country_code node field to distinguish bridges from matches. Supplying this populates total_count_in_scope in the response (count of matching nodes, excludes bridges). Filter order: depth → country incl → country excl → naics incl → naics excl → industry incl → industry excl (depth is applied FIRST, then the filters run on the depth-capped tree). Within a param, values are OR; across params, AND." }, "exclude_country_codes": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "ISO alpha-2 country codes to EXCLUDE from the tree (e.g. [\"US\"]). Applied after country_codes include. A node is removed only when it has no passing descendants." }, "naics_codes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{2,6}$" }, "maxItems": 50, "description": "NAICS code prefixes to INCLUDE (e.g. [\"51\"] for Information, [\"54\",\"541810\"] for Professional Services). Prefix-matched: \"54\" matches any 6-digit code starting with 54. Bridge-node ancestors outside the filter are retained as connectors. The naics_code node field is auto-fetched — no need to add it to selected_fields. Nodes whose naics_code is null are EXCLUDED while this filter is active (the field is sparse). Pair with depth:5+ so matches deeper in the tree aren't missed." }, "exclude_naics_codes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{2,6}$" }, "maxItems": 50, "description": "NAICS code prefixes to EXCLUDE. Applied after naics_codes include. A node is removed only when it has no passing descendants." }, "industry_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Case-insensitive substrings to match against each node's industry_name field (e.g. [\"software\",\"technology\"]). A node is kept when its industry_name contains ANY of the provided values. The industry_name node field is auto-fetched when supplied. Nodes whose industry_name is null are EXCLUDED while this filter is active (the field is sparse). Pair with depth:5+ so matches deeper in the tree aren't missed." }, "exclude_industry_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Case-insensitive substrings to EXCLUDE on industry_name. Applied after industry_names include." }, "depth": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Cap on levels of children, counted from the ROOT of the returned tree. In mode:\"children\" (default) root = matched node: depth:0 = node only, depth:1 = direct children (DEFAULT), depth:2 = two levels. In mode:\"full\" root = GHQ: depth:0 = GHQ only. When omitted, the API returns direct children only — equivalent to depth:1 in mode:\"children\". Omitting depth does NOT return the full subtree; to walk deeper, pass an explicit depth (e.g. depth:5). WARNING: depth:1 is NOT a size guarantee — a Fortune-500 GHQ can have 60-150+ direct subsidiaries (e.g. Cisco returned 113 nodes, Salesforce 62 at depth:1). Deep trees can be very large (100–330+ nodes on Fortune-500 parents) and may overflow the response — depth is the size lever. Rough budget: ~200–400 bytes/node at default fields, ~3× with all_fields:true. IMPORTANT: depth is applied BEFORE the filters (upstream order: depth → country → naics → industry), so a shallow depth removes deeper nodes before any filter runs — filtering at the default depth:1 only ever sees the top level and misses matches lower in the tree. Always pair filter calls with an explicit depth:5+." }, "include_nulls": { "type": "boolean", "default": false, "description": "If true, fields with null values are kept on each node (including parent_id:null on the root and selected:false on non-matching nodes). Default false strips nulls and selected:false — significantly reduces payload size on large trees. Use include_nulls:true only when you need to distinguish \"field absent\" from \"field present but null\"." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "hierarchy": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Root node of the corporate hierarchy tree (recursive; node fields are verbatim upstream snake_case). Null when no match or tree fully pruned by filters — check no_match_reason for the cause." }, "node_count": { "type": "number", "description": "Total nodes in the returned tree." }, "total_count_in_scope": { "type": [ "number", "null" ], "description": "Nodes directly matching the country_codes filter (excludes bridge-node connectors). Null when no country filter is active." }, "no_match_reason": { "type": "string", "description": "Human-readable explanation when hierarchy is null. Either \"no UCM record for this identifier — try search_companies to verify\" or \"all nodes pruned by active filters — widen filters or increase depth\"." }, "already_at_ghq": { "type": "boolean", "description": "True (only present in mode:\"parents\") when the matched company is already the Group HQ — it has no parent chain above it." } }, "required": [ "hierarchy", "node_count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_install_time_series", "description": "Track how a company's technology adoption changes over TIME: returns a monthly installation-intensity time series per product for one company. Use this for TREND questions — adoption growth, decline, or churn — e.g. 'How has Cisco's usage of Snowflake changed over the past 2 years?' or 'Is company X ramping up or winding down its AWS footprint?' Identify the company by EITHER company_domain OR hg_id — provide exactly one (supplying both or neither is a validation error). Do NOT use this for a point-in-time answer: for the company's CURRENT installed tech stack use company_technographic (snapshot); 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). The most-recent point is typically null (current month incomplete); treat a partial penultimate point as provisional. For trend analysis use intensity_momentum (positive = growing, negative = declining; magnitude is meaningful), not raw intensity; current_intensity is a separate aggregate and NOT on the 1-31 daily scale. Filtering is ID-based only — numeric product_ids/vendor_ids or string category_ids (no name-based filtering); resolve IDs first (see each param). Filter IDs that match nothing return products: [] with HTTP 200 and 0 credits — indistinguishable from genuine no-data, so this tool sets the warning field whenever 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.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "The company domain to look up (e.g., 'cisco.com'). Provide EITHER company_domain OR hg_id — exactly one is required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized. match_confidence in the response is 0.90 when identified by domain." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "The hex HG company id (31-32 alphanumeric chars) as returned by search_companies. Provide EITHER hg_id OR company_domain — exactly one is required. match_confidence in the response is 1.0 when identified by hg_id." }, "product_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 50, "description": "Filter by numeric HG product IDs (integers, e.g. [26434, 22]). Resolve IDs with product_search_and_enrich first — the upstream filters by integer ID only, so names or slug-style IDs return nothing." }, "vendor_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 50, "description": "Filter by numeric HG vendor IDs (integers, e.g. [376]). Resolve IDs with get_vendor_information first — the upstream filters by integer ID only." }, "category_ids": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50, "description": "Filter by HG category IDs (strings, e.g. ['cat-crm']). Resolve IDs with list_product_categories first — the upstream filters by category ID only, not name." }, "country_codes": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO 3166-1 alpha-2 country codes (e.g. ['US', 'GB']). Use with granularity='country' to get per-country intensity breakdowns; each returned product then carries a country_code." }, "granularity": { "type": "string", "enum": [ "global", "country" ], "description": "'global' aggregates intensity across all countries (default upstream behavior). 'country' returns one row per product per country with country_code populated on each product." }, "time_range": { "type": "string", "enum": [ "last_6_months", "last_12_months", "last_24_months", "last_36_months" ], "default": "last_24_months", "description": "Time range for the series. Options: last_6_months, last_12_months, last_24_months, last_36_months. Default: last_24_months. Note: each option returns N+1 data points because the current incomplete month is appended as a null tail (e.g. last_6_months → 7 points, last_12_months → 13 points)." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of products to return (1-50, default 10)." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "company_id": { "type": "string", "description": "Resolved company ID" }, "company_name": { "type": "string", "description": "Company display name" }, "match_confidence": { "type": "number", "description": "Confidence of company match (0.0-1.0). 1.0 for hg_id, 0.90 for domain." } }, "required": [ "company_id", "company_name", "match_confidence" ], "additionalProperties": true, "description": "Matched company details including ID, name, and match confidence" }, "time_range": { "type": "object", "properties": { "start_date": { "type": "string", "description": "Start date (YYYY-MM format)" }, "end_date": { "type": "string", "description": "End date (YYYY-MM format)" }, "granularity": { "type": "string", "enum": [ "month" ] } }, "required": [ "start_date", "end_date", "granularity" ], "additionalProperties": true, "description": "Time range covered by the returned data points" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "product_name": { "type": "string" }, "vendor_name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "description": "Whether the product was verified within the last 90 days" }, "current_intensity": { "type": [ "number", "null" ], "description": "Aggregate intensity from global install data — not on the 1-31 daily scale" }, "intensity_momentum": { "type": [ "number", "null" ], "description": "Momentum float — positive means growing, negative means declining; magnitude is meaningful (larger absolute values = stronger trend direction)" }, "country_code": { "type": [ "string", "null" ], "description": "ISO alpha-2 country code. Populated when granularity='country'; null for global rows." }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM format" }, "intensity": { "type": [ "number", "null" ], "description": "Days the product was detected that month (1-31), null if no detection" } }, "required": [ "date", "intensity" ], "additionalProperties": true } } }, "required": [ "product_id", "product_name", "is_active", "current_intensity", "intensity_momentum", "data_points" ], "additionalProperties": true }, "description": "Products with their time series data" }, "credits_consumed": { "type": "number", "description": "Credits consumed (3 per product returned)" }, "warning": { "type": "string", "description": "Present when filters were provided but no products matched — explains the miss and how to resolve it" } }, "required": [ "company", "time_range", "products", "credits_consumed" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_intent", "description": "Get buying-intent signals for ONE SPECIFIC, ALREADY-KNOWN company, identified by company_domain or hg_id. Returns merged HG proprietary + TrustRadius buyer intent in three optional field groups: summary (active/high-signal topic counts, per-source counts, top context types), topics (per-topic detail — score, signal level, buyer-journey stage, context types/dispositions for competitive intel, vendors, products), and activities (TrustRadius buyer activities with evidence URLs). Each present group carries its own total count alongside a page of data.\n\nUse 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).\n\nDo NOT use this to find WHICH companies show intent on a topic — this tool needs a single known company. Use search_companies with its intent filter block for topic-to-company discovery.\nDo NOT guess topic_ids — resolve a topic name to its hex ID with list_intent_topics first, then pass it here.\n\nScores are bounded 0–100 (100 = strongest signal); signal_level buckets those into HIGH/MEDIUM/LOW.\nDEFAULT: omitting fields returns the summary overview only (up to 50 rows) — topics and activities require an explicit opt-in because large enterprises can have 500k+ topic rows. Pass fields:[\"topics\"] (optionally with \"activities\") plus a small limit when you need detail.\nTopics are geo-expanded by default (one row per state); pass granularity:\"global\" to collapse to one row per topic.\nFilters: signal_level (HIGH/MEDIUM/LOW), buyers_journey_names (Researching/Evaluating), context_type_names (e.g. \"Displacement\"), topic_ids, product_category_ids, vendor_ids/product_ids, a signal_date window, and limit/offset per section.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company domain to look up intent signals for (e.g., \"cisco.com\", \"salesforce.com\"). Either company_domain 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": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company ID (32-character hex). When provided, this overrides company_domain (hg_id wins outright — no fallback to the domain). Obtain from a previous search_companies / company_enrich result; do not fabricate it." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "summary", "topics", "activities" ] }, "maxItems": 3, "description": "Which field groups to include: any subset of \"summary\", \"topics\", \"activities\". DEFAULT when omitted: \"summary\" only (an overview) — pass [\"topics\"] and/or [\"activities\"] explicitly to include those groups. Unrequested groups are omitted from the response (never null)." }, "signal_date": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive lower bound for signal date (YYYY-MM-DD)." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive upper bound for signal date (YYYY-MM-DD)." } }, "additionalProperties": false, "description": "Inclusive signal-date range filter { from, to } (YYYY-MM-DD). Omit for the upstream default window." }, "signal_level": { "type": "array", "items": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ] }, "maxItems": 3, "description": "Filter topics by signal level (HG topics only). Any subset of HIGH, MEDIUM, LOW." }, "buyers_journey_names": { "type": "array", "items": { "type": "string", "enum": [ "Researching", "Evaluating" ] }, "maxItems": 2, "description": "Filter topics by buyer-journey stage (HG topics only). Allowed values: \"Researching\", \"Evaluating\" (the only stages the upstream accepts)." }, "context_type_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20, "description": "Filter topics by context type for competitive intelligence (HG topics only), e.g. [\"Displacement\", \"Whitespace\", \"Expansion\", \"Complementary\"]. Pair with vendor_ids for displacement analysis against a specific competitor." }, "topic_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9A-Fa-f]{1,32}$" }, "maxItems": 50, "description": "Filter to specific hex-encoded topic IDs (32-char Int128; hex chars 0-9/a-f only). Obtain from list_intent_topics — do not fabricate IDs. Malformed IDs are rejected client-side before the upstream call." }, "granularity": { "type": "string", "enum": [ "global", "region", "country", "state" ], "description": "Geographic granularity for topic results. DEFAULT when omitted is \"state\" (geo-expanded: one topic row per state) — pass \"global\" to collapse to one row per topic. \"country\"/\"region\" break results down to those levels, populating country_name/region_name/state_name on each returned topic." }, "product_category_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Filter TrustRadius activities (the \"activities\" field group) to specific product category IDs (hex-encoded). Obtain them from get_product_category." }, "vendor_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 50, "description": "Filter results to specific vendor IDs (integers). Applies across both topics and activities; pair with context_type_names:[\"Displacement\"] to scope competitive/displacement signals to a named competitor." }, "product_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 50, "description": "Filter results to specific product IDs (integers). Applies across both topics and activities." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Max records per section (1-200). Defaults to the upstream page size (50)." }, "offset": { "type": "integer", "minimum": 0, "description": "Records to skip per section for pagination (default 0)." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string", "description": "HG Insights company ID (hex-encoded)" }, "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] } }, "additionalProperties": true, "description": "Company identification details" }, "data_available": { "type": "boolean", "description": "False when HG Insights has no intent data for this company. Absent on populated results. When false, this is a definitive no-data answer — not a service failure — and topics/activities are empty." }, "no_data_reason": { "type": "string", "description": "Human-readable explanation naming the identifier that returned no intent data. Present only when data_available is false." }, "summary": { "type": "object", "properties": { "active_topics_count": { "type": "number" }, "high_signal_topics_count": { "type": "number" }, "latest_signal_date": { "type": [ "string", "null" ] }, "sources": { "type": "object", "additionalProperties": {}, "description": "Signal counts by source (hg, trustradius)" }, "top_context_types": { "type": "object", "additionalProperties": {}, "description": "Context type counts" } }, "additionalProperties": true, "description": "Aggregated intent signal summary" }, "topics": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "number", "description": "Total matching topic rows (may exceed returned rows). With non-global granularity, count reflects geo-expanded rows (one per topic × region/state), not unique topics; pass granularity:'global' for a per-topic count." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Intent score (0-100)" }, "signal_level": { "type": [ "string", "null" ] }, "buyers_journey_name": { "type": [ "string", "null" ] }, "context_type_names": { "type": "array", "items": { "type": "string" } }, "context_dispositions": { "type": "array", "items": { "type": "string" } }, "vendor_names": { "type": "array", "items": { "type": "string" } }, "product_names": { "type": "array", "items": { "type": "string" } }, "trend": { "type": [ "number", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "country_name": { "type": [ "string", "null" ], "description": "Populated when granularity is country/region/state; null for global rows." }, "region_name": { "type": [ "string", "null" ], "description": "Populated when granularity is region/state; null otherwise." }, "state_name": { "type": [ "string", "null" ], "description": "Populated when granularity is state; null otherwise." } }, "required": [ "name", "score", "source" ], "additionalProperties": true } } }, "required": [ "count", "data" ], "additionalProperties": true }, { "type": "null" } ], "description": "Per-topic intent details (HG topics; source is always \"hg\"). Absent when not requested." }, "activities": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "number", "description": "Total matching activities (may exceed returned rows)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "activity_date": { "type": "string" }, "activity_label": { "type": [ "string", "null" ] }, "activity_type": { "type": "string" }, "daily_views": { "type": [ "number", "null" ] }, "intent_signal_url": { "type": [ "string", "null" ] }, "products": { "type": "array", "items": { "type": "string" } }, "vendors": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "required": [ "count", "data" ], "additionalProperties": true }, { "type": "null" } ], "description": "TrustRadius buyer activities. Absent when not requested." } }, "required": [ "company" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_operating_signals", "description": "Retrieve a single company's operating 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 number — note the two intensity scales differ: mentions intensity is an UNBOUNDED sum of detection volume (routinely in the thousands, comparable within a company only), while genai_maturity intensity is a BOUNDED 0-100 score. Call this when a user asks about one 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 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 a company's installed technology stack/products — use company_technographic instead; for raw buying-intent topic scores, use company_intent. Provide a company_domain (e.g., \"cisco.com\") or an HG Insights company ID (hg_id). Missing coverage is signaled per-section via data_available:false + no_data_reason, and per-attribute via stage:\"no-signal\" — these are normal, not errors.", "inputSchema": { "type": "object", "properties": { "company_domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company website domain to profile (e.g., \"cisco.com\"). Either company_domain or hg_id is required; hg_id wins if both are supplied. Protocol prefixes (http://, https://), a leading \"www.\", and any trailing path/query/fragment are stripped automatically and case is normalized, so a full URL like \"https://www.cisco.com/products\" also works." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company identifier (31-32 alphanumeric characters), as returned in the organization_id field of this and other HG tools. Use for an exact, domain-independent lookup once the company is already resolved. Overrides company_domain when both are supplied." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company_name": { "type": [ "string", "null" ], "description": "Resolved company name from HG Insights firmographics; null if the company was not matched or has no firmographic name." }, "company_domain": { "type": [ "string", "null" ], "description": "The resolved company domain. Populated regardless of whether the lookup used company_domain 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": { "type": "string", "description": "HG company identifier" }, "mentions": { "type": "object", "properties": { "data_available": { "type": "boolean", "description": "Whether mentions-derived attributes were found" }, "no_data_reason": { "type": [ "string", "null" ], "description": "Reason when mentions data is unavailable" }, "work_model": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "cloud_posture": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "esg_commitment": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "iot_posture": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "network_modernization": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "automation_stage": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "description": "Derived categorical stage label" }, "intensity": { "type": "number", "description": "UNBOUNDED sum of all contributing signal intensities (rolled-up detection volume, routinely in the thousands) — NOT the 0-100 scale used by the genai_maturity attributes, and not a percentage or currency amount. Comparable within a company, not across companies." }, "last_verified_at": { "type": [ "string", "null" ], "description": "Most recent verification date" }, "signals": { "type": "object", "properties": {}, "additionalProperties": { "type": "number" }, "description": "Breakdown of individual mention intensities by product or keyword" } }, "required": [ "stage", "intensity", "last_verified_at", "signals" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "data_available", "no_data_reason", "work_model", "cloud_posture", "esg_commitment", "iot_posture", "network_modernization", "automation_stage" ], "additionalProperties": true, "description": "Mentions-derived operating signal attributes" }, "genai_maturity": { "type": "object", "properties": { "data_available": { "type": "boolean", "description": "Whether GenAI maturity data was found" }, "no_data_reason": { "type": [ "string", "null" ], "description": "Reason when GenAI maturity data is unavailable" }, "ai_trajectory": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "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" ], "description": "AI trajectory stage classification" }, "intensity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Intensity score (0-100)" }, "signals": { "type": "object", "properties": { "ai_maturity_score": { "type": "number" }, "ai_maturity_6m_delta": { "type": "number" } }, "additionalProperties": true, "description": "Raw input signals used for derivation" } }, "required": [ "stage", "intensity", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "cloud_depth": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "cloud-native", "cloud-heavy", "cloud-moderate", "cloud-light", "no-cloud" ], "description": "Cloud depth stage classification" }, "intensity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Intensity score (0-100)" }, "signals": { "type": "object", "properties": { "gcp_intensity": { "type": "number" }, "aws_intensity": { "type": "number" }, "azure_intensity": { "type": "number" } }, "additionalProperties": true, "description": "Raw input signals used for derivation" } }, "required": [ "stage", "intensity", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "genai_readiness": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "genai-ready", "genai-interested", "genai-exploring", "genai-aware", "genai-curious", "genai-inactive" ], "description": "GenAI readiness stage classification" }, "intensity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Intensity score (0-100)" }, "signals": { "type": "object", "properties": { "genai_intent_score": { "type": "number" }, "ai_product_use": { "type": "boolean" }, "data_maturity_score": { "type": "number" } }, "additionalProperties": true, "description": "Raw input signals used for derivation" } }, "required": [ "stage", "intensity", "signals" ], "additionalProperties": true }, { "type": "null" } ] }, "intent_adoption_gap": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "ai-champion", "active-explorer", "intent-no-action", "moderate-adopter", "warming-up", "quiet-user", "disengaged" ], "description": "Intent-adoption gap stage classification" }, "intensity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Intensity score (0-100)" }, "signals": { "type": "object", "properties": { "genai_intent_score": { "type": "number" }, "ai_product_use": { "type": "boolean" }, "ai_maturity_score": { "type": "number" } }, "additionalProperties": true, "description": "Raw input signals used for derivation" } }, "required": [ "stage", "intensity", "signals" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "data_available", "no_data_reason", "ai_trajectory", "cloud_depth", "genai_readiness", "intent_adoption_gap" ], "additionalProperties": true, "description": "Derived GenAI maturity attributes" } }, "required": [ "company_name", "company_domain", "organization_id", "mentions", "genai_maturity" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_spend", "description": "Estimate a company's IT spend in USD, broken down by spend category and country, from HG Insights modeled spend data (v2). Values are HG modeled dollar estimates (not billed/actual invoices) — e.g. Cisco returns per-category rows like \"Total IT\" (~$6.2B US), \"Total External IT\", \"Services\", and \"Software\", each split by country. Use when a user asks how much a company spends on IT overall or within a specific category (Security, Software, Cloud, Services, Hardware), or the geographic distribution of that spend. Accepts a batch: pass hg_ids OR domains (up to 25 companies — the HG spend batch cap); the two selectors are mutually exclusive, and when both are supplied hg_ids wins. One entry per matched company under companies[]; unmatched companies are omitted. Each company returns spend.all (a thin snake_case passthrough of HG v2 rows: spend, category_name, category_id, country_name, country_code) plus spend.all_count. Filter by category_ids or category_names. WARNING: category_names does case-insensitive substring matching (max 10 names); a name that is not a substring of any catalog category returns 0 rows — prefer category_ids or resolve exact names via get_product_category. Paginate with max_results and offset. Credits: 3 per requested company (charged regardless of match or row count). 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 on-prem software/products a company runs — use company_technographic.", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 25, "description": "HG Insights company IDs for batch spend lookup (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids OR domains (at least one is required); the two are mutually exclusive — if both are supplied, hg_ids takes precedence." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "minItems": 1, "maxItems": 25, "description": "Company domains for batch spend lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized. Provide hg_ids OR domains; the two are mutually exclusive — if both are supplied, hg_ids takes precedence." }, "category_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter USD spend rows to these HG category IDs (string array of hex ids, e.g. from get_product_category). Exact-match and the reliable filter — prefer over category_names. Forwarded as `filters.spend.categories.ids` to the upstream." }, "category_names": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Filter USD spend rows by category name (string array, max 10 — the upstream cap), e.g. [\"Security\",\"Software\"]. Case-insensitive substring match: a name that is not a substring of any catalog category returns 0 rows — prefer category_ids or resolve exact names via get_product_category. Forwarded as `filters.spend.categories.names` to the upstream." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of spend rows (category × country combinations) to return per company (1–25 — the HG spend pagination cap). Forwarded as `pagination.spend.limit` to the upstream." }, "offset": { "type": "integer", "minimum": 0, "description": "Zero-based row offset for pagination. Forwarded as `pagination.spend.offset` to the upstream." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company id (hex). Empty string when not found." }, "company_domain": { "type": "string", "description": "The resolved company domain." }, "spend": { "type": "object", "properties": { "all": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Array of spend rows (snake_case v2 passthrough)." }, "all_count": { "type": "number", "description": "Total number of spend rows in this response." } }, "required": [ "all", "all_count" ], "additionalProperties": true, "description": "Spend section from the HG v2 API — thin upstream passthrough. Rows are snake_case (e.g. category_name, country_name, spend)." }, "credits_consumed": { "type": "number", "description": "Credits consumed for this company: a fixed 3 charged per requested company, regardless of whether the company matched or returned any spend rows." } }, "required": [ "company_id", "company_domain", "spend", "credits_consumed" ], "additionalProperties": true } } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_technographic", "description": "Call this when a user asks what technology a company uses, what its tech stack is, or whether 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 by vendor or product without resolving IDs, pass vendor_names/product_names — case-insensitive substring matches (OR within the list), so an exact canonical name is not required; prefer vendor_ids/product_ids only when you already have resolved IDs. Global/unattributed installs (country_code: null) are included by default; use granularity or country_codes to change scope. total_installs_count and has_more are returned — if has_more is true (even at the default max_results:50) the installs are a partial view of the stack; narrow with specific category_ids, vendor_ids, or product_ids (or page via offset) rather than assuming it is complete. Fortune 500 companies can have 1,000+ installs — filter, keep max_results ≤50, and use include_description:false or install_fields to stay compact. company_id signal: on UNFILTERED calls company_id:\"\" means not in catalog; with a filter it may instead mean zero matching installs. Non-empty company_id + empty installs = found, no match. Use this only when you already know the company (by domains/hg_ids); to find WHICH companies use a given product/vendor/category, use search_companies (its installs filter) — this tool never discovers 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).", "inputSchema": { "type": "object", "properties": { "hg_ids": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$" }, "maxItems": 25, "description": "HG Insights company IDs for batch technographic lookup (up to 25). Each is 31-32 alphanumeric/hex chars, from a previous search_companies result. Provide hg_ids or domains (at least one is required); both may be combined." }, "domains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 25, "description": "Company domains for batch technographic lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically; case is normalized. Provide hg_ids or domains; both may be combined." }, "category_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9A-Fa-f]{32}$" }, "description": "Filter by exact HG Insights category IDs (OR-within-the-list). Get category_id values (32-char hex) from get_product_category, then pass them here. Preferred over product/vendor IDs when filtering by technology category." }, "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by exact HG Insights numeric product IDs (OR-within-the-list). Get IDs from get_vendor_information, or from a previous result's product_id field." }, "product_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Filter by product name substrings (case-insensitive, OR-within-the-list). Combine with product_ids for exact+fuzzy matching. Prefer product_ids when you have resolved IDs." }, "vendor_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by exact HG Insights numeric vendor IDs (OR-within-the-list). Call get_vendor_information first to resolve a vendor name to its integer vendor_id, then pass that ID here. You can also reuse vendor_id values from a previous company_technographic result." }, "vendor_names": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Filter by vendor name substrings (case-insensitive, OR-within-the-list). Combine with vendor_ids for exact+fuzzy matching. Prefer vendor_ids when you have resolved IDs." }, "country_codes": { "type": "array", "items": { "type": "string" }, "description": "ISO alpha-2 country codes to include installs from (e.g. [\"US\",\"GB\"]). When set, only installs from these countries are returned, and results are automatically returned country-scoped (one row per product per country with country_code populated) unless you override granularity explicitly. When multiple codes are passed, the same product may appear as multiple rows — one per country with its own intensity score. Deduplicate on product_id if you need a unique product list." }, "granularity": { "type": "string", "enum": [ "global", "country" ], "description": "Shape of the returned installs. 'global' returns deduplicated rows per product (country_code: null); 'country' returns one row per product per country with country_code populated. Leave unset to include global / unattributed installs by default — this is what surfaces vendors that only appear as global installs, which typically score higher intensity than country-scoped installs. Pass granularity:\"country\" when you want country-specific rows and ranking. NOTE: passing country_codes already defaults granularity to 'country'; set this explicitly only to override that (e.g. granularity:\"global\" to still get deduplicated product rows while filtering by country)." }, "product_attribute_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by HG Insights numeric product attribute IDs (OR-within-the-list). Get attribute IDs from get_product_attribute. Useful for filtering installs by cross-cutting attributes (e.g. open-source, cloud-native)." }, "last_verified_date": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Include installs last verified on or after this date (YYYY-MM-DD, inclusive)." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Include installs last verified on or before this date (YYYY-MM-DD, inclusive)." } }, "additionalProperties": false, "description": "Filter installs by their last-verified date, as a range object { from, to } (both optional, YYYY-MM-DD, inclusive). Use \"to\" to exclude stale installs (e.g. { \"to\": \"2022-01-01\" } finds installs not seen recently); use \"from\" for recently-verified installs; supply both to bound a window." }, "max_results": { "type": "number", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of installs to return (1-100, default 50). For companies with large tech footprints (typically Fortune 500), unfiltered requests with max_results >50 may fail with HTTP 422 — respond by adding category_ids, product_ids, or vendor_ids filters, or reducing max_results to ≤50. Prefer filters over large max_results." }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Pagination offset (default 0, max 10 000). Use with max_results to page through installs." }, "sort": { "type": "string", "enum": [ "intensity", "last_seen" ], "description": "Sort order for returned installs. 'intensity' = highest usage signal first (default upstream behavior). 'last_seen' = most recently verified first." }, "install_fields": { "type": "array", "items": { "type": "string", "enum": [ "country_code", "intensity", "location_count", "product_category_id", "product_category_level1_name", "product_category_level2_name", "product_category_level3_name", "product_category_level4_name", "product_category_level5_name", "product_description", "product_first_verified_date", "product_id", "product_last_verified_date", "product_name", "vendor_domain", "vendor_id", "vendor_name" ] }, "description": "Limit which fields are returned per install. Omit to return all fields. Useful when you only need a subset (e.g. [\"product_name\",\"vendor_name\",\"intensity\"]) to keep the response compact. Unknown field names are rejected." }, "include_description": { "type": "boolean", "default": false, "description": "When false (default), strips product_description from every install (~60% smaller payload). Set to true only when product descriptions are explicitly needed. Overrides install_fields even if product_description is listed there." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "HG Insights company identifier (hex)." }, "company_domain": { "type": "string", "description": "The company domain that was queried." }, "installs": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "number", "description": "Numeric product identifier (use with company_fai product_ids)." }, "product_name": { "type": "string", "description": "Name of the technology product." }, "product_description": { "type": "string", "description": "Description of the product." }, "vendor_id": { "type": "number", "description": "Numeric vendor identifier." }, "vendor_name": { "type": "string", "description": "Name of the technology vendor." }, "vendor_domain": { "type": "string", "description": "Vendor domain." }, "product_category_id": { "type": "string", "description": "HG technology-taxonomy code (e.g. SW012)." }, "product_category_level1_name": { "type": "string", "description": "Top-level product category." }, "product_category_level2_name": { "type": "string", "description": "Level-2 product category." }, "product_category_level3_name": { "type": "string", "description": "Level-3 product category." }, "product_category_level4_name": { "type": [ "string", "null" ], "description": "Level-4 product category (may be null)." }, "product_category_level5_name": { "type": [ "string", "null" ], "description": "Level-5 product category (may be null)." }, "country_code": { "type": [ "string", "null" ], "description": "Install country (null for global / unattributed installs)." }, "product_last_verified_date": { "type": "string", "description": "Date the install was last verified (YYYY-MM-DD)." }, "product_first_verified_date": { "type": "string", "description": "Date the install was first verified (YYYY-MM-DD)." }, "intensity": { "type": "number", "description": "Install intensity score." }, "location_count": { "type": "number", "description": "Number of locations with the install." } }, "additionalProperties": true }, "description": "List of technology installs (tech stack), passed through from the HG v2 API." }, "installs_count": { "type": "number", "description": "Number of installs in this response (≤ max_results)." }, "total_installs_count": { "type": "number", "description": "Total matching installs available upstream. Compare with installs_count to know if more pages exist." }, "has_more": { "type": "boolean", "description": "True when the upstream has more matching installs than were returned in this page. Add filters (category_ids, product_ids, vendor_ids) to narrow the result set." } }, "required": [ "company_id", "company_domain", "installs", "installs_count" ], "additionalProperties": true } } }, "required": [ "companies" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "contact_enrich", "description": "Use only after contact_search (2 credits per call) has identified the person — do not use for open-ended discovery. 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 availability is org-specific (commonly Apollo only). Leave provider on 'auto' (default); naming an unconfigured provider returns a hard error, so check the response's availableProviders. 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. BULK omits unmatched contacts from the returned array entirely (no placeholder) — read metadata.matchCount and compare results by id/name, never by array position. USES CREDITS, billed per requested reveal, per MATCHED contact: 0.2 per email + 2 per phone. revealPhone defaults to TRUE, so unless you pass revealPhone:false every matched contact is billed 2.2 (10x an email reveal) — set revealPhone:false when you only need email/firmographic data. No-match calls cost 0; response metadata.dynamicCreditCost reports the actual charge. Do NOT re-enrich a contact already in context — credits are charged per call regardless of whether data changed.", "inputSchema": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Provider contact ID returned by contact_search — a 24-character hex string (e.g. '54a797027468696b7f8f9d42'). Most accurate identifier: resolves an exact person with no matching ambiguity. Reuse the id from search rather than constructing one, and pass the same `provider` that produced it." }, "firstName": { "type": "string", "description": "Contact's first (given) name. Combine with lastName and a company domain/name so the provider can resolve the right person." }, "lastName": { "type": "string", "description": "Contact's last (family) name. Combine with firstName and a company domain/name so the provider can resolve the right person." }, "email": { "type": "string", "format": "email", "description": "Contact's work or personal email, if known. A strong standalone matcher — sufficient on its own to reverse-lookup the rest of the profile." }, "companyDomain": { "type": "string", "description": "Current employer's website domain (e.g. 'stripe.com'). Pair with firstName+lastName to disambiguate common names; preferred over companyName. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "companyName": { "type": "string", "description": "Current employer's name (e.g. 'Stripe'). Use only when the domain is unknown — companyDomain resolves more reliably." }, "linkedinUrl": { "type": "string", "format": "uri", "description": "Contact's LinkedIn profile URL. A strong standalone matcher — sufficient on its own to identify the person." }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider contact ID (from contact_search) for this row. Most accurate matcher for a bulk item." }, "firstName": { "type": "string", "description": "Contact's first (given) name; pair with lastName and a company domain/name." }, "lastName": { "type": "string", "description": "Contact's last (family) name; pair with firstName and a company domain/name." }, "email": { "type": "string", "format": "email", "description": "Contact's email, if known — a strong standalone matcher for this row." }, "companyDomain": { "type": "string", "description": "This contact's current employer domain (e.g. 'salesforce.com'); preferred over companyName. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "companyName": { "type": "string", "description": "This contact's current employer name; use only when the domain is unknown." }, "linkedinUrl": { "type": "string", "format": "uri", "description": "Contact's LinkedIn profile URL — a strong standalone matcher for this row." } }, "additionalProperties": false }, "maxItems": 25, "description": "Array of known contacts to enrich in one call (max 25), each identified the same ways as a single enrichment (id, email, linkedinUrl, or name + company). Cheaper and faster than one call per person; mutually exclusive with the single-contact fields above. Unmatched rows are omitted from the returned array — compare results by id/name, never by array position." }, "revealEmail": { "type": "boolean", "default": true, "description": "Whether to reveal email addresses (default: true)" }, "revealPhone": { "type": "boolean", "default": true, "description": "Whether to attempt a phone reveal. Defaults to TRUE, so a default enrich call is billed the 2-credit phone fee on every matched contact (10x an email reveal), charged for the attempt whether or not a phone value is returned. Pass false when you only need email/firmographic data." }, "provider": { "type": "string", "default": "auto", "description": "Contact data provider. Prefer \"auto\" (default), which selects an available provider. \"apollo\" or \"zoominfo\" target a specific provider, but requesting one your org has not configured returns a hard error rather than falling back — check availableProviders in the response." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Contact ID" }, "firstName": { "type": [ "string", "null" ], "description": "First name" }, "lastName": { "type": [ "string", "null" ], "description": "Last name" }, "name": { "type": [ "string", "null" ], "description": "Full name" }, "title": { "type": [ "string", "null" ], "description": "Job title" }, "seniority": { "type": [ "string", "null" ], "description": "Seniority level" }, "email": { "type": [ "string", "null" ], "description": "Email address (if revealed)" }, "emailStatus": { "type": [ "string", "null" ], "description": "Email verification status" }, "personalEmails": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Personal email addresses" }, "phone": { "type": [ "string", "null" ], "description": "Primary phone number" }, "mobilePhone": { "type": [ "string", "null" ], "description": "Mobile phone number" }, "corporatePhone": { "type": [ "string", "null" ], "description": "Corporate phone number" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL" }, "twitterUrl": { "type": [ "string", "null" ], "description": "Twitter/X profile URL" }, "facebookUrl": { "type": [ "string", "null" ], "description": "Facebook profile URL" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Company name" }, "domain": { "type": [ "string", "null" ], "description": "Company domain" }, "industry": { "type": [ "string", "null" ], "description": "Industry" }, "employeeCount": { "type": [ "number", "null" ], "description": "Employee count" }, "revenue": { "type": [ "number", "null" ], "description": "Annual revenue" }, "location": { "type": [ "string", "null" ], "description": "Company location" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "Company LinkedIn URL" }, "website": { "type": [ "string", "null" ], "description": "Company website" } }, "required": [ "id", "name" ], "additionalProperties": true, "description": "Organization information" }, "employmentHistory": { "type": "array", "items": { "type": "object", "properties": { "organizationName": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "isCurrent": { "type": "boolean" } }, "required": [ "isCurrent" ], "additionalProperties": true }, "description": "Employment history" }, "city": { "type": [ "string", "null" ], "description": "City" }, "state": { "type": [ "string", "null" ], "description": "State/Region" }, "country": { "type": [ "string", "null" ], "description": "Country" } }, "required": [ "id", "organization" ], "additionalProperties": true, "description": "Enriched contact data (single enrichment)" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Contact ID" }, "firstName": { "type": [ "string", "null" ], "description": "First name" }, "lastName": { "type": [ "string", "null" ], "description": "Last name" }, "name": { "type": [ "string", "null" ], "description": "Full name" }, "title": { "type": [ "string", "null" ], "description": "Job title" }, "seniority": { "type": [ "string", "null" ], "description": "Seniority level" }, "email": { "type": [ "string", "null" ], "description": "Email address (if revealed)" }, "emailStatus": { "type": [ "string", "null" ], "description": "Email verification status" }, "personalEmails": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Personal email addresses" }, "phone": { "type": [ "string", "null" ], "description": "Primary phone number" }, "mobilePhone": { "type": [ "string", "null" ], "description": "Mobile phone number" }, "corporatePhone": { "type": [ "string", "null" ], "description": "Corporate phone number" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL" }, "twitterUrl": { "type": [ "string", "null" ], "description": "Twitter/X profile URL" }, "facebookUrl": { "type": [ "string", "null" ], "description": "Facebook profile URL" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Company name" }, "domain": { "type": [ "string", "null" ], "description": "Company domain" }, "industry": { "type": [ "string", "null" ], "description": "Industry" }, "employeeCount": { "type": [ "number", "null" ], "description": "Employee count" }, "revenue": { "type": [ "number", "null" ], "description": "Annual revenue" }, "location": { "type": [ "string", "null" ], "description": "Company location" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "Company LinkedIn URL" }, "website": { "type": [ "string", "null" ], "description": "Company website" } }, "required": [ "id", "name" ], "additionalProperties": true, "description": "Organization information" }, "employmentHistory": { "type": "array", "items": { "type": "object", "properties": { "organizationName": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "isCurrent": { "type": "boolean" } }, "required": [ "isCurrent" ], "additionalProperties": true }, "description": "Employment history" }, "city": { "type": [ "string", "null" ], "description": "City" }, "state": { "type": [ "string", "null" ], "description": "State/Region" }, "country": { "type": [ "string", "null" ], "description": "Country" } }, "required": [ "id", "organization" ], "additionalProperties": true }, "description": "Enriched contacts (bulk enrichment)" }, "metadata": { "type": "object", "properties": { "creditsUsed": { "type": "number", "description": "Credits consumed (equals dynamicCreditCost)" }, "dynamicCreditCost": { "type": "number", "description": "Credits actually charged (matches × 3; 0 on no-match)" }, "matchConfidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Match confidence level" }, "enrichedAt": { "type": "string", "description": "ISO timestamp of enrichment" }, "noMatchReason": { "type": "string", "description": "Reason when no matching contact was found" }, "enrichmentType": { "type": "string", "enum": [ "single", "bulk" ], "description": "Type of enrichment performed" }, "provider": { "type": "string", "description": "Contact data provider used (e.g., apollo, zoominfo)" }, "usedProvider": { "type": "string", "description": "Which provider fulfilled this request" }, "availableProviders": { "type": "array", "items": { "type": "string" }, "description": "Providers configured for the organization" } }, "required": [ "creditsUsed", "enrichedAt" ], "additionalProperties": true, "description": "Enrichment metadata" } }, "required": [ "metadata" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "contact_search", "description": "Discover PEOPLE (contacts) at a company by job title, seniority, and location — returns a list of individuals (name, title, seniority, LinkedIn, org), not company facts. Use this when you need to find contacts at an account (e.g. 'who are the VPs of Marketing at Salesforce') to 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) not 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). Availability is org-specific (commonly Apollo only); with none configured the tool is unavailable. Leave provider on 'auto' (default). Costs 2 credits per call regardless of result count, so batch all filters into one call. The ONLY filters are: personTitles, personSeniorities, personLocations, organizationLocations, organizationNumEmployeesRanges, contactEmailStatus. There is NO free-text/keyword search — express intent via personTitles and personSeniorities. Params like q, keywords, titles, or seniority are not real and are silently ignored; confirm a filter worked by comparing totalResults with and without it. LARGE COMPANIES: for big accounts (tens of thousands of contacts) an unfiltered search returns an unranked default page — always pass personTitles and/or personSeniorities. RULES: combine ALL title variations into ONE call via arrays (never one call per title); on 0 results, STOP and report 'no matches found' instead of retrying variations; max 2 searches per request (initial + optional pagination). Then use contact_enrich for email/phone of the best matches.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "description": "Company domain to search (e.g., \"salesforce.com\"). Preferred over companyName for accuracy. Either companyDomain or companyName is required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "companyName": { "type": "string", "description": "Company name for fuzzy match (e.g., \"Salesforce\") when the domain is unknown. Prefer companyDomain for accuracy. Provide one of companyDomain or companyName (domain wins if both are given)." }, "personTitles": { "type": "array", "items": { "type": "string" }, "description": "Job titles to match, as an array — combine ALL variations in one call (e.g., [\"VP Marketing\", \"CMO\", \"Head of Marketing\"]). This is the primary way to express search intent; there is no free-text/keyword param." }, "personSeniorities": { "type": "array", "items": { "type": "string", "enum": [ "owner", "founder", "c_suite", "partner", "vp", "head", "director", "manager", "senior", "entry", "intern" ] }, "description": "Seniority levels to match (array). One or more of: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Combine with personTitles to narrow large accounts." }, "personLocations": { "type": "array", "items": { "type": "string" }, "description": "Filter contacts by the PERSON's location, \"City/State, Country\" style (e.g., [\"California, US\", \"New York, US\"])." }, "organizationLocations": { "type": "array", "items": { "type": "string" }, "description": "Filter by the company's HQ location (e.g., [\"San Francisco, US\"]) — distinct from personLocations, which filters the individual." }, "organizationNumEmployeesRanges": { "type": "array", "items": { "type": "string" }, "description": "Company employee-count ranges as \"min,max\" strings (e.g., [\"1,10\", \"11,50\", \"51,200\"])." }, "contactEmailStatus": { "type": "array", "items": { "type": "string", "enum": [ "verified", "unverified", "likely_to_engage", "unavailable" ] }, "description": "Filter by email deliverability status (array): verified, unverified, likely_to_engage, unavailable. Not all providers support this; when the tool can detect it, ignored/unsupported params are listed in metadata.warnings, which is omitted when there is nothing to report." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number for pagination (default: 1)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Results per page (default: 25, max: 100)" }, "provider": { "type": "string", "default": "auto", "description": "Contact data provider. Prefer \"auto\" (default), which selects an available provider. \"apollo\" or \"zoominfo\" target a specific provider, but requesting one your org has not configured returns a hard error rather than falling back — check availableProviders in the response." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Contact ID (use for enrichment with the same provider)" }, "firstName": { "type": [ "string", "null" ], "description": "First name" }, "lastName": { "type": [ "string", "null" ], "description": "Last name" }, "name": { "type": [ "string", "null" ], "description": "Full name" }, "title": { "type": [ "string", "null" ], "description": "Job title" }, "seniority": { "type": [ "string", "null" ], "description": "Seniority level" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Company name" }, "domain": { "type": [ "string", "null" ], "description": "Company domain" }, "industry": { "type": [ "string", "null" ], "description": "Industry" }, "employeeCount": { "type": [ "number", "null" ], "description": "Employee count" }, "location": { "type": [ "string", "null" ], "description": "Company location" } }, "required": [ "id", "name" ], "additionalProperties": true, "description": "Organization information" }, "city": { "type": [ "string", "null" ], "description": "City" }, "state": { "type": [ "string", "null" ], "description": "State/Region" }, "country": { "type": [ "string", "null" ], "description": "Country" } }, "required": [ "id", "organization" ], "additionalProperties": true }, "description": "List of contacts found" }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number" }, "perPage": { "type": "number", "description": "Results per page" }, "totalResults": { "type": "number", "description": "Total number of matching contacts" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" } }, "required": [ "page", "perPage", "totalResults", "hasMore" ], "additionalProperties": true, "description": "Pagination information" }, "metadata": { "type": "object", "properties": { "searchCriteria": { "type": "object", "additionalProperties": {}, "description": "The search criteria used" }, "tip": { "type": "string", "description": "Usage tip" }, "provider": { "type": "string", "description": "Contact data provider used (e.g., apollo, zoominfo)" }, "usedProvider": { "type": "string", "description": "Which provider fulfilled this request" }, "availableProviders": { "type": "array", "items": { "type": "string" }, "description": "Providers configured for the organization" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings about ignored parameters" } }, "required": [ "searchCriteria", "tip" ], "additionalProperties": true, "description": "Search metadata" } }, "required": [ "contacts", "pagination", "metadata" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "customer_data_discover", "description": "Auto-discover the structure of YOUR organization's own connected Snowflake data (not HG Insights data). Scans the connected Snowflake account, scores tables for how account-like they are, and proposes field mappings (e.g. account name, domain, ID) with confidence levels — a fast way to learn what customer datasets and tables are available without knowing the schema up front.\n\nRuns asynchronously: start a run with action \"run_discovery\", poll with \"get_status\", then read the proposed tables and mappings with \"get_results\".\n\nUse this when you need to map out an unfamiliar connected Snowflake account: which tables exist, which look like account/company data, and how their columns map to standard fields (discover available customer datasets/tables).\n\nDo NOT use this when you already know the specific schema or table you want — use customer_data_explore to inspect a known dataset (list schemas/tables, describe columns, sample rows). Do NOT use this to read actual records or run analytics — use customer_data_query to run a SQL query. Do NOT use this for HG Insights' own company/technographic/spend data — those live behind the company_* and hg_* tools.", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "run_discovery", "get_status", "get_results" ], "default": "run_discovery", "description": "Which step to run against your connected Snowflake data (default: run_discovery). run_discovery: start an async scan that analyzes tables and proposes field mappings, returning a discoveryId. get_status: poll a prior run's progress (pending/running/completed/failed). get_results: fetch the full result — candidate tables and proposed mappings — once the run has completed." }, "discovery_id": { "type": "string", "default": "", "description": "The discoveryId returned by a run_discovery call. Required for get_status and get_results; ignored for run_discovery." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "action": { "type": "string", "description": "Action that was executed." }, "discoveryId": { "type": "string", "description": "ID of the discovery result." }, "status": { "type": "string", "description": "Status of the discovery (pending, running, completed, failed)." }, "summary": { "type": "string", "description": "Human-readable summary of the discovery results." }, "executionTimeMs": { "type": [ "number", "null" ], "description": "Execution time in milliseconds." }, "result": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Full discovery result data (for get_results action)." }, "error": { "type": [ "string", "null" ], "description": "Error message if discovery failed." } }, "required": [ "action" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "openWorldHint": true, "destructiveHint": false, "idempotentHint": false } }, { "name": "customer_data_explore", "description": "Inspect the structure of YOUR ORGANIZATION'S OWN Snowflake data (the customer's connected warehouse), not HG Insights' datasets.\nDrill into one dataset: list the schema(s) you can access, list the tables in a schema, describe a table's columns (names, types, nullability, comments), or return a small sample of rows so you can see real values before writing SQL.\n\nUse this when you already know which dataset you want and need its structure: to see what columns a table has, confirm column names/types before querying, or peek at a few sample rows.\nThis is the middle step of the customer-data flow: discover (find datasets) → explore (inspect a dataset) → query (run SQL).\n\nDo NOT use this to list/find which datasets exist or get proposed field mappings — use customer_data_discover.\nDo NOT use this to run arbitrary SQL, aggregate, filter, or join — use customer_data_query.\nDo NOT use this for HG Insights firmographic/technographic/spend/intent data — those live in the company_* and hg_* tools, not the customer's own warehouse.\n\nScope: read-only. Access is confined to the schema configured on the Snowflake connection; a mismatched schema parameter is rejected.", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "list_schemas", "list_tables", "describe_table", "sample_data" ], "default": "list_schemas", "description": "What to inspect. list_schemas: the schema(s) you can access. list_tables: the tables in a schema. describe_table: a table's columns (name, type, nullability, comment) — requires `table`. sample_data: a few real rows from a table — requires `table`. Defaults to list_schemas." }, "schema": { "type": "string", "default": "", "description": "Schema to inspect. Optional: defaults to the schema configured on the Snowflake connection. If provided it must equal the configured schema (any other value is rejected) — access is confined to that one schema." }, "table": { "type": "string", "default": "", "description": "Table (or view) name within the schema. Required for action=describe_table and action=sample_data; ignored for list_schemas and list_tables. Must be a valid Snowflake identifier." }, "sample_size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5, "description": "How many sample rows to return. Only used by action=sample_data. Integer 1–100, default 5. Keep small — this is meant for previewing values, not bulk export." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "action": { "type": "string", "description": "Action that was executed." }, "count": { "type": "number", "description": "Number of records returned for the action." }, "schemas": { "type": "array", "items": { "type": "string" }, "description": "Schema names returned by list_schemas." }, "tables": { "type": "array", "items": { "type": "object", "properties": { "tableName": { "type": "string", "description": "Table name." }, "rowCountEstimate": { "type": [ "number", "null" ], "description": "Estimated row count when available." }, "comment": { "type": [ "string", "null" ], "description": "Table comment." } }, "required": [ "tableName", "rowCountEstimate", "comment" ], "additionalProperties": true }, "description": "Table metadata returned by list_tables." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "columnName": { "type": "string", "description": "Column name." }, "dataType": { "type": "string", "description": "Snowflake data type." }, "isNullable": { "type": "boolean", "description": "Whether column is nullable." }, "comment": { "type": [ "string", "null" ], "description": "Column comment." } }, "required": [ "columnName", "dataType", "isNullable", "comment" ], "additionalProperties": true }, "description": "Column metadata returned by describe_table." }, "rows": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Sample rows returned by sample_data." }, "executionTimeMs": { "type": "number", "description": "Execution time for the action in milliseconds." } }, "required": [ "action", "count", "executionTimeMs" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "customer_data_query", "description": "Run a read-only SQL SELECT against the ORG'S OWN connected Snowflake data warehouse (the customer's data — e.g. their CRM accounts, opportunities, product usage — NOT HG Insights' market data). Use this when you already know the exact table and column names and need to read, filter, aggregate, or join the org's own rows to answer a question. This is the final step of the customer-data flow: discover → explore → query. The statement must start with SELECT or WITH. It is validated as read-only (no INSERT/UPDATE/DELETE/DDL) and is scoped to the single schema configured on the Snowflake connection — fully-qualified references outside that schema are rejected. TABLE() and IDENTIFIER() functions are not supported; use direct table references. A row limit and a 30s timeout are enforced. Do NOT use this when you don't yet know the schema, tables, or columns — run customer_data_discover to auto-map the schema, then customer_data_explore to list tables/columns and sample rows, before writing SQL here. Do NOT use this to query HG Insights' market/technographic/firmographic warehouse — use hg_data_query for that.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "default": "SELECT 1", "description": "Read-only SQL to run against the org's own Snowflake schema. Must start with SELECT or WITH; INSERT/UPDATE/DELETE/DDL are rejected. All table references must resolve to the single configured schema (use bare or configured-schema-qualified table names from customer_data_explore). TABLE() and IDENTIFIER() are unsupported — reference tables directly." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100, "description": "Hard cap on rows returned, enforced on top of any LIMIT in the SQL (default: 100, max: 10000). Lower it for wide tables to keep the response small." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Rows returned by the query." }, "rowCount": { "type": "number", "description": "Number of rows returned." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Column names returned by the query." }, "executionTimeMs": { "type": "number", "description": "Query execution time in milliseconds." } }, "required": [ "rows", "rowCount", "columns", "executionTimeMs" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "get_product_attribute", "description": "Resolve HG Insights product-attribute IDs from a search theme. Attributes are the cross-cutting capability tags of the product taxonomy (e.g. 'Cloud Computing', 'Security', 'Software as a Service (SaaS)', 'Open Source') — the semantic layer above individual products. This is a taxonomy lookup, NOT a per-product attribute reader: there is no `product_id` input; it returns global taxonomy rows, not the attributes attached to one product, and never returns which companies carry an attribute. Free — no credits consumed. Search by `attributeName` for a case-insensitive substring match (relevance-ranked), or pass known `attributeIds` to fetch specific rows in one call. Provide at least one. Returns rows with `attribute_id`, `attribute_name`, `attribute_description` (a paragraph of context, populated for most attributes though occasionally empty), `attribute_parent_id` (0 = root theme, otherwise the id of the parent attribute), `attribute_level` (1 = root theme, 2 = more specific sub-attribute), and `product_count` (how many products carry the attribute — a rough breadth signal), plus a top-level `count` (total matches before pagination). The taxonomy is hierarchical: a search like 'Cloud' returns both the root 'Cloud Computing' (level 1) and its children (e.g. 'Cloud Workloads', level 2). Use this when you have a broad capability/theme and need the attribute_id(s) to feed as a filter into product or install tools (e.g. product_search_and_enrich, company_technographic). Browse by searching a broad `attributeName` — do NOT enumerate IDs sequentially. Do NOT use this to resolve a named product category — use `get_product_category` for taxonomy categories. Do NOT use this to resolve or look up a vendor/company — use `get_vendor_information`.", "inputSchema": { "type": "object", "properties": { "attributeName": { "type": "string", "minLength": 1, "description": "Free-text capability theme to search attribute names by. Case-insensitive substring match on `attribute_name` (LIKE) that activates relevance ranking. Pass a short capability keyword, not a full product or company name, e.g. 'SaaS', 'Open Source', 'Cloud', 'Security'. A broad term also matches sub-attributes (e.g. 'Cloud' → 'Cloud Computing' and its children like 'Cloud Workloads')." }, "attributeIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "description": "Fetch specific attributes by their known `attribute_id`s (from a prior search), returning all matching rows in one call. Use this to re-hydrate ids into names/descriptions; do not guess or enumerate ids sequentially to browse the catalog — search by `attributeName` instead." }, "sortBy": { "type": "string", "enum": [ "relevance", "attribute_name", "product_count" ], "default": "relevance", "description": "Sort order: 'relevance' (best name match first — only meaningful with `attributeName`; the default), 'attribute_name' (alphabetical A→Z), or 'product_count' (most-used attributes first, useful for finding the broadest themes). On an id-only call the default 'relevance' falls back to the API's own ordering." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of attribute rows to return (1–50, default 10). A broad theme can match dozens of attributes; raise this to survey a theme's full sub-hierarchy." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-based pagination offset (default 0). Combine with `limit` to page through matches when `count` exceeds the rows already returned." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute_id": { "type": "number", "description": "Use this ID in downstream tool calls." }, "attribute_name": { "type": "string" }, "attribute_description": { "type": [ "string", "null" ] }, "attribute_parent_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "0 = root-level attribute with no parent." }, "attribute_level": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "product_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "attribute_id", "attribute_name" ], "additionalProperties": true }, "description": "Matching attribute rows, ordered by sortBy." }, "count": { "type": "number", "description": "Total matching attributes before pagination." } }, "required": [ "attributes", "count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "get_product_category", "description": "Resolve a term to the exact HG Insights taxonomy category name/id needed by company_technographic before an install query. Free — no credits consumed.\n\nMatching: 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. Per-parameter behaviour is documented on each parameter.\n\nReturns category rows (category_id, category_code, category_name, category_name_tree, has_category_installs, product_count) plus a top-level count of total matches across all pages. product_count covers direct products only, not the subtree, so parent nodes look small. Prefer deeper leaf categories (longer category_name_tree) for precise filtering.\n\nUse this when:\n- You need the exact category name/id to pass to company_technographic (set hasInstalls: true to limit to categories with real install data).\n- You want to explore the category taxonomy by keyword.\n\nDo NOT use this when:\n- You want vendor details or a vendor_id — use get_vendor_information.\n- You want product attribute data — use get_product_attribute.\n- You want warehouse table schemas for SQL query planning — use hg_catalog (not product taxonomy).\n\nRequires 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.", "inputSchema": { "type": "object", "properties": { "categoryName": { "type": "string", "minLength": 1, "description": "Case-insensitive LIKE substring match on `category_name` (NOT fuzzy/semantic — misspellings return 0 rows). Activates relevance ranking. Use common partial terms, e.g. 'CRM', 'Security', 'Cloud'. Note: the taxonomy root is 'Security' — 'Cyber Security'/'Cybersecurity' return 0 rows." }, "treeContains": { "type": "string", "minLength": 1, "description": "Case-insensitive LIKE substring scanned across every node in `category_name_tree` (root → leaf). Use to scope to a whole branch, e.g. 'Sales and Marketing' returns all categories under that parent." }, "categoryCode": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Exact match on `category_code`, e.g. 'SW049'. Note: many intermediate and some top-level categories have a null `category_code` — if a prior call returned a null code, use `categoryId` instead." }, "categoryId": { "type": "string", "pattern": "^[0-9A-F]{32}$", "description": "Exact match on `category_id` (uppercase 32-char Int128 hex)." }, "hasInstalls": { "type": "boolean", "description": "true = only categories with at least one install signal; false = catalog-only categories. Omit to return all." }, "sortBy": { "type": "string", "enum": [ "relevance", "category_name", "product_count" ], "default": "relevance", "description": "Sort order: 'relevance' (best match first; only sent when `categoryName` or `treeContains` is present — auto-dropped for exact `categoryCode`/`categoryId` lookups so they don't 422), 'category_name' (A→Z), 'product_count' (desc)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of category rows to return (1–50)." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "category_id": { "type": "string", "description": "Uppercase 32-char Int128 hex. Use in downstream tool calls." }, "category_code": { "type": [ "string", "null" ], "description": "Stable short code, e.g. 'SW049'. Null for some top-level categories." }, "category_name": { "type": "string" }, "category_parent_id": { "type": [ "string", "null" ], "description": "Null at the taxonomy root." }, "category_id_tree": { "type": "array", "items": { "type": "string" } }, "category_name_tree": { "type": "array", "items": { "type": "string" } }, "has_category_installs": { "type": "boolean" }, "product_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "category_id", "category_name", "category_id_tree", "category_name_tree", "has_category_installs" ], "additionalProperties": true }, "description": "Matching category rows, ordered by sortBy." }, "count": { "type": "number", "description": "Total matching categories across all pages (not the page size). Compare to limit+offset to detect further pages." } }, "required": [ "categories", "count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "get_vendor_information", "description": "Resolve 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`), for product attributes (use `get_product_attribute`), or for a product's reviews/pricing/details (use `get_product_information`). Do NOT call it with no filter — always supply `vendor_name`, `description`, or `vendor_id`.", "inputSchema": { "type": "object", "properties": { "vendor_name": { "type": "string", "minLength": 1, "description": "Case-insensitive substring match on `vendor_name` (LIKE), which activates relevance ranking. Pass the plain company name, e.g. 'Salesforce', 'Oracle'. Because it is substring (not fuzzy), a single name can return multiple rows — a parent plus its subsidiaries (e.g. 'Oracle' → 'Oracle Corporation' and 'Oracle NetSuite') — so inspect `vendor_name`/`vendor_url` and pick the intended row before reusing its `vendor_id`." }, "description": { "type": "string", "minLength": 1, "description": "Case-insensitive substring match on `vendor_company_description` (the vendor's company blurb) — useful to find vendors by what they do, e.g. 'endpoint security'. ANDed with `vendor_name` when both are provided: the stored description must contain the exact substring AND the name must match. If results are empty when using both filters, retry with only `vendor_name`; the stored description text may not contain your exact phrase." }, "vendor_id": { "type": "integer", "minimum": 0, "description": "Exact `vendor_id` (UInt64) match — returns ≤ 1 row. Use when you already hold the ID (e.g. from an earlier search) and want to resolve the vendor's full metadata; do not use `vendor_id` to re-search by name." }, "has_products_with_installs": { "type": "boolean", "description": "true = only vendors with ≥1 product carrying an install signal; false = catalog-only vendors. Omit to return all. Note: product ownership joins may occasionally surface unrelated vendors — verify `vendor_name` and `vendor_url` before using the returned `vendor_id`." }, "include_products": { "type": "boolean", "default": false, "description": "When true, each vendor row carries a `products[]` of `{product_id, product_name}` ordered by presence frequency, capped at `products_limit`." }, "products_limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Cap on the `products[]` list per vendor when `include_products` is true (1–100)." }, "sort_by": { "type": "string", "enum": [ "relevance", "vendor_name", "product_count" ], "default": "relevance", "description": "Sort order for the returned rows: 'relevance' (best name match first — only meaningful alongside `vendor_name`), 'vendor_name' (A→Z), or 'product_count' (most products first). On this channel an unrecognised value is rejected with an upstream 422 (it is no longer silently discarded)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of vendor rows to return (1–100)." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "vendors": { "type": "array", "items": { "type": "object", "properties": { "vendor_id": { "type": "number", "description": "Use this ID in downstream tool calls." }, "vendor_name": { "type": "string" }, "vendor_url": { "type": [ "string", "null" ] }, "vendor_parent_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Null if this vendor has no parent." }, "vendor_company_id": { "type": [ "string", "null" ], "description": "Paired HG company id, when known." }, "vendor_company_description": { "type": [ "string", "null" ] }, "product_count": { "type": "number" }, "products": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "number" }, "product_name": { "type": "string" } }, "required": [ "product_id", "product_name" ], "additionalProperties": true } }, { "type": "null" } ], "description": "Null when `include_products` is false/omitted." } }, "required": [ "vendor_id", "vendor_name", "product_count" ], "additionalProperties": true }, "description": "Matching vendor rows, ordered by sort_by." }, "total": { "type": "number", "description": "Total matching vendors before pagination." }, "has_more": { "type": "boolean" }, "credits_consumed": { "type": "number" } }, "required": [ "vendors", "total", "has_more", "credits_consumed" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "hg_catalog", "description": "Browse the HG Insights data warehouse SCHEMA (table/column names and types, join keys, indexing hints, sql_qualifier) to plan an hg_data_query — returns schema metadata, NOT data rows. This is the required first step before writing SQL. The schema is stable — call once per session and cache it.\n\nTWO MODES:\n (1) ORIENTATION (default, table_names OMITTED): a lightweight index of ALL tables, each as {name, sql_qualifier, description} only — no columns, join keys, sample queries, or relationships. The cheap first call; use it to discover which tables exist, then drill in.\n (2) DETAIL (table_names SET): full metadata for the named tables (columns, order_by, primary_key, join_keys, common_filters, mandatory_predicate, sample_queries) plus the relationship edges touching them. The columns and include_sample_queries params apply in DETAIL mode only.\n\nUse this when:\n - Discovering which tables and columns exist before writing SQL for hg_data_query.\n - Confirming a column's exact name, type, or join key, or a table's sql_qualifier, before referencing it.\n - Mapping table relationships to plan a multi-table join.\n\nDo NOT use this when:\n - You want to RUN a query and get rows back — call hg_data_query (this tool returns schema only).\n - You need product/technology taxonomy VALUES (category, vendor, attribute, or product names/IDs) — call get_product_category, get_vendor_information, or get_product_attribute; those describe HG's product catalog, not warehouse table schemas.", "inputSchema": { "type": "object", "properties": { "table_names": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]{0,63}$" }, "maxItems": 20, "description": "Exact table names from a prior orientation call (lowercase, underscores; e.g. [\"install_global\", \"company_locations\"]). Returns FULL detail for them (columns, join keys, sample queries) plus the relationship edges that touch any of them — an edge is included when EITHER endpoint is in the requested set, not only when both are. Omit for a lightweight ORIENTATION index of all tables ({name, sql_qualifier, description} only, empty relationships[]). An unknown name errors (422) and names the bad entries — call with no table_names first to see valid names." }, "columns": { "type": "string", "enum": [ "none", "important", "full" ], "default": "important", "description": "Column verbosity. Applies only when table_names is set — an unscoped call always returns the compact orientation index (name/sql_qualifier/description only). none=strips column definitions AND projection/index blocks (projection_details, skip_indexes, indexed_filters); order_by/primary_key/mandatory_predicate kept. important=curated most-important columns with full indexing metadata (default). full=every column live from ClickHouse system.columns (many have no description)." }, "include_sample_queries": { "type": "boolean", "default": true, "description": "Include curated worked SQL examples per table. Applies only when table_names is set. Set false to reduce token usage." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "sql_qualifier": { "description": "Database prefix required in FROM, or null for default-database tables. Build the full reference as: sql_qualifier ? `${sql_qualifier}.${name}` : name. Example: products → sql_qualifier=\"hg_statics\" → FROM hg_statics.products." }, "description": { "type": "string" }, "row_count_approx": { "type": "string", "description": "Approximate row count, e.g. \"426M\"." }, "engine": { "type": "string", "description": "ClickHouse storage engine." }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "ORDER BY sort key columns (primary sort key for ClickHouse MergeTree)." }, "primary_key": { "type": "array", "items": { "type": "string" } }, "projections": { "type": "array", "items": { "type": "string" }, "description": "Alternate sort-order projection names that can accelerate specific query patterns." }, "mandatory_predicate": { "description": "If set, every query touching this table must include a WHERE predicate on this column to avoid a full-table scan." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "ClickHouse column type." }, "description": { "type": "string" }, "important": { "type": "boolean" } }, "required": [ "name", "type" ], "additionalProperties": true }, "description": "Column definitions (empty when columns=none)." }, "join_keys": { "type": "array", "items": { "type": "string" }, "description": "Columns typically used to join this table to other tables." }, "common_filters": { "type": "array", "items": { "type": "string" }, "description": "Columns most commonly used in WHERE predicates." }, "sample_queries": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "sql": { "type": "string" } }, "required": [ "description", "sql" ], "additionalProperties": true }, "description": "Curated worked SQL examples (empty when include_sample_queries=false)." } }, "required": [ "name" ], "additionalProperties": true }, "description": "Available tables in the HG Insights data warehouse. In ORIENTATION mode (no table_names) each entry carries only name, sql_qualifier, and description; pass table_names for the full per-table metadata (columns, join_keys, sample_queries, etc.)." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "from_table": { "type": "string" }, "from_column": { "type": "string" }, "to_table": { "type": "string" }, "to_column": { "type": "string" }, "type": { "type": "string", "description": "Cardinality, e.g. \"many_to_one\"." } }, "required": [ "from_table", "from_column", "to_table", "to_column", "type" ], "additionalProperties": true }, "description": "Join graph edges. When table_names is set, scoped to edges where from_table OR to_table is in the requested set (an edge touching any requested table is included). When table_names is omitted (orientation mode), this is EMPTY — pass table_names to get the join graph. Use this to discover how tables relate before writing multi-table queries." } }, "required": [ "tables", "relationships" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "hg_data_query", "description": "Execute read-only SQL SELECT queries against the HG Insights data warehouse. hg_data_query EXECUTES SQL you already have and returns rows; the similarly-named hg_query only GENERATES SQL from a plain-English question and does NOT run it — use hg_query when you need the SQL written for you, then run it here. 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.). Returns rows, column names, row count, and credits consumed. Credit cost is SCAN-BASED not row-based — the cost depends on data scanned, not rows returned. A query returning 0 rows can still consume ~50 credits; add WHERE predicates to narrow scans. \n\nPREFER search_companies for vendor/product/category lookups, company counts, and firmographic filters — no SQL needed. Use hg_data_query only for multi-table joins, time-series, or aggregations search_companies cannot express. \n\nCONSTRAINTS: SELECT * rejected — list explicit columns. Call hg_catalog to discover valid tables. \n\nKEY COLUMNS: company_locations(cl): name, country_name, country_code, employees_min, employees_max, company_id, url_id. install_global(ig): product_id, product_name, vendor_name, category_leaf_name, url_id — NO category_id. Join: USING (url_id). \n\nTAM: call get_vendor_information for product IDs, then filter install_global by product_id. See query param for worked examples.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "A single read-only SQL statement to run against the HG data warehouse. Must start with SELECT or WITH; `SELECT *` and any write/DDL (INSERT/UPDATE/DELETE/DROP) are rejected. Use exact table/column names from hg_catalog. Examples — (1) \"How many mid-market North American companies have installed Splunk?\" → call get_vendor_information(vendorName: \"Splunk\") for product IDs, then: SELECT COUNT(DISTINCT cl.company_id) FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.product_id IN () AND cl.country_name IN ('United States', 'Canada') AND cl.employees_min >= 100 AND cl.employees_max <= 1000. (2) \"Companies running a SIEM that's not Splunk\" (competitive displacement) → same first call for Splunk product IDs, then: SELECT DISTINCT cl.company_id, cl.name FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.category_leaf_name IN (SELECT DISTINCT category_leaf_name FROM install_global WHERE product_id IN ()) AND ig.product_id NOT IN () LIMIT 1000. The category subquery derives Splunk's categories from install_global itself — get_vendor_information returns product_id/product_name only, not category_leaf_name." }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000, "description": "Row cap for the result set (default: 1000, max: 10000). Credit cost is scan-based, not row-based, so prefer COUNT/aggregate queries and tight WHERE predicates over pulling raw rows." } }, "required": [ "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Rows returned by the query." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Column names returned by the query." }, "row_count": { "type": "number", "description": "Number of rows returned." }, "credits_consumed": { "type": "number", "description": "Credits consumed by this query." } }, "required": [ "rows", "columns", "row_count", "credits_consumed" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "list_fai_departments", "description": "Resolver for the Functional Area Intelligence (FAI) taxonomy: lists the 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.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Case-insensitive partial-match filter on the department name, e.g. 'eng' matches 'Engineering'. Use it to resolve a canonical department name (and its roles) before calling company_fai. Matching is delegated to the upstream catalog. Omit to list the full department catalog." }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of departments to return (>= 1). Omit to use the upstream default of 10 rows per page; pass a higher limit (e.g. 100) or paginate with offset to retrieve the full catalog. The response's `count` is the total matching-record count, which may exceed the number of rows in `data` — check `data.length` or paginate until you have seen `count` rows." }, "offset": { "type": "integer", "minimum": 0, "description": "Number of departments to skip before returning results (>= 0), for paging alongside limit. Omit to start from the first record." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "count": { "type": "number", "description": "Total number of matching FAI departments (upstream total, may exceed returned rows)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "FAI department ID (hex-encoded)" }, "name": { "type": "string", "description": "FAI department name" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "FAI role ID (hex-encoded)" }, "name": { "type": "string", "description": "FAI role name" } }, "required": [ "id", "name" ], "additionalProperties": true }, "description": "Roles within the department" } }, "required": [ "id", "name" ], "additionalProperties": true }, "description": "List of FAI departments" } }, "required": [ "count", "data" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "list_intent_topics", "description": "RESOLVER: list 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.\n\nUse 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.\n\nDo 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). \n\nDo 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.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Filter intent topics by name (case-insensitive substring match), e.g. 'security' or 'cloud'. This is a literal substring filter over catalog topic names, not a ranked or semantic search: pass a single short keyword, NOT a natural-language phrase — a multi-word phrase that is not a literal substring of a topic name (e.g. 'cloud security infrastructure management') returns zero results. Catalog names are lowercased (e.g. 'vendor security assessment (vsa)'), so match on the keyword, not on casing. Omit only to browse the full 20,000+ topic catalog (reverse-alphabetical, page with limit/offset)." }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of topics to return (>= 1). Omit for the upstream default page size. Use a small value (e.g. 5-25) when resolving a keyword to a topic ID; raise it only to browse the catalog." }, "offset": { "type": "integer", "minimum": 0, "description": "Number of topics to skip for pagination (>= 0). Omit to start from the first record. Advance by your limit to page through the reverse-alphabetical catalog when name is omitted." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "count": { "type": "number", "description": "Total number of matching intent topics (upstream total, may exceed returned rows)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Intent topic ID (hex-encoded). Pass this value to company_intent's topic_ids parameter or search_companies' intent.topics.ids parameter to find companies showing intent for the topic." }, "name": { "type": "string", "description": "Intent topic name" }, "category": { "type": "string", "description": "Intent topic category" } }, "required": [ "id", "name" ], "additionalProperties": true }, "description": "List of intent topics" } }, "required": [ "count", "data" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "phoenix_get_artifact", "description": "Retrieve ONE Phoenix artifact by its id and, when the deliverable is a small HTML brief, inline its content. 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.", "inputSchema": { "type": "object", "properties": { "artifact_id": { "type": "string", "description": "Synthetic artifact id from phoenix_list_artifacts, e.g. \"{runId}-html\" or \"{runId}-pdf\". Provide this OR run_id (at least one is required)." }, "run_id": { "type": "string", "format": "uuid", "description": "Bare run id (UUID), e.g. a runId from phoenix_invoke_agent — resolves that run's canonical artifact. Provide this OR artifact_id." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "found": { "type": "boolean" }, "runId": { "type": "string" }, "artifactType": { "type": "string" }, "url": { "type": "string", "description": "Absolute webapp URL to open the artifact" }, "content": { "type": "string", "description": "Brief HTML body when small enough to inline" }, "message": { "type": "string", "description": "Explanation when found is false" } }, "required": [ "found" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "phoenix_get_run_status", "description": "Check the status and details of a Phoenix agent run started by phoenix_invoke_agent. 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.", "inputSchema": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid", "description": "The run id to check (UUID). This is the `runId` returned by phoenix_invoke_agent." } }, "required": [ "run_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "runId": { "type": "string", "description": "Unique identifier for the agent run" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "partially_failed", "failed" ], "description": "Current status of the run" }, "agentName": { "type": [ "string", "null" ], "description": "Name of the agent that was executed" }, "inputs": { "type": "object", "additionalProperties": {}, "description": "Input parameters provided to the agent" }, "startedAt": { "type": [ "string", "null" ], "description": "ISO timestamp when the run started; null while queued" }, "finishedAt": { "type": [ "string", "null" ], "description": "ISO timestamp when the run completed; null while queued or running" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Artifact identifier" }, "type": { "type": "string", "description": "Artifact type (html, markdown, pdf, table)" }, "url": { "type": "string", "description": "Absolute URL to view the artifact" }, "byteSize": { "type": "number", "description": "Artifact size in bytes (omitted when unknown)" } }, "additionalProperties": true }, "description": "Generated artifacts from the run (empty when the run has no downloadable artifact)" }, "costSummary": { "type": "object", "properties": { "tool_credits": { "type": "number", "description": "Credits used for tool calls" }, "llm_credits": { "type": "number", "description": "Credits used for LLM inference" }, "total_credits": { "type": "number", "description": "Total credits consumed" } }, "additionalProperties": true, "description": "Credit usage summary for the run" } }, "required": [ "runId", "status", "artifacts", "costSummary" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "phoenix_invoke_agent", "description": "Start a Phoenix AI agent run with the given inputs. This kicks off one of THIS org's published orchestration agents (e.g. an Account Research Brief that assembles a cited deliverable) — it does not itself return company data; it 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.", "inputSchema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid", "description": "The agent instance id to run (UUID). Get it from phoenix_list_agents — this is the `id` field of an agent row, not its name." }, "inputs": { "type": "object", "additionalProperties": {}, "description": "The agent's input object, shaped by that agent's input schema (see the `inputs` field from phoenix_list_agents). Keys vary by agent — e.g. an Account Research Brief takes { domain, hgid?, depth? }." }, "params": { "type": "object", "additionalProperties": {}, "description": "Optional execution/output controls independent of the agent's inputs (e.g. { depth: \"deep\", output_formats: [\"html\",\"pdf\"] }). Omit to use the agent's defaults." } }, "required": [ "agent_id", "inputs" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "runId": { "type": "string", "description": "Unique ID for this agent run" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "partially_failed", "failed" ], "description": "Current status of the run" }, "message": { "type": "string", "description": "Status message" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Artifact identifier" }, "type": { "type": "string", "description": "Artifact type (html, markdown, pdf, table)" }, "url": { "type": "string", "description": "Absolute URL to view the artifact" }, "byteSize": { "type": "number", "description": "Artifact size in bytes (omitted when unknown)" } }, "additionalProperties": true }, "description": "Generated artifacts. Empty/absent for a freshly-queued run — use phoenix_get_run_status to retrieve artifacts once the run succeeds." } }, "required": [ "runId", "status", "message" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } }, { "name": "phoenix_list_agents", "description": "List the Phoenix AI agents this organization has published and can 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.", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent instance ID" }, "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "description": "Agent description" }, "version": { "type": "string", "description": "Current published version ID" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Available tools" }, "inputs": { "type": "object", "additionalProperties": {}, "description": "Expected input schema" } }, "required": [ "id", "name", "tools" ], "additionalProperties": true }, "description": "Published agents available to the authenticated organization" }, "count": { "type": "number", "description": "Total number of agents" } }, "required": [ "agents", "count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } }, { "name": "phoenix_list_artifacts", "description": "Browse this organization's Phoenix artifacts — the canonical deliverable (one brief per succeeded agent run or upload) already produced in this 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.", "inputSchema": { "type": "object", "properties": { "artifact_type": { "type": "string", "enum": [ "html", "markdown", "pdf", "table" ], "description": "Return only artifacts of this type. Omit to return all types." }, "source": { "type": "string", "enum": [ "all", "agent", "uploaded" ], "default": "all", "description": "Filter by origin: \"agent\" (agent-generated), \"uploaded\" (via phoenix_upload_artifact), or \"all\" (default)." }, "run_id": { "type": "string", "format": "uuid", "description": "Scope results to a single run id (UUID) — e.g. a runId from phoenix_invoke_agent. Omit to list across all runs." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Max rows to return (1-200, default 50). Pair with offset to page." }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Rows to skip for pagination (0-10000, default 0). E.g. offset 50 with limit 50 returns the second page." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Synthetic artifact id (`${runId}-${type}`)" }, "runId": { "type": "string" }, "artifactType": { "type": "string" }, "source": { "type": "string", "description": "\"agent\" or \"uploaded\"" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "expiresAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp or null" }, "url": { "type": "string", "description": "Absolute webapp URL to open the artifact" } }, "required": [ "id", "runId", "artifactType", "source", "createdAt", "url" ], "additionalProperties": true } }, "count": { "type": "number", "description": "Number of artifacts returned" } }, "required": [ "artifacts", "count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "phoenix_onboarding", "description": "Onboards a new user or agent to Phoenix: renders a branded, personalized getting-started widget recommending the best GTM workflows to run first, with a text fallback for clients that cannot render MCP-app widgets. Use this when the user is new to Phoenix or asks how to begin (e.g. \"I'm getting started\", \"what can Phoenix do\", \"where do I start\") and needs orientation on Phoenix's tools and capabilities. Do NOT use it when you already know which specific data tool to call (e.g. a company's firmographics, technographics, or intent) — call that tool directly instead. On that intent you MUST ask EXACTLY these two questions and WAIT for the answers before doing anything else. Ask the role question as a NUMBERED choice list (so the user can reply with a number), then the company question on its own line — formatted exactly: \"First, what's your role? Reply with the number: 1. Sales 2. Marketing 3. Customer Success 4. Exec / Strategy 5. Other\" and \"And what company or product do you represent?\". Ask ONLY those two — do NOT ask open-ended questions like \"what are you hoping to do with Phoenix\", and do NOT present role as a free-text question. Do not skip, improvise, or guess the answers. After you have BOTH answers, call this tool with `role`, `company`, and 1–3 `recommended_prompts` slugs. See each parameter for how to pick and when to omit.", "inputSchema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "sales", "marketing", "cs", "exec", "other" ], "description": "The user's role, the answer to onboarding question 1 — ASK THE USER first (sales / marketing / cs / exec / other); do not guess. Drives which workflows are recommended and the \"why we picked these\" reason line." }, "company": { "type": "string", "maxLength": 200, "description": "The company or product the user represents, the answer to onboarding question 2 — ASK THE USER first; do not guess. Personalizes the widget copy and pre-fills the primary-action prompt. Optional: OMIT it to let Phoenix derive the company from the user's corporate signup email instead of stalling." }, "recommended_prompts": { "type": "array", "items": { "type": "string", "enum": [ "account-research-brief", "phoenix-pvp-pqs-briefing", "intent-targeting-activation", "vendor-sprawl-consolidation-map", "pre-call-brief", "competitive-analysis-brief", "tam-sizer-tech-adjacency", "competitive-battlecard", "icp-refiner-closed-won-cohort", "market-analysis-brief" ] }, "maxItems": 3, "description": "The 1–3 curated prompt slugs you recommend for this user, chosen from their role and the tools visible in this session (e.g. \"account-research-brief\", \"pre-call-brief\", \"competitive-battlecard\"). Pass these only AFTER you have both answers. Must be drawn from the curated onboarding set; anything outside the set is rejected. Omit to get a safe default recommendation." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "role": { "type": [ "string", "null" ], "description": "The user's role." }, "company": { "type": [ "string", "null" ], "description": "The company or product the user represents." }, "recommendationReason": { "type": "string", "description": "Why these workflows were recommended for this user." }, "recommendedPrompts": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "blurb": { "type": "string" } }, "required": [ "slug", "title", "blurb" ], "additionalProperties": true }, "description": "The 1–3 curated workflows recommended for this user." }, "curatedPrompts": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "blurb": { "type": "string" } }, "required": [ "slug", "title", "blurb" ], "additionalProperties": true }, "description": "The remaining curated workflows (excludes the recommended ones)." }, "primaryAction": { "type": "object", "properties": { "title": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "title", "prompt" ], "additionalProperties": true, "description": "The single primary next action (CTA)." }, "provider": { "type": "string", "description": "Provider bucket the entry copy is framed for (claude/chatgpt/aws/default)." }, "framingNote": { "type": "string", "description": "Light provider-aware framing note." }, "companyDerivedFromSignup": { "type": "boolean", "description": "Whether the company was derived from signup data rather than the answer." } }, "required": [ "recommendationReason", "recommendedPrompts", "curatedPrompts", "primaryAction", "provider", "framingNote", "companyDerivedFromSignup" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": false, "destructiveHint": false, "idempotentHint": true, "title": "Phoenix Onboarding" } }, { "name": "phoenix_upload_artifact", "description": "Register an externally-produced PDF or HTML file into Phoenix as an artifact by giving a publicly-fetchable https URL to the bytes. Phoenix server-side fetches the URL (SSRF-guarded), stores it in S3, and it then appears in the org's Artifacts tab tagged \"Uploaded\" — indistinguishable from an agent-generated deliverable. Returns the created upload run id and the artifact descriptor. Only PDF (application/pdf) and HTML (text/html) files up to 25 MB are supported, and the 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.", "inputSchema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Original file name including extension, shown in the Artifacts tab (e.g. \"acme-account-brief.pdf\"). 1-512 chars." }, "content_type": { "type": "string", "enum": [ "application/pdf", "text/html" ], "description": "MIME type of the file — only \"application/pdf\" or \"text/html\" are accepted. Must match the actual bytes at source_url." }, "source_url": { "type": "string", "format": "uri", "description": "Publicly-fetchable https URL to the file bytes (must be https and reachable server-side without auth; file must be ≤25 MB). Phoenix fetches this URL, not the caller." } }, "required": [ "file_name", "content_type", "source_url" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "runId": { "type": "string", "description": "The upload run ID" }, "artifactType": { "type": "string", "description": "Resolved artifact type (pdf or html)" }, "message": { "type": "string", "description": "Status message" }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": true }, "description": "The uploaded artifact descriptor." } }, "required": [ "runId", "artifactType", "message" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true } }, { "name": "product_search_and_enrich", "description": "Discover and hydrate products/technologies from the HG Insights product catalog (the technographic taxonomy of vendors, products, and categories). 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 into a concrete product_id or to browse the 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. Use when you need to look up a product in the catalog, resolve a product name to an id, browse a vendor's or category's products, or fetch full catalog metadata for specific product_ids. Typical flow: search to find the id, then enrich the chosen id(s). Unmatched enrich ids are silently omitted from the response and do not consume credits (there is no per-row error). 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, not the CRM software one). Same guidance applies to attributes via get_product_attribute (use attribute_ids over attribute_name) and vendors via get_vendor_information (use vendor_id over vendor_name). Do NOT use for pricing, competitor narrative, or user reviews — use get_product_information / get_product_reviews (TrustRadius). This tool returns HG catalog taxonomy (category/vendor/attributes/install signals) only.", "inputSchema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "search", "enrich" ], "description": "Required discriminator selecting the operation. 'search' = free, returns a paginated list of matching product_ids (use with filters/sort/limit/offset). 'enrich' = 1 credit per successful match, hydrates known product_ids into full catalog records (use with products[])." }, "filters": { "type": "object", "properties": { "product_name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "category_name": { "type": "string", "minLength": 1 }, "attribute_name": { "type": "string", "minLength": 1 }, "vendor_name": { "type": "string", "minLength": 1 }, "category_id": { "type": "string", "pattern": "^[0-9A-F]{32}$" }, "attribute_ids": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "vendor_id": { "type": "integer", "minimum": 0 }, "has_install": { "type": "boolean" } }, "additionalProperties": false, "description": "search-only, all fields optional and AND-combined. Flat HG catalog filters: product_name, description, category_name, attribute_name, vendor_name (substring matches — imprecise), category_id (32-char uppercase hex, resolve via get_product_category), attribute_ids (resolve via get_product_attribute), vendor_id (resolve via get_vendor_information), has_install (true = only products with observed installs). Resolve category_id via get_product_category first and pass it here — category_name does a substring match that can silently pick the wrong category. Prefer id filters over the *_name substring filters. Unknown keys and legacy nested shapes are rejected." }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "product_name", "vendor_name", "category_name", "last_verified_at" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "order" ], "additionalProperties": false }, "maxItems": 3, "description": "search-only. Ordered list of up to 3 sort specs (first is primary). Each: field ∈ {relevance, product_name, vendor_name, category_name, last_verified_at}, order ∈ {asc, desc}. Omit for the server's default relevance ranking." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "search-only. Max results per page, 1-100. Server default: 50." }, "offset": { "type": "integer", "minimum": 0, "description": "search-only. Zero-based pagination offset (>=0) into the result set; page N = offset N*limit. Server default: 0." }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 0 } }, "required": [ "product_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "enrich-only, required for enrich. 1-50 product_ids to hydrate, each as {product_id}. Get ids from a prior action='search' call. Duplicates are deduped by upstream. Unmatched ids are silently omitted from the response and consume no credits (no per-row error is returned)." } }, "required": [ "action" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "number", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "product_description": { "type": [ "string", "null" ] }, "vendor_id": { "type": [ "number", "null" ] }, "vendor_name": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ] }, "category_name": { "type": [ "string", "null" ] }, "product_details": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "category_info": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "vendor_info": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": true }, "description": "search: slim product hit list ({product_id, product_name, ...}). enrich: one hydrated row per matched product_id." }, "count": { "type": "number", "description": "search only. Total matching products before pagination." } }, "required": [ "products" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "search_companies", "description": "Search and discover companies using the HG Insights v2 search API. Each filter group is a separate, optional parameter; groups combine with AND semantics.\n\nUse this when:\n - Building a prospect or ICP list (e.g. \"US corporate parents with 1K+ employees using Oracle\").\n - Filtering by technology installs, intent, or AI/GenAI maturity.\n - Whitespace analysis — exclude known CRM accounts (company_identifiers.company_ids with NONE_PRESENT).\nDo NOT use this when you already know the company domain or hg_id — call company_firmographic instead.\n\nTo find companies by name use company_identifiers.name (case-insensitive token substring match); with an exact domain, company_identifiers.domains is more precise. Resolve product/vendor/category IDs first: invalid IDs are NOT rejected — they match nothing and return total_count 0, indistinguishable from a genuine zero-match.\n\nGUARDRAIL: broad firmographic-only filters (e.g. countries=[\"US\"], or revenue/employee alone) match hundreds of thousands to millions of records. Always pair a firmographic-only filter with a meaningful installs, intent, industry, or geography filter (≥2 filter groups).\n\n⚠ TOKEN BUDGET: rows are lean (four identity columns), but limit is capped at 100 (default 10). Use 10–50 for exploration and paginate with offset for bulk workflows; total_count reports matches across all pages.\n\nNOTE: sorting on a ranking signal (e.g. ai_maturity_score) orders results but never adds a column — the four returnable fields are unchanged, so a sort is a no-op for the payload shape.\n\nResponse: 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.", "inputSchema": { "type": "object", "properties": { "company_identifiers": { "type": "object", "properties": { "company_ids": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "HG company hex IDs (32-char). Use ANY_PRESENT to include; NONE_PRESENT to exclude known accounts (whitespace analysis)." }, "company_ids_including_corporate_relatives": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Like company_ids but also matches the entire corporate family of each provided ID." }, "domains": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Company domains (e.g. \"cisco.com\")" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Filter by normalized company domain. NONE_PRESENT excludes those domains." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Free-text company-name search. Case-insensitive substring match — every space-separated token must appear in the company name (e.g. \"acme corp\" matches \"Acme Corporation\"). Use when you have a name but not a domain or hg_id." } }, "additionalProperties": false, "description": "Filters by known company identifiers (HG IDs, domains, or name)." }, "firmographics": { "type": "object", "properties": { "company_level": { "type": "string", "enum": [ "ALL_ENTITIES", "CORPORATE_PARENT", "DOMESTIC_PARENT", "GLOBAL_HEADQUARTER" ], "description": "Hierarchy level. CORPORATE_PARENT = brand-level; GLOBAL_HEADQUARTER = ultimate parent. Omit for all entities." }, "country_codes": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "ISO-2 country codes, e.g. [\"US\",\"DE\"]" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false }, "description": "HQ country filter. Multiple clauses combine. NONE_PRESENT to exclude countries." }, "region_names": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Literal region code strings, e.g. \"AMER\", \"APAC\", \"EMEA\", \"LATAM\" — NOT hex IDs." }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Geographic region — ids accepts \"AMER\", \"APAC\", \"EMEA\", \"LATAM\", etc. Only ANY_PRESENT supported." }, "state_ids": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "US state hex IDs (32-char) — resolve via search_industries_naics_sic or company_firmographic, NOT literal state names/abbreviations." }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "US state hex IDs. Only ANY_PRESENT supported." }, "employees": { "type": "object", "properties": { "min": { "type": "integer", "description": "Minimum employee count" }, "max": { "type": "integer", "description": "Maximum employee count" }, "has_fixed_employees": { "type": "boolean", "description": "true = only companies with a fixed headcount (exclude ranged records)" } }, "additionalProperties": false, "description": "Employee count filter." }, "revenue": { "type": "object", "properties": { "min": { "type": "number", "description": "Minimum annual revenue in USD" }, "max": { "type": "number", "description": "Maximum annual revenue in USD" }, "has_fixed_revenue": { "type": "boolean", "description": "true = only companies with a fixed revenue value (exclude ranged records)" } }, "additionalProperties": false, "description": "Annual revenue filter in USD (HG proprietary estimate)." }, "industries": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "HG industry integer IDs — resolve via search_industries_naics_sic" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false }, "description": "HG industry filter. Multiple clauses combine." }, "naics_codes": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "HG internal NAICS hex IDs (32-char) — NOT raw code strings" }, "codes": { "type": "array", "items": { "type": "string" }, "description": "Raw NAICS code strings, e.g. [\"5221\"]" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "inclusion_method" ], "additionalProperties": false }, "description": "NAICS filter. Array of clauses; each clause carries EITHER hex ids OR raw codes (exactly one). Multiple clauses combine." }, "sic_codes": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "HG internal SIC hex IDs (32-char) — NOT raw code strings" }, "codes": { "type": "array", "items": { "type": "string" }, "description": "Raw SIC code strings, e.g. [\"5912\"]" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "inclusion_method" ], "additionalProperties": false }, "description": "SIC filter. Array of clauses; each clause carries EITHER hex ids OR raw codes (exactly one). Multiple clauses combine." } }, "additionalProperties": false, "description": "Firmographic-based filters: company hierarchy, geography, size, and industry." }, "installs": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "HG product IDs — resolve via get_vendor_information or product_search_and_enrich. Invalid IDs are not rejected: they match nothing and return total_count 0." }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ], "description": "ANY_PRESENT = has at least one; ALL_PRESENT = has all; NONE_PRESENT = has none" }, "fai": { "type": "object", "properties": { "departments": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee departments (hex IDs)." }, "roles": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee roles (hex IDs)." } }, "additionalProperties": false, "description": "Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required." }, "install_age": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Install age in years" }, "install_age_months": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Install age in months" }, "intensity": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Install intensity score" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false }, "description": "Filter by installed products. Array allows combining multiple inclusion methods (e.g. must have A, must not have B)." }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "HG vendor IDs — resolve via get_vendor_information. Invalid IDs are not rejected: they match nothing and return total_count 0." }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] }, "fai": { "type": "object", "properties": { "departments": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee departments (hex IDs)." }, "roles": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee roles (hex IDs)." } }, "additionalProperties": false, "description": "Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required." }, "product_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Number of products from this vendor installed" }, "install_age": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false }, "install_age_months": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false }, "description": "Filter by vendor installs. Array allows combining multiple inclusion methods." }, "product_categories": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Product category hex IDs (32-char) — resolve via get_product_category. Invalid IDs are not rejected: they match nothing and return total_count 0." }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] }, "fai": { "type": "object", "properties": { "departments": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee departments (hex IDs)." }, "roles": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Functional-area hex IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buying-committee roles (hex IDs)." } }, "additionalProperties": false, "description": "Functional Area Intelligence — narrow installs by associated buying-committee departments and/or roles. At least one of departments/roles required." }, "install_age": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false }, "install_age_months": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Filter by product category." }, "product_attributes": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "Product attribute integer IDs" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT", "NONE_PRESENT" ] }, "install_age": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false }, "install_age_months": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Filter by product attributes." }, "country": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 codes, e.g. [\"US\",\"GB\"]" } }, "required": [ "codes" ], "additionalProperties": false, "description": "Filter by the install's own country (where the technology is deployed) — NOT the company HQ country." }, "product_last_verified_date": { "type": "object", "properties": { "min": { "type": "string", "description": "Earliest date, inclusive (YYYY-MM-DD)." }, "max": { "type": "string", "description": "Latest date, inclusive (YYYY-MM-DD)." } }, "additionalProperties": false, "description": "Filter installs by their last-verified date (inclusive YYYY-MM-DD range). At least one of min/max required." } }, "additionalProperties": false, "description": "Filters on detected technology installs (technographics)." }, "intent": { "type": "object", "properties": { "topics": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Intent topic hex IDs — resolve via list_intent_topics" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "ALL_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Intent topics (buying signal). ALL_PRESENT = company shows signal on all listed topics." }, "signal_score": { "type": "string", "enum": [ "MEDIUM", "HIGH" ], "description": "Minimum signal intensity: MEDIUM (score 65–84) or HIGH (score 85–100)." }, "context_type_ids": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Intent context type hex IDs." }, "buyers_journey_ids": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Buyer's journey stage hex IDs." }, "number_of_cadences": { "type": "integer", "description": "Number of cadences showing intent." }, "location": { "type": "object", "properties": { "country_alpha2s": { "type": "array", "items": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "ISO-2 country codes" }, "inclusion_method": { "type": "string", "enum": [ "ANY_PRESENT", "NONE_PRESENT" ] } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false } }, "region_names": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false }, "state_ids": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Hex-encoded IDs" }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Filter by where the intent signal was detected (not company HQ). At least one sub-field required." } }, "additionalProperties": false, "description": "Intent signal filters — companies showing buying interest on topics or in locations." }, "ai_maturity": { "type": "object", "properties": { "ai_maturity_score": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false, "description": "Composite AI maturity score (0–100)." }, "ai_maturity_rank": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "AI maturity rank (1 = highest)." }, "ai_maturity_6m_delta": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false, "description": "6-month change in AI maturity score." }, "genai_intent_score": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "GenAI buying-intent score (0–100)." }, "ai_product_use": { "type": "boolean", "description": "true = only companies with an AI product installed." }, "data_maturity_level": { "type": "array", "items": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Data maturity tier." }, "dominant_cloud_provider": { "type": "array", "items": { "type": "string" }, "description": "Dominant cloud provider name(s)." } }, "additionalProperties": false, "description": "AI and data maturity filters." }, "cloud_maturity": { "type": "object", "properties": { "aws_products_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Count of AWS products in the stack." }, "azure_products_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Count of Azure products in the stack." }, "gcp_products_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Count of GCP products in the stack." }, "cloud_stack_percent_change": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Change in cloud stack size — may be negative (min/max accept negative bounds)." }, "current_products_used_cloud_percent": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Cloud share (%) of current products used." }, "current_products_used_total_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Total count of current products used." }, "new_products_used_cloud_percent": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "additionalProperties": false, "description": "Cloud share (%) of newly-adopted products." } }, "additionalProperties": false, "description": "Cloud adoption/maturity filters (integer ranges)." }, "corporate_hierarchy": { "type": "object", "properties": { "is_corporate_parent": { "type": "boolean", "description": "true = only corporate parents." }, "is_domestic_parent": { "type": "boolean", "description": "true = only domestic parents." }, "is_global_headquarters": { "type": "boolean", "description": "true = only global headquarters." } }, "additionalProperties": false, "description": "DEPRECATED — prefer firmographics.company_level, which takes precedence when both are set. Boolean corporate-hierarchy flags." }, "spend": { "type": "array", "items": { "type": "object", "properties": { "categories": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Spend category hex IDs" }, "inclusion_method": { "type": "string", "const": "ANY_PRESENT" } }, "required": [ "ids", "inclusion_method" ], "additionalProperties": false, "description": "Required. Spend category to filter on." }, "range": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false, "description": "Required. Spend range in USD (min and/or max)." } }, "required": [ "categories", "range" ], "additionalProperties": false }, "description": "Filter by IT spend in a category. Array of clauses — each requires categories + range." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum companies to return per page (default: 10, hard max: 100). Use 10–50 for exploration; paginate with offset for bulk workflows. total_count reports the full match count regardless of limit." }, "offset": { "type": "integer", "minimum": 0, "maximum": 24999, "description": "Pagination offset (0–24999). total_count gives total matches across all pages." }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ASC", "DESC" ] }, "field": { "type": "string", "enum": [ "id", "name", "domain", "domain_normalized", "ai_maturity_score", "ai_maturity_rank", "ai_maturity_6m_delta", "genai_intent_score", "current_products_used_cloud_percent", "cloud_stack_percent_change" ] } }, "required": [ "direction", "field" ], "additionalProperties": false }, "description": "Sort order — array of {direction, field}. Sortable: id, name, domain, domain_normalized, plus ranking signals (ai_maturity_score, ai_maturity_rank, ai_maturity_6m_delta, genai_intent_score, current_products_used_cloud_percent, cloud_stack_percent_change) — the ranking signals can be sorted/filtered but are not returned as result columns." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "hg_id": { "type": "string", "description": "HG Insights company ID (31-32-char hex; leading zeros may be truncated). Pass to enrichment tools (company_firmographic, company_technographic, company_enrich, etc.)." }, "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "domain_normalized": { "type": [ "string", "null" ] } }, "required": [ "hg_id" ], "additionalProperties": true }, "description": "Array of matching company results." }, "total_count": { "type": "number", "description": "Total matching companies across all pages." } }, "required": [ "companies", "total_count" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "search_federal_contracts", "description": "Broad SEARCH of U.S. federal contract AWARDS (already-signed obligations) across many recipients, sourced from USAspending.gov. 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, awarding agency/sub-agency, obligated dollar amount, contract type, dates, and place of performance. Results are ranked by amount or date.\n\nUse 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 (Computer Systems Design) awards\", \"small-business set-aside awards from the VA\", or \"who holds contracts with the Department of Energy?\".\n\nDo NOT use this when: (1) you already know the company and want ITS contract footprint — use company_contracts (a specific company's federal award history); (2) you want OPEN solicitations / RFPs a company can still bid on rather than awards already made — use search_gov_opportunities (open opportunities) or company_gov_opportunities (one company's pipeline); (3) you want a company's agency relationships/history — use company_gov_relationships.\n\nRequires the SAM.gov (Data.gov) integration to be configured.", "inputSchema": { "type": "object", "properties": { "recipientName": { "type": "string", "description": "Recipient (awardee) company name, partial/fuzzy match, e.g. \"Lockheed Martin\". For a single known company prefer company_contracts; use recipientUei here for an exact match." }, "recipientUei": { "type": "string", "description": "Exact 12-character SAM.gov Unique Entity Identifier (UEI) of the recipient. Use for a precise match instead of fuzzy recipientName; takes precedence when both are given." }, "awardingAgency": { "type": "string", "description": "Awarding agency name to filter by, e.g. \"Department of Defense\" or \"Department of Veterans Affairs\"." }, "naicsCode": { "type": "string", "description": "6-digit NAICS industry code to filter by, e.g. \"541512\" (Computer Systems Design Services). Look codes up with search_industries_naics_sic if unknown." }, "pscCode": { "type": "string", "description": "Product/Service Code (PSC) to filter by, e.g. \"D310\" (IT & telecom — cyber security). Categorizes what was bought, complementary to naicsCode." }, "keywords": { "type": "string", "description": "Free-text terms matched against contract descriptions, e.g. \"cybersecurity\" or \"cloud migration\"." }, "minAmount": { "type": "number", "description": "Minimum total obligated amount in USD (inclusive), e.g. 10000000 for $10M+ awards." }, "maxAmount": { "type": "number", "description": "Maximum total obligated amount in USD (inclusive)." }, "startDateAfter": { "type": "string", "description": "Only awards whose period-of-performance start date is on/after this date (ISO \"YYYY-MM-DD\", e.g. \"2024-01-01\")." }, "startDateBefore": { "type": "string", "description": "Only awards whose period-of-performance start date is on/before this date (ISO \"YYYY-MM-DD\")." }, "setAsideType": { "type": "string", "description": "Small-business set-aside type code, e.g. \"SBA\" (Total Small Business), \"8A\", \"WOSB\", \"HZC\" (HUBZone). Omit to include all award types." }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of awards to return (1-100, default 50)." }, "offset": { "type": "number", "minimum": 0, "default": 0, "description": "Number of awards to skip for pagination, in the current sort order (default 0)." }, "sortBy": { "type": "string", "enum": [ "amount", "date" ], "default": "amount", "description": "Ranking field: \"amount\" (obligated dollar value) or \"date\" (award start date). Default \"amount\"." }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction for sortBy: \"desc\" (largest/most recent first) or \"asc\". Default \"desc\"." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "totalCount": { "type": "number", "description": "Total matching contracts" }, "contracts": { "type": "array", "items": { "type": "object", "properties": { "awardId": { "type": "string" }, "recipientName": { "type": "string" }, "recipientUei": { "type": "string" }, "awardingAgency": { "type": "string" }, "awardingSubAgency": { "type": "string" }, "totalObligation": { "type": "number" }, "totalObligationFormatted": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "contractType": { "type": "string" }, "naicsCode": { "type": "string" }, "naicsDescription": { "type": "string" }, "pscCode": { "type": "string" }, "pscDescription": { "type": "string" }, "setAsideType": { "type": "string" }, "placeOfPerformance": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": true }, "description": { "type": "string" } }, "additionalProperties": true }, "description": "List of federal contract awards matching the search criteria" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" } }, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "search_gov_opportunities", "description": "Broad market SEARCH of OPEN U.S. federal contracting opportunities on SAM.gov — solicitations (RFPs, RFQs), presolicitations, and sources-sought notices that agencies are actively soliciting bids on. Use this when you want to FIND open solicitations across the whole federal market by criteria — a keyword, NAICS code, PSC/classification code, awarding agency, small-business set-aside type, posting-date window, or response-deadline window — without knowing any particular vendor. Returns each opportunity with its title, awarding agency, notice type, set-aside, NAICS, posting date, response deadline, days-until-deadline, place of performance, and a direct SAM.gov link, plus a total match count for pagination. Do NOT use this when you already have a SPECIFIC company and want opportunities relevant to them (their NAICS registration, incumbency, or agency relationships) — use company_gov_opportunities instead. Do NOT use this to look up AWARDED/historical contracts (who won, dollar amounts) — those are closed transactions, use search_federal_contracts. Note: keywords matches opportunity TITLES only (not full-notice text), so keep them short and general. Requires the SAM.gov (Data.gov) integration to be configured.", "inputSchema": { "type": "object", "properties": { "keywords": { "type": "string", "description": "Free-text term matched against opportunity TITLES only (not full-notice text). Keep it short and general, e.g. \"cybersecurity\" or \"cloud\"; long phrases match poorly. To narrow by industry instead, prefer naicsCode." }, "naicsCode": { "type": "string", "description": "6-digit NAICS industry code to filter by, e.g. \"541512\" (Computer Systems Design). Resolve an industry name to a code via search_industries_naics_sic." }, "pscCode": { "type": "string", "description": "Federal Product/Service Code (PSC) classifying the good or service, e.g. \"D307\" (IT systems development). More specific than NAICS for the deliverable itself." }, "agency": { "type": "string", "description": "Awarding department/agency name to filter by, e.g. \"Department of Defense\" or \"General Services Administration\"." }, "setAsideType": { "type": "string", "description": "SAM.gov small-business set-aside code, e.g. \"SBA\" (Total Small Business), \"SDVOSBC\" (Service-Disabled Veteran-Owned), \"8A\", \"WOSB\", \"HZC\". Omit to include all opportunities regardless of set-aside." }, "postedAfter": { "type": "string", "description": "Lower bound on the notice posting date. ISO date \"YYYY-MM-DD\", e.g. \"2025-01-01\"." }, "postedBefore": { "type": "string", "description": "Upper bound on the notice posting date. ISO date \"YYYY-MM-DD\"." }, "responseDeadlineAfter": { "type": "string", "description": "Only opportunities whose bid response deadline falls on or after this date. ISO date \"YYYY-MM-DD\". Use with responseDeadlineBefore to find opportunities closing within a window." }, "responseDeadlineBefore": { "type": "string", "description": "Only opportunities whose bid response deadline falls on or before this date. ISO date \"YYYY-MM-DD\". Useful for surfacing opportunities closing soon." }, "opportunityType": { "type": "string", "enum": [ "solicitation", "presolicitation", "award", "sources_sought" ], "description": "Restrict to one notice type: \"solicitation\" (active RFP/RFQ open for bids), \"presolicitation\" (advance notice, not yet biddable), \"sources_sought\" (market research request), or \"award\" (notice of a made award). Omit to include all types." }, "activeOnly": { "type": "boolean", "default": true, "description": "When true (default), returns only active/open notices. Set false to include archived/inactive notices." }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of opportunities to return, 1-100 (default: 25)." }, "offset": { "type": "number", "minimum": 0, "default": 0, "description": "Number of results to skip for pagination (default: 0). Combine with limit and the returned totalCount/hasMore to page through results." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "totalCount": { "type": "number", "description": "Total matching opportunities" }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "opportunityId": { "type": "string" }, "title": { "type": "string" }, "solicitationNumber": { "type": "string" }, "agency": { "type": "string" }, "subAgency": { "type": "string" }, "postedDate": { "type": "string" }, "responseDeadline": { "type": "string" }, "daysUntilDeadline": { "type": "number" }, "type": { "type": "string" }, "setAsideType": { "type": "string" }, "naicsCode": { "type": "string" }, "classificationCode": { "type": "string" }, "placeOfPerformance": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": true }, "description": { "type": "string" }, "link": { "type": "string" } }, "additionalProperties": true }, "description": "List of federal opportunities/solicitations matching the search criteria" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" } }, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "search_industries_naics_sic", "description": "RESOLVER: find industry codes (HG industry_id, NAICS, SIC) by keyword to feed into `search_companies` (`industry_ids`, `naics_codes`, `sic_codes`). Searches/translates 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` (pass `companyDomain`/`hg_id`); this searches taxonomy definitions, not company records. Do NOT use for technology/product categories (\"IaaS\",\"CRM\",\"cloud infrastructure\") — use get_product_category. Use cases: (1) q=\"software publishers\" name fragment; (2) q=\"541511\" code crosswalk; (3) q=52 numeric prefix→sector+descendants; (4) q=\"software,saas\" multi-term OR; (5) 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: empty results + near-miss q → up to 5 suggestions (taxonomy name near-misses only). NAICS: hierarchy_level (sector|subsector|industry_group|naics_industry|national_industry) + 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.", "inputSchema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 2, "description": "Optional. Text input → case-insensitive substring match against industry/NAICS/SIC name columns. All-digit input → prefix match against code columns only (e.g. `q=52` returns NAICS sector 52 and its descendants, not codes that merely contain \"52\" like 1152). Multi-term: comma-separated (`software,publishing,saas`) runs the union (OR). Colloquial terms (fintech, saas, healthcare, cleantech, ev, cybersecurity, …) are expanded server-side; the response's `alias_expansions` shows what ran. Minimum 2 characters." }, "taxonomy": { "type": "string", "enum": [ "industry", "naics", "sic" ], "description": "Optional. Restricts matching to one taxonomy AND groups results by its primary key — one row per distinct entity with crosswalk counts on the matched block. Other blocks become {}. Pick the taxonomy your downstream filter needs: `industry` → `search_companies.industry_ids`, `naics` → `naics_codes`, `sic` → `sic_codes`." }, "naics_leaf_only": { "type": "boolean", "default": false, "description": "Only meaningful when `taxonomy=naics`. When true, drops 2/3/4/5-digit NAICS rollup codes and returns only the 6-digit leaf codes — the safe codes to chain into `search_companies.naics_codes`, since rollups will not match a single company's classification. Silently ignored for other taxonomies." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50, "description": "Page size, 1–500. Default 50." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Page offset, ≥ 0. Default 0." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "matched_on": { "type": "string", "enum": [ "industry", "naics", "sic" ], "description": "Which taxonomy produced the match. Present when `q` is set." }, "industry": { "type": "object", "properties": { "industry_id": { "type": [ "number", "null" ] }, "industry_name": { "type": [ "string", "null" ] }, "naics_count": { "type": [ "number", "null" ], "description": "Crosswalk count — populated only in grouped mode (taxonomy=industry)." }, "sic_count": { "type": [ "number", "null" ], "description": "Crosswalk count — populated only in grouped mode (taxonomy=industry)." } }, "additionalProperties": true, "description": "HG industry block. {} when not the matched/populated taxonomy." }, "naics": { "type": "object", "properties": { "naics_code": { "type": [ "string", "null" ] }, "naics_name": { "type": [ "string", "null" ] }, "naics_top_parent_code": { "type": [ "string", "null" ] }, "naics_top_parent_name": { "type": [ "string", "null" ] }, "hierarchy_level": { "type": [ "string", "null" ], "description": "NAICS level derived from code length (2/3/4/5/6 digits)." }, "is_leaf": { "type": [ "boolean", "null" ], "description": "True iff `hierarchy_level == \"national_industry\"`. Only leaves are safe to chain into downstream code-based filters." }, "display_name_with_level": { "type": [ "string", "null" ], "description": "Disambiguating label, e.g. \"Commercial Banking (subsector 5221)\"." }, "sic_count": { "type": [ "number", "null" ], "description": "Crosswalk count — populated only in grouped mode (taxonomy=naics)." } }, "additionalProperties": true, "description": "NAICS 2012 block. {} when not the matched/populated taxonomy." }, "sic": { "type": "object", "properties": { "sic_code": { "type": [ "string", "null" ], "description": "HG-extended SIC code (carries an internal letter prefix, e.g. \"I7372\"). Do NOT pass to downstream APIs — use `sic_standard_code` instead." }, "sic_standard_code": { "type": [ "string", "null" ], "description": "Standard SIC-1987 code (e.g. \"7372\"). This is the value to pass to downstream APIs. Empty for sector-level rows." }, "sic_name": { "type": [ "string", "null" ] }, "is_hg_extension": { "type": [ "boolean", "null" ], "description": "True when `sic_code` carries an HG-internal letter prefix (currently true for every SIC row)." }, "naics_count": { "type": [ "number", "null" ], "description": "Crosswalk count — populated only in grouped mode (taxonomy=sic)." } }, "additionalProperties": true, "description": "SIC 1987 block. {} when not the matched/populated taxonomy." } }, "required": [ "industry", "naics", "sic" ], "additionalProperties": true }, "description": "Crosswalk rows. In unscoped mode, one row per match across taxonomies. In grouped mode, one row per distinct entity in the requested taxonomy." }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total rows matching the filter (not just this page)." }, "limit": { "type": "number" }, "offset": { "type": "number" }, "has_more": { "type": "boolean" }, "total_pages": { "type": "number", "description": "ceil(total / limit)." }, "offset_exceeds_total": { "type": "boolean", "description": "True when `offset >= total` and `total > 0` — diagnostic for paging-past-end bugs." } }, "required": [ "total", "limit", "offset", "has_more", "total_pages" ], "additionalProperties": true }, "alias_expansions": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "expanded_to": { "type": "array", "items": { "type": "string" } } }, "required": [ "term", "expanded_to" ], "additionalProperties": true } }, { "type": "null" } ], "description": "Present only when one or more `q` terms were rewritten server-side. Each entry shows the colloquial term and the substrings it expanded to." }, "suggestions": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "null" ] } }, { "type": "null" } ], "description": "Present only when `results` is empty AND `q` contained a text term. Up to 5 closest taxonomy names by trigram distance — use to self-heal typos / near-misses before retrying." } }, "required": [ "results", "pagination" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "sec_filing_section", "description": "Fetch the full text of one named section from a specific company's SEC 10-K (annual), 10-Q (quarterly), or 8-K (current event) filing, returned as clean text. You supply the ticker, filing type, and section code (topic-to-code mapping is in the \"section\" parameter). Returns the single most recent matching filing.\n\nUSE when you already know WHICH section of WHICH company you want to read — e.g. \"What are Microsoft's risk factors?\", \"Show me Apple's MD&A\", \"Get AAPL's latest earnings 8-K\", \"Read Tesla's legal proceedings\".\n\nDo NOT use to search filings by keyword or across companies (e.g. \"which filings mention 'material weakness'?\") — use sec_full_text_search. For general company background (revenue, headcount, products) use company_enrich (or company_firmographic); for non-SEC web info use web_search.\n\nSCOPE: US domestic issuers only (10-K / 10-Q / 8-K). Foreign private issuers file 20-F / 6-K / 40-F instead (e.g., Barclays, BP, SAP, Toyota) — this tool returns \"No filing found\" for them; use sec_full_text_search with filingTypes: [\"20-F\"] or [\"6-K\"].\n\nFISCAL FILTERING: fiscalYear narrows by calendar year; quarter-precise filtering is NOT supported — use dateFrom/dateTo instead (also for recurring 8-K events like 2.02 earnings).\n\nPROXY STUBS: For most large-caps, 10-K sections 10–14 (Directors, Compensation, Security Ownership, Related Party, Accountant Fees) are incorporated by reference from the DEF 14A Proxy Statement and return a short stub — if content is under 100 words and mentions a Proxy Statement, the full data is not available here.\n\n8-K EXHIBIT NOTE: Items like 2.02 (earnings) often return only a stub referencing Exhibit 99.1; the exhibit text is not returned — for the full earnings narrative use sec_full_text_search.\n\nDo not call if the filing section content is already present in the conversation.", "inputSchema": { "type": "object", "properties": { "companyTicker": { "type": "string", "minLength": 1, "maxLength": 10, "pattern": "^[A-Za-z0-9.\\-]{1,10}$", "description": "Stock ticker symbol of a US-listed company (e.g., \"AAPL\", \"MSFT\", \"CRM\"). Case-insensitive; class shares use a dot or hyphen (e.g., \"BRK.A\", \"BF-B\")." }, "filingType": { "type": "string", "enum": [ "10-K", "10-Q", "8-K" ], "description": "Filing form to read: \"10-K\" (annual report), \"10-Q\" (quarterly report), or \"8-K\" (current-event disclosure). US domestic issuers only — use sec_full_text_search for 20-F/6-K/40-F foreign issuers. The valid \"section\" codes depend on this value." }, "section": { "type": "string", "description": "Section code to extract. Must belong to the chosen filingType. Choose the code that matches the topic below.\n\n10-K ANNUAL REPORTS:\n\"1\" Business (overview, products, markets, strategy) · \"1A\" Risk Factors (risks, challenges, threats) · \"1B\" Unresolved Staff Comments · \"2\" Properties (facilities, real estate) · \"3\" Legal Proceedings (lawsuits, litigation) · \"4\" Mine Safety · \"5\" Market for Common Equity · \"6\" Selected Financial Data · \"7\" MD&A (financial performance, trends) · \"7A\" Market Risk Disclosures · \"8\" Financial Statements · \"9\" Accountant Disagreements · \"9A\" Controls and Procedures · \"9B\" Other Information · \"10\" Directors & Officers (board, leadership) · \"11\" Executive Compensation (pay, bonuses, stock options) · \"12\" Security Ownership · \"13\" Related Party Transactions · \"14\" Principal Accountant Fees · \"15\" Exhibits\n\n10-Q QUARTERLY REPORTS:\n\"part1item1\" Financial Statements · \"part1item2\" MD&A (quarterly performance) · \"part1item3\" Market Risk · \"part1item4\" Controls and Procedures · \"part2item1\" Legal Proceedings · \"part2item1a\" Risk Factors · \"part2item2\" Unregistered Equity Sales · \"part2item3\" Defaults on Senior Securities · \"part2item4\" Mine Safety · \"part2item5\" Other Information · \"part2item6\" Exhibits\n\n8-K CURRENT EVENTS:\n\"1.01\" Material Agreement (new contracts, partnerships) · \"1.02\" Termination of Agreement · \"1.03\" Bankruptcy · \"1.04\" Mine Safety · \"1.05\" Cybersecurity Incident · \"2.01\" Acquisition/Disposition (M&A) · \"2.02\" Results of Operations (earnings) · \"2.03\" Financial Obligation · \"2.04\" Triggering Events · \"2.05\" Exit/Disposal Costs · \"2.06\" Material Impairments · \"3.01\" Delisting Notice · \"3.02\" Unregistered Equity Sales · \"3.03\" Rights Modifications · \"4.01\" Accountant Changes · \"4.02\" Non-Reliance on Financials · \"5.01\" Control Changes · \"5.02\" Officer Changes (CEO/CFO departures/appointments) · \"5.03\" Bylaws Amendments · \"5.04\" Trading Suspension · \"5.05\" Ethics Code Amendments · \"5.06\" Shell Company Status · \"5.07\" Shareholder Vote · \"5.08\" Shareholder Nominations · \"7.01\" Regulation FD Disclosure · \"8.01\" Other Events · \"9.01\" Financial Statements and Exhibits" }, "fiscalYear": { "type": "number", "description": "Calendar year to filter by (e.g., 2024), matched against the filing's periodOfReport (Jan 1–Dec 31). Omit to get the single most recent filing." }, "fiscalQuarter": { "type": "number", "minimum": 1, "maximum": 4, "description": "Informational annotation only — does NOT filter results and is NOT reflected in the response. Must be paired with fiscalYear. Quarter-precise filtering is not supported; use dateFrom/dateTo instead. Verify which filing was selected via the returned periodOfReport field." }, "maxWords": { "type": "integer", "minimum": 100, "maximum": 50000, "description": "Truncate the returned section content to this many words. Omit for the full section (typically 5,000–15,000 words for 10-K sections). Use 1000–3000 for a quick summary-sized extract, 5000+ for detailed analysis." }, "dateFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only return filings filed on or after this date (ISO 8601, e.g. \"2024-07-01\"). Most useful for 8-K event windows." }, "dateTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only return filings filed on or before this date (ISO 8601, e.g. \"2024-07-31\"). Inclusive of the whole day. Most useful for 8-K event windows." } }, "required": [ "companyTicker", "filingType", "section" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Full company name from the filing" }, "ticker": { "type": "string", "description": "Stock ticker symbol" }, "cik": { "type": "string", "description": "SEC Central Index Key" }, "filingType": { "type": "string", "enum": [ "10-K", "10-Q", "8-K" ], "description": "Type of SEC filing" }, "filingDate": { "type": "string", "description": "Date the filing was submitted to SEC" }, "periodOfReport": { "type": "string", "description": "Period covered by the filing" }, "section": { "type": "string", "description": "Section code that was extracted" }, "sectionLabel": { "type": "string", "description": "Human-readable section name" }, "content": { "type": "string", "description": "Extracted section content" }, "contentFormat": { "type": "string", "enum": [ "text" ], "description": "Format of the content (always cleaned text)" }, "filingUrl": { "type": "string", "description": "URL to the original SEC filing" }, "wordCount": { "type": "number", "description": "Word count of the extracted content" }, "metadata": { "type": "object", "properties": { "accessionNumber": { "type": "string", "description": "SEC accession number for the filing" }, "fiscalYear": { "type": "number", "description": "Fiscal year of the filing" }, "fiscalQuarter": { "type": "number", "description": "Fiscal quarter (for 10-Q filings)" } }, "required": [ "accessionNumber" ], "additionalProperties": true, "description": "Additional filing details and fiscal period metadata" } }, "required": [ "companyName", "ticker", "cik", "filingType", "filingDate", "periodOfReport", "section", "sectionLabel", "content", "contentFormat", "filingUrl", "wordCount", "metadata" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "sec_full_text_search", "description": "Search within SEC filing content (the EDGAR full-text index) for specific terms or phrases. Thin wrapper around the sec-api.io full-text-search API. Accepts ticker symbols and resolves them to CIKs automatically.\n\nUse when the user wants filings that mention or contain a term/phrase. Supports AND, OR, NOT, wildcards (*), and exact phrases (\"quoted\"). Generic words like \"award\" also match boilerplate (stock awards) — prefer exact phrases.\n\nDO 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 (revenue, employees, technographics) use company_enrich; for non-SEC web info use web_search.\n\nDOMAIN→TICKER: accepts tickers only, not domains. Given a domain or name, resolve it to a ticker first (via web_search or company_firmographic) — company_firmographic does not itself return filing text.\n\nSCOPING: omitting BOTH tickers and formTypes searches the entire EDGAR corpus and can return a capped ~10,000-result flood of unrelated issuers (total is approximate at that cap). Always pass tickers (preferred) or at least formTypes unless a cross-company sweep is intended.\n\nDATES: startDate defaults to the last 30 days. Annual filings (10-K, 20-F, 40-F) are yearly — pass startDate \"2020-01-01\" for them or you get zero results.\n\nReturns 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 and results are unfiltered — check it (and warnings) before treating results as company-specific.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "default": "cybersecurity incident", "description": "Search query. Supports AND, OR, NOT, wildcards (*), and exact phrases (\"quoted\"). NOT for extracting a named section from a specific filing — use sec_filing_section. Scope broad/common-word queries with tickers or formTypes; a bare query searches the entire EDGAR corpus." }, "formTypes": { "type": "array", "items": { "type": "string" }, "description": "Filter by SEC form type (e.g., [\"8-K\", \"10-K\", \"20-F\"]). Recommended for wildcard queries to reduce noise: [\"8-K\", \"10-K\", \"10-Q\"]. Matching is family-based, not exact: [\"10-K\"] also returns 10-K/A and NT 10-K; [\"8-K\"] also returns 8-K/A and CORRESP. Post-filter on each result's formType field if you need exact types. Note: sec_filing_section calls this concept filingType — a singular enum string, not an array." }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Filter by company ticker symbol (e.g., [\"MSFT\", \"AAPL\"]). Resolved to CIKs automatically via the sec-api.io Mapping API for real server-side filtering. IMPORTANT: if resolvedCiks in the response is empty, the ticker(s) could not be resolved and NO filter was applied — results are the full unfiltered corpus, not company-specific. Always check resolvedCiks (and the warnings array) before trusting results as company-specific. Some foreign/ADR issuers may not resolve." }, "startDate": { "type": "string", "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago. For annual filings (10-K, 20-F, 40-F) pass \"2020-01-01\" — the 30-day default misses most annual reports." }, "endDate": { "type": "string", "description": "End date (YYYY-MM-DD). Defaults to today." }, "page": { "type": "string", "pattern": "^[1-9]\\d*$", "default": "1", "description": "Page of results (default \"1\"). Each page returns up to 100 filings. Use \"2\", \"3\", etc. to paginate." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching filings across all pages" }, "query": { "type": "string", "description": "The search query that was executed" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal advisories about this result set. Populated when a ticker did not resolve (so no company filter was applied), when only some tickers resolved, or when zero filings matched. Empty/absent means no advisories." }, "filings": { "type": "array", "items": { "type": "object", "properties": { "accessionNumber": { "type": "string", "description": "SEC accession number" }, "formType": { "type": "string", "description": "SEC form type (10-K, 10-Q, 8-K, 20-F, etc.)" }, "filedAt": { "type": "string", "description": "Filing date (YYYY-MM-DD)" }, "companyName": { "type": [ "string", "null" ], "description": "Company name" }, "ticker": { "type": [ "string", "null" ], "description": "Stock ticker (null for foreign or CIK-only filers)" }, "cik": { "type": "string", "description": "SEC Central Index Key" }, "filingUrl": { "type": "string", "description": "Direct URL to the SEC filing" }, "description": { "type": [ "string", "null" ], "description": "Filing description" } }, "required": [ "accessionNumber", "formType", "filedAt", "cik", "filingUrl" ], "additionalProperties": true }, "description": "Up to 100 matching filings for this page" }, "searchParams": { "type": "object", "properties": { "formTypes": { "type": "array", "items": { "type": "string" } }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Input tickers" }, "resolvedCiks": { "type": "array", "items": { "type": "string" }, "description": "CIKs resolved from tickers and passed to the API" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "page": { "type": "string" } }, "additionalProperties": true, "description": "Parameters sent to the API" } }, "required": [ "total", "query", "filings", "searchParams" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "web_search", "description": "General-purpose web search for information that is NOT in HG Insights' proprietary data — recent news, general facts, and public-web context about people, products, or events outside HG's firmographic/technographic/intent datasets. Runs a live search (Tavily) and returns relevant results (title, URL, content snippet) plus an optional AI-generated answer summary. Cost: 0.05 credits (searchDepth='basic') or 0.10 credits (searchDepth='advanced' deep extraction). \n\nUse when: you need current/breaking news, background on a person or topic, or any fact that lives on the open web rather than in HG's structured data. \n\nDo NOT use when a purpose-built HG tool covers the request — reach for company_enrich or company_firmographic (company profile/size/HQ/industry), company_technographic (installed technologies), company_intent (buying signals), or search_companies (find companies by criteria) instead, since those return richer, structured, billable HG data. Do NOT use to search SEC filing text — use sec_full_text_search. Do NOT use for general knowledge you already know; reserve it for live/current facts. \n\nOPERATORS: boolean exclusion syntax (-term) is NOT honored — do not assume Google-style minus-sign exclusion works; filter unwanted results yourself. \n\nVERBOSITY: includeRawContent=true returns full cleaned page content per result (no extra Tavily cost) but can add ~10KB+ of boilerplate per result — enable it only when you need full text, and keep maxResults low. searchDepth 'advanced' improves extraction (recommended with includeRawContent) at 2x cost.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Natural-language web search query. Required, non-empty (whitespace-only is rejected), max 500 chars. Be specific — include names, dates, or qualifiers (\"Q3 2025 Cisco layoffs\", not \"Cisco news\") for sharper results. Boolean exclusion (-term) is NOT honored — do not rely on Google-style minus-sign syntax; filter unwanted results yourself." }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Maximum number of results to return, 1-20 (default 5). Raise for broad topic scans; keep low for a quick fact check." }, "includeRawContent": { "type": "boolean", "default": false, "description": "When true, each result also includes the full cleaned page body (rawContent), not just a short snippet — use it when you need to read/quote the source. Default false. No extra Tavily credit cost; adds a little latency. Can return ~10KB+ of boilerplate per result, so keep maxResults low when enabling. Pair with searchDepth='advanced' for best extraction." }, "searchDepth": { "type": "string", "enum": [ "basic", "advanced" ], "default": "basic", "description": "Search thoroughness. 'basic' (0.05 credits, default) is fast and fine for most lookups; 'advanced' (0.10 credits) does deeper crawling with higher-quality content extraction — recommended when includeRawContent is true or the topic is niche/hard to find." } }, "required": [ "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query that was executed" }, "answer": { "type": [ "string", "null" ], "description": "AI-generated answer summarizing the search results (null when not available)" }, "requestId": { "type": "string", "description": "Unique identifier for the search request" }, "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "url": { "type": "string", "description": "Page URL" }, "content": { "type": "string", "description": "Snippet of page content" }, "rawContent": { "type": [ "string", "null" ], "description": "Raw page content when requested (null when include_raw_content is false)" }, "score": { "type": "number", "description": "Relevance score" }, "publishedDate": { "type": "string", "description": "Publication date if available" } }, "required": [ "title", "url", "content" ], "additionalProperties": true }, "description": "Search results" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL" }, "description": { "type": "string", "description": "Image description" } }, "additionalProperties": true }, "description": "Related images (when available)" }, "responseTime": { "type": "number", "description": "Time taken for search in seconds" } }, "required": [ "query", "results" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "get_product_information", "description": "Comprehensive TrustRadius product information for a software product by name — overview, rating and review count, and (optionally) pricing, competitors, integrations, and the TrustRadius score breakdown.", "inputSchema": { "type": "object", "properties": { "productName": { "type": "string", "description": "Search for product by name (e.g., \"Salesforce Sales Cloud\", \"HubSpot CRM\")" }, "includePricing": { "type": "boolean", "description": "Include pricing information (default: true)", "default": true }, "includeCompetitors": { "type": "boolean", "description": "Include competitor list (default: true)", "default": true }, "includeIntegrations": { "type": "boolean", "description": "Include integrations list (default: true)", "default": true }, "includeTrScore": { "type": "boolean", "description": "Include TrustRadius score breakdown (default: false)", "default": false } }, "required": [ "productName" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "product": { "type": "object", "description": "Basic product information", "properties": { "name": { "type": "string", "description": "Product name" }, "description": { "type": "string", "description": "Product description" }, "vendor": { "type": "string", "description": "Vendor/company name" }, "category": { "type": "string", "description": "Product category" }, "rating": { "type": "number", "description": "Overall rating" }, "reviewCount": { "type": "number", "description": "Total number of reviews" } } }, "pricing": { "type": "object", "description": "Pricing information (if available)", "properties": { "model": { "type": "string", "description": "Pricing model (subscription, one-time, etc.)" }, "plans": { "type": "array", "items": { "type": "object" }, "description": "Available pricing plans" }, "hasFreeVersion": { "type": "boolean", "description": "Whether a free version is available" }, "hasFreeTrial": { "type": "boolean", "description": "Whether a free trial is available" } } }, "competitors": { "description": "Competitor products data (may be array or object with error)" }, "integrations": { "description": "Product integrations/connectors data (may be array or object with error)" }, "ratings": { "type": "object", "description": "TrustRadius score breakdown (if requested)", "properties": { "trScore": { "type": "number", "description": "TrustRadius score" }, "breakdown": { "type": "object", "description": "Score breakdown by category" } } } }, "additionalProperties": true } }, { "name": "get_product_reviews", "description": "Filtered TrustRadius reviews for a software product by name — date range, rating bounds, and pagination, with an aggregated pros/cons summary and per-review reviewer firmographics.", "inputSchema": { "type": "object", "properties": { "productName": { "type": "string", "description": "Search for product by name (e.g., \"Salesforce Sales Cloud\", \"HubSpot CRM\")" }, "dateFrom": { "type": "string", "description": "Filter reviews from this date (ISO format, e.g., \"2024-01-01\"). Defaults to 90 days ago." }, "dateTo": { "type": "string", "description": "Filter reviews until this date (ISO format). Defaults to today." }, "minRating": { "type": "number", "description": "Minimum rating filter (1-10 scale)", "minimum": 1, "maximum": 10 }, "maxRating": { "type": "number", "description": "Maximum rating filter (1-10 scale)", "minimum": 1, "maximum": 10 }, "page": { "type": "number", "description": "Page number (default: 1)", "default": 1, "minimum": 1 }, "pageSize": { "type": "number", "description": "Results per page (default: 10, max: 50)", "default": 10, "minimum": 1, "maximum": 50 }, "includeProsAndCons": { "type": "boolean", "description": "Include aggregated pros and cons (default: true)", "default": true } }, "required": [ "productName" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "product": { "type": "object", "description": "Product information", "properties": { "name": { "type": "string", "description": "Product name" }, "id": { "type": "string", "description": "TrustRadius product ID" } }, "required": [ "name", "id" ] }, "summary": { "type": "object", "description": "Review summary", "properties": { "totalReviews": { "type": "number", "description": "Total number of reviews matching criteria" }, "dateRange": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date of filter range" }, "to": { "type": "string", "description": "End date of filter range" } } }, "rating": { "type": "number", "description": "Average rating" }, "prosAndCons": { "type": "object", "description": "Aggregated pros and cons", "properties": { "pros": { "type": "array", "items": { "type": "string" }, "description": "Common pros" }, "cons": { "type": "array", "items": { "type": "string" }, "description": "Common cons" } } } } }, "reviews": { "type": "array", "description": "List of reviews", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Review title" }, "rating": { "type": "number", "description": "Review rating (1-10)" }, "createdAt": { "type": "string", "description": "Review date" }, "reviewer": { "type": "object", "description": "Reviewer information", "properties": { "jobTitle": { "type": "string", "description": "Reviewer job title" }, "companyName": { "type": "string", "description": "Reviewer company" }, "companySize": { "type": "string", "description": "Company size" }, "industry": { "type": "string", "description": "Industry" } } }, "questions": { "type": "array", "items": { "type": "object" }, "description": "Q&A from the review" } } } }, "pagination": { "type": "object", "description": "Pagination information", "properties": { "page": { "type": "number", "description": "Current page number" }, "pageSize": { "type": "number", "description": "Results per page" }, "totalPages": { "type": "number", "description": "Total number of pages" } }, "required": [ "page", "pageSize", "totalPages" ] } }, "required": [ "product", "summary", "reviews", "pagination" ], "additionalProperties": true } } ] }