{ "version": "v1", "tools": [ { "name": "company_ai_maturity", "description": "Scores how advanced a single company is at AI and data, its GenAI buying intent, and which cloud provider it centers on — call it when a user asks any of those about a named company. Returns the raw HG Insights AI-maturity signals: 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. Use this when you have one company (by domain or hg_id) and need its AI-maturity numbers, cloud centricity, or GenAI intent. Do NOT use this to build a target list of AI-advanced companies (use search_companies to find matching companies first), to get derived AI-adoption stage labels or a broader operating-signals rollup (use company_operating_signals), or to inspect the specific AI/ML products installed (use company_technographic). IMPORTANT — companyId signal: companyId:\"\" with aiMaturity:null means the company was not found or HG has no AI-maturity coverage for it. Provide companyDomain or hg_id; hg_id takes precedence.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company's registered web domain to look up (e.g., 'cisco.com'), not a company name or ticker. Either companyDomain or hg_id is required; if both are given, hg_id wins. Protocol prefixes (http://, https://), a leading www., and trailing paths/queries/fragments are accepted and stripped automatically, and case is lowercased — so 'https://www.Cisco.com/products' resolves to 'cisco.com'. Max 253 chars. If you only have a company name, resolve it to a domain with search_companies first." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company identifier: 31-32 characters, letters and digits only (hex-like). Takes precedence over companyDomain when both are supplied. Not a domain, DUNS, or ticker — obtain it from the `id` field of a prior search_companies result or another HG tool's output." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "HG Insights company identifier (hex). Empty string when the company is not found." }, "companyDomain": { "type": "string", "description": "The company domain that was queried." }, "aiMaturity": { "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", "description": "Dominant cloud provider." }, "cloud_intensity": { "type": "object", "properties": { "aws": { "type": "number" }, "azure": { "type": "number" }, "gcp": { "type": "number" } }, "additionalProperties": true, "description": "Per-provider rolled-up cloud detection volume. UNBOUNDED — real values run into the thousands (e.g. aws 4711), so these are NOT 0-100 scores, percentages, or dollar amounts. Use them to compare providers within this company; they scale with company size and footprint age, so do not compare across companies. company_operating_signals returns the same three numbers flat as aws_intensity/azure_intensity/gcp_intensity." }, "data_maturity_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Data maturity level." }, "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": [ "companyId", "companyDomain", "aiMaturity" ], "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 from HG Insights Cloud Dynamics (Intricately). Use this when you need to know WHICH cloud/CDN/hosting/DNS/email vendors a company uses, grouped by service category, plus when each was first detected and the company's geographic web-traffic split (North America / Latin America / Asia Pacific / EMEA percentages). Identify the company by domain (e.g., \"cisco.com\") or HG Insights company ID (hg_id); if both are given, hg_id wins. Note: despite the \"spend\" name, the response contains no dollar figures — it lists vendors and adoption dates, not billed amounts. Do NOT use this when you need a company's total product/technology spend in USD — use company_spend instead. Do NOT use this for on-premise or general software installs (CRM, databases, security) — use company_technographic instead. Filter to specific vendors via productList (fuzzy-matched). By default the response is capped at 10 vendors per service category, 50 service categories, and 100 vendors total (~30 KB); raise vendorsPerServiceLimit (max 50) / limit (max 200) for more, or set full=true for the entire payload (may exceed 90 KB on large accounts).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Registered/primary web domain of the company to look up cloud vendors for (e.g., \"cisco.com\"). Either companyDomain or hg_id is required; if both are given, hg_id takes precedence. 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 Intricately's database or the call returns a \"Company not found\" error." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company ID: 31-32 alphanumeric characters, obtained from a previous search_companies or company_firmographic result. When provided, it takes precedence over companyDomain and is resolved to a domain internally (this path additionally requires the \"hginsights\" v1 integration to be configured)." }, "productList": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Optional case-insensitive vendor/product names to narrow the results to (e.g., [\"Cloudflare\", \"Amazon EC2\"]). Matched fuzzily against detected vendor names (Fuse.js, threshold 0.6), 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 technologyServices entries to return (default: 50, max: 200). Ignored when full=true." }, "vendorsPerServiceLimit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of vendors to include per technologyServices 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; services beyond that cap are dropped." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "vendorName", "vendorLogo", "firstSeen" ] }, "description": "Project each vendor row to this subset of fields. vendorName 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." } }, "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", "description": "Company logo URL" } }, "required": [ "name", "website" ], "additionalProperties": true, "description": "Company information" }, "trafficDistribution": { "anyOf": [ { "type": "object", "properties": { "northAmericaPercent": { "type": [ "number", "null" ], "description": "Percentage of traffic from North America" }, "latinAmericaPercent": { "type": [ "number", "null" ], "description": "Percentage of traffic from Latin America" }, "asiaPacificPercent": { "type": [ "number", "null" ], "description": "Percentage of traffic from Asia Pacific" }, "emeaPercent": { "type": [ "number", "null" ], "description": "Percentage of traffic from EMEA" } }, "additionalProperties": true }, { "type": "null" } ], "description": "Geographic distribution of company's web traffic (may be null for some companies)" }, "technologyServices": { "type": "array", "items": { "type": "object", "properties": { "serviceName": { "type": "string", "description": "Name of the technology service category" }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "vendorName": { "type": "string", "description": "Name of the vendor" }, "vendorLogo": { "type": "string", "description": "Vendor logo URL (omitted when projected away via fields)" }, "firstSeen": { "type": [ "string", "null" ], "description": "Date when vendor was first detected (may be null; omitted when projected away)" } }, "required": [ "vendorName" ], "additionalProperties": true } } }, "required": [ "serviceName", "vendors" ], "additionalProperties": true }, "description": "Technology services and vendors used by the company" } }, "required": [ "company", "trafficDistribution", "technologyServices" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_contracts", "description": "Retrieve a company's known contract intelligence — vendor relationships, deal values, contract status/durations, service-line breakdowns, renewal timing, and contractHolder (the entity holding each contract). Trigger on questions like \"who does have contracts with?\", \"what are 's outsourcing deals and their values?\", or \"when are 's contracts up for renewal?\". Provide a company domain (e.g. \"salesforce.com\") OR an HG Insights company ID (hg_id); if both are given, hg_id wins. Domain lookups roll up contracts held by subsidiaries across the corporate family (matching the HG app); hg_id lookups return that one entity only.\n\nSCOPE: returns ICT outsourced contracts — typically large managed-services/IT-outsourcing deals brokered by Global System Integrators like Accenture, IBM, or Cognizant, sourced from publicly announced deals (not comprehensive). It is NOT individual product contracts (e.g. a VMware ELA or NetApp agreement), reseller relationships, or vendor renewal/expiration dates.\n\nUse this when you want a company's outsourcing/GSI contract footprint and renewal opportunities; pair it with company_firmographic, company_technographic, and company_spend for full account context. Do NOT use this to browse U.S. federal award records across many recipients — use search_federal_contracts (keyword/agency/NAICS search) instead; company_gov_opportunities and company_gov_relationships cover a company's government pipeline and agency ties. To fold this one company's federal awards INTO these results, set includeFederalContracts=true (requires the datagov / SAM.gov integration): the response adds USAspending.gov awards (awarding agency, contract type, NAICS/PSC codes, set-aside type) plus SAM.gov entity registration (UEI, CAGE code, business types).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company domain to look up contracts for, e.g. \"salesforce.com\". Provide either companyDomain or hg_id. Domain lookups roll up subsidiary contracts across the corporate family. Protocol prefixes (http://, https://), a leading \"www.\", and trailing paths/queries/fragments are stripped automatically and case is normalized, so a full URL is accepted." }, "hg_id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG Insights company ID (32 hex/alphanumeric characters), typically taken from a prior search_companies or company_firmographic result. When provided it overrides companyDomain and returns contracts for that exact entity only (no subsidiary roll-up)." }, "status": { "type": "string", "enum": [ "active", "churned", "all" ], "default": "all", "description": "Filter by contract status: \"active\" (currently in effect), \"churned\" (expired/ended), or \"all\" (default, both)." }, "vendorName": { "type": "string", "description": "Case-insensitive partial match on the counterparty vendor/GSI name, e.g. \"Accenture\" or \"IBM\". Omit to return all vendors." }, "minDealValue": { "type": "number", "description": "Only return contracts whose total deal value is at least this many USD, e.g. 1000000 for $1M+." }, "maxDealValue": { "type": "number", "description": "Only return contracts whose total deal value is at most this many USD." }, "endDateBefore": { "type": "string", "description": "Only return contracts ending on or before this date (ISO \"YYYY-MM-DD\", e.g. \"2025-12-31\"). Useful for finding near-term renewal opportunities." }, "endDateAfter": { "type": "string", "description": "Only return contracts ending on or after this date (ISO \"YYYY-MM-DD\", e.g. \"2025-01-01\")." }, "limit": { "type": "number", "default": 50, "description": "Maximum number of contracts to return, sorted by deal value descending (default 50, capped at 100)." }, "includeFederalContracts": { "type": "boolean", "default": false, "description": "When true, also fetch this company's U.S. federal government awards from USAspending.gov and merge them into the contracts list (each tagged source=\"usaspending\"). Requires the datagov integration (a SAM.gov API key) to be configured; the call fails with a setup message if it is not. The response then adds SAM.gov entity registration (UEI, CAGE code, business types) and federalDataStatus metadata. Defaults to false (HG contracts only)." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "description": "The company domain that was queried" }, "organizationId": { "type": "string", "description": "The HG Insights organization identifier" }, "companyName": { "type": "string", "description": "The company name" }, "contractCount": { "type": "number", "description": "Number of contracts returned" }, "totalContractValue": { "type": "string", "description": "Total contract value formatted as currency" }, "totalContractValueAmount": { "type": "number", "description": "Total contract value as numeric amount" }, "contracts": { "type": "array", "items": { "type": "object", "properties": { "contractId": { "type": "string" }, "vendorName": { "type": "string" }, "vendorDomain": { "type": "string" }, "productName": { "type": "string" }, "productCategory": { "type": "string" }, "headline": { "type": "string" }, "status": { "type": "string" }, "dealValue": { "type": "string", "description": "Deal value formatted as currency" }, "dealValueAmount": { "type": "number" }, "annualValue": { "type": "string" }, "annualValueAmount": { "type": "number" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "contractTermMonths": { "type": "number" }, "renewalLikelihood": { "type": "number", "description": "0-100 score" }, "daysUntilRenewal": { "type": "number" }, "churnRiskScore": { "type": "number", "description": "0-100 score" }, "contractHolder": { "type": "string", "description": "Name of the entity holding the contract (populated for subsidiary contracts)" }, "country": { "type": "string" }, "source": { "type": "string", "enum": [ "hg", "usaspending" ], "description": "Data source (present when includeFederalContracts=true)" }, "federalData": { "type": "object", "properties": { "awardId": { "type": "string" }, "awardingAgency": { "type": "string" }, "awardingSubAgency": { "type": "string" }, "fundingAgency": { "type": "string" }, "contractType": { "type": "string" }, "setAsideType": { "type": "string" }, "naicsCode": { "type": "string" }, "naicsDescription": { "type": "string" }, "pscCode": { "type": "string" }, "pscDescription": { "type": "string" }, "placeOfPerformance": { "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": [ "contractId", "vendorName", "status", "dealValue", "dealValueAmount" ], "additionalProperties": true }, "description": "List of contracts (HG and optionally federal)" }, "hasMore": { "type": "boolean", "description": "Whether there are more contracts available" }, "samEntity": { "type": "object", "properties": { "uei": { "type": "string", "description": "Unique Entity Identifier" }, "cageCode": { "type": "string", "description": "Commercial and Government Entity code" }, "legalBusinessName": { "type": "string" }, "registrationStatus": { "type": "string", "enum": [ "Active", "Inactive" ] }, "businessTypes": { "type": "array", "items": { "type": "string" }, "description": "e.g., Large Business, 8(a), HUBZone" }, "naicsCodes": { "type": "array", "items": { "type": "string" } }, "pscCodes": { "type": "array", "items": { "type": "string" } }, "samRegistrationDate": { "type": "string" }, "samExpirationDate": { "type": "string" } }, "additionalProperties": true, "description": "SAM.gov entity registration data (present when includeFederalContracts=true and entity is resolved)" }, "federalDataStatus": { "type": "object", "properties": { "resolved": { "type": "boolean", "description": "Whether the federal data fetch completed" }, "samEntityFound": { "type": "boolean", "description": "Whether a SAM.gov entity was found" }, "contractsFound": { "type": "number", "description": "Number of federal contracts found" }, "dataAsOf": { "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 includeFederalContracts=true)" } }, "required": [ "companyDomain", "organizationId", "companyName", "contractCount", "totalContractValue", "totalContractValueAmount", "contracts", "hasMore" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_fai", "description": "Functional Area Intelligence (FAI): shows WHICH DEPARTMENTS inside one company use specific products, with per-department usage share, signal strength, decision-maker/influencer flags, roles, and signal location. Use this when you already know (or can name) the products and want the departmental/functional-area breakdown of who uses them at a single company — e.g. \"which teams at Cisco use Salesforce?\" or account mapping to find the department to sell into. Do NOT use this when you want the company's whole-company technology installs (use company_technographic — it also returns the productId values to feed back in here), or when you need to resolve or list valid FAI department/role IDs and names (use list_fai_departments). Identify the company with a domain (e.g., \"cisco.com\") or an HG Insights company ID (hg_id); if both are given, hg_id wins. You MUST supply at least one product via productIds (PREFERRED — numeric IDs from company_technographic, exact and deterministic) or products (FALLBACK — names, fuzzy-matched).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company to analyze, as a website domain (e.g., \"cisco.com\"). Either companyDomain or hg_id is required (hg_id wins if both are given). 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) identifying the company; overrides companyDomain when provided. Obtain it from a prior search_companies or company_firmographic result. Prefer this over a domain when disambiguating subsidiaries from their parent." }, "products": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 20, "description": "FALLBACK product selector: product names to fuzzy-match (e.g., [\"snowflake\", \"microsoft office\"]), max 20. Use only when you lack exact IDs; prefer productIds. Unrecognized names fail loudly with \"Unknown product(s): ...\". Ignored when productIds is also supplied." }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 20, "description": "PREFERRED product selector: HG Insights numeric product IDs (max 20) for exact, deterministic lookup with no fuzzy matching. Get them from the productId field of a company_technographic result for this same company. Takes precedence over products when both are given." }, "provider": { "type": "string", "default": "auto", "description": "Data source provider. Leave as \"auto\" (default) to auto-select the best configured provider; only override with a specific key like \"hginsights\" if you must pin the source." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of enriched.records entries to return (default: 50, max: 200). Ignored when full=true." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "departmentName", "departmentId", "productName", "productId", "departmentUsageShare", "departmentSignalStrength", "roleName", "roleId", "roleSignalShare", "roleUsageShare", "signalCountryName", "signalStateName", "signalCityName", "isDecisionMaker", "isInfluencer", "totalCount", "lastVerifiedAt" ] }, "description": "Project each enriched.records row to this subset of fields. departmentName, departmentId, productName, and productId are always included regardless of this list (they are required to correlate rows). Ignored when full=true." }, "full": { "type": "boolean", "default": false, "description": "When true, return the full payload with no limit and no field projection. Default: false (limit and fields apply, keeping unconstrained payloads under 40KB)." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Unique company identifier" }, "companyDomain": { "type": "string", "description": "The company domain that was analyzed" }, "departments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the department" }, "detectedProducts": { "type": "array", "items": { "type": "string" }, "description": "Product names detected in this department" } }, "required": [ "name", "detectedProducts" ], "additionalProperties": true }, "description": "Departments with detected products" }, "enriched": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "departmentName": { "type": "string", "description": "Department name" }, "departmentId": { "type": "string", "description": "Department identifier" }, "productName": { "type": "string", "description": "Product name" }, "productId": { "type": "number", "description": "Product identifier" }, "departmentUsageShare": { "type": "number", "description": "Department usage share" }, "departmentSignalStrength": { "type": "number", "description": "Department signal strength" }, "roleName": { "type": [ "string", "null" ], "description": "Role name" }, "roleId": { "type": [ "string", "null" ], "description": "Role identifier" }, "roleSignalShare": { "type": [ "number", "null" ], "description": "Role signal share" }, "roleUsageShare": { "type": [ "number", "null" ], "description": "Role usage share" }, "signalCountryName": { "type": "string", "description": "Country where signal was detected" }, "signalStateName": { "type": "string", "description": "State/province where signal was detected" }, "signalCityName": { "type": "string", "description": "City where signal was detected" }, "isDecisionMaker": { "type": "boolean", "description": "Whether decision makers are present" }, "isInfluencer": { "type": "boolean", "description": "Whether influencers are present" }, "totalCount": { "type": "number", "description": "Total record count in source data" }, "lastVerifiedAt": { "type": "string", "description": "Last verification timestamp" } }, "required": [ "departmentName", "departmentId", "productName", "productId" ], "additionalProperties": true }, "description": "Raw-enriched records from HG Insights FAI response" } }, "required": [ "records" ], "additionalProperties": true, "description": "Optional enriched FAI records with location and decision-maker signals" } }, "required": [ "companyId", "companyDomain", "departments" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_firmographic", "description": "Call this when a user asks about a company's firmographics — name, location, industry, employee/revenue size, corporate hierarchy, or global HQ. Use this (not company_research) for firmographic-only questions — it is faster and returns a smaller payload than a full profile.\n\nReturns: name, industry_name, employees_total/employees_band, revenue_total/revenue_band, city/state/country, NAICS/SIC codes, Fortune 500 / Forbes 2000 rank, it_spend, company_level, and the corporate-parent / global_hq_* hierarchy fields.\n\ncompany_level values: \"Group HQ\" (ultimate parent — global_hq_* fields are omitted), \"Corporate Parent\" (intermediate parent — global_hq_* carries the ultimate parent), or subsidiary. E.g. linkedin.com → company_level=\"Corporate Parent\", global_hq_domain=\"microsoft.com\". Chain global_hq_id to reach the ultimate parent (same as companyId for a Group HQ).\n\ncompanyId is the queried entity's HG company id (32 uppercase hex chars) for chaining downstream.\n\nNo-match detection: the API always returns found:true. When companyId is \"\" (empty string) and firmographics is an empty object {}, no company was matched — do NOT rely on found as a sentinel.\n\nWhen the org has a Snowflake integration configured, its own account record is attached as customerData.\n\nProvide companyDomain or hg_id; hg_id takes precedence.\n\nDo NOT use this when: the firmographic data is already in context (e.g. from a prior company_research call); you need the full multi-level ownership tree (use get_company_hierarchy); you need a full multi-signal profile (technographic + intent + spend) — use company_research; or you are filtering/building a list of many companies — use search_companies.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to look up (e.g., 'cisco.com'). Either companyDomain 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 uppercase hex characters; schema accepts 31-32 alphanumeric chars). When provided, companyDomain is silently ignored. Obtain from a previous search_companies result." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "HG Insights company identifier (hex). Empty string when the company was not found." }, "companyDomain": { "type": "string", "description": "The company domain that was queried (or the domain returned by the provider)." }, "found": { "type": "boolean", "description": "True when a company matched the query; false when not found (companyId is empty and message explains)." }, "message": { "type": "string", "description": "Present only when found is false — a human-readable explanation of why no company matched." }, "firmographics": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name." }, "domain": { "type": "string", "description": "Company domain." }, "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", "description": "HQ ISO country code." }, "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", "description": "Corporate parent hex id." }, "corporate_parent_name": { "type": "string", "description": "Corporate parent name." }, "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 companyId. " }, "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 companyId) to reach the ultimate parent." }, "customerData": { "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": [ "companyId", "companyDomain", "found", "firmographics" ], "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 where ONE named company (given by domain) is the likely incumbent or a probable bidder. Trigger on questions like \"what government RFPs should Booz Allen bid on?\" or \"which open opportunities is this contractor positioned to win?\". 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. Use this when you have a specific company and want THEIR bid pipeline. Do NOT use this when: browsing opportunities across all vendors by keyword/agency/NAICS with no target company (use search_gov_opportunities); mapping a company's past/current award history and agency relationships rather than open bids (use company_gov_relationships); listing a company's commercial or federal contracts already held (use company_contracts); or searching awarded federal contracts across recipients (use search_federal_contracts).", "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": "integer", "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": "integer", "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" } }, "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_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 (by domain). Use this when the question is about a TREND over time — 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?' Do NOT use this when you want 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 = the number of days the product was detected that month (null = no detection that month). current_intensity is a separate aggregate integer from global install data and is NOT on the 1-31 daily scale — use intensity_momentum (positive = growing, negative = declining; magnitude is meaningful) for trend analysis rather than comparing raw intensity values. IMPORTANT: The most-recent data point is typically null because the current month is incomplete; the penultimate point may also be partial if queried early in a new month — treat it as provisional. BEFORE filtering, resolve exact canonical names and numeric IDs first — get_vendor_information for vendor names, get_product_category for category names, product_search_and_enrich for product names and numeric productIds. Filter values that don't match exact canonical names return products: [] with HTTP 200 and 0 credits — indistinguishable from a genuine no-data result. Unlike company_technographic, this tool emits a warning field whenever filters were provided but nothing matched, explaining the miss and how to resolve it. Credit cost: 3 per product returned; 0 on empty results.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to look up (e.g., 'cisco.com'). Required. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized." }, "products": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50, "description": "Optional. Restrict the series to specific products by name (e.g., ['Snowflake Platform', 'Databricks']). Values must be EXACT canonical product names — a near-match ('Snowflake' vs 'Snowflake Platform') silently returns no products. Resolve names with product_search_and_enrich first, or prefer productIds. Omit to return the company's top products by intensity." }, "productIds": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50, "description": "Optional. Restrict the series to specific products by ID. Must be numeric HG product IDs (e.g. '26434') — slug-style IDs silently return nothing. The most reliable filter: obtain the numeric ID from product_search_and_enrich, then pass it here instead of a product name." }, "vendors": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50, "description": "Optional. Restrict the series to products from specific vendors. Values must be EXACT canonical vendor names (e.g. 'Microsoft Corporation', not 'Microsoft') — a short/informal name silently returns no products. Resolve the canonical name with get_vendor_information before filtering." }, "categories": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50, "description": "Optional. Restrict the series to products in specific categories. Values must be EXACT canonical category names (e.g. 'Infrastructure-as-a-Service (IaaS)', not 'Cloud Infrastructure') — a paraphrase silently returns no products. Resolve the canonical name with get_product_category before filtering." }, "timeRange": { "type": "string", "enum": [ "last_6_months", "last_12_months", "last_24_months", "last_36_months" ], "default": "last_24_months", "description": "How far back the monthly series extends. Options: last_6_months, last_12_months, last_24_months, last_36_months. Default: last_24_months. Pick a longer range for slow-moving adoption/churn trends, a shorter one for recent momentum. 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)." }, "maxProducts": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of products to return (1-50, default 10)." } }, "required": [ "companyDomain" ], "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 domain match (0.0-1.0)" } }, "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)" }, "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 a broad overview of intent signals for a single company — returns the top topics by score (0–100, where 100 = strongest signal) with intent levels (High/Medium/Low), buyer journey stages, and context dispositions (Displacement/Expansion/Complementary/Whitespace) from HG proprietary data. TrustRadius activity events (raw page views with evidence URLs) appear in the activities array.\n\nUse this when: you want the full ranked landscape of what a company is researching (top-N topics by score), competitive signals (set vendor_name + context_type=Displacement), or filtering by journey stage or intent level.\n\nDo NOT use this when:\n- You want companies researching a specific topic → use intent_category with topic_name instead.\n- You need to discover valid topic names/IDs → use list_intent_topics first.\n- You set group_by=company with signal — this activates activity search mode which ignores companyDomain and returns cross-company aggregates; only use that combination if you want a ranked list of companies (not a per-company lookup).\n- You set source=trustradius expecting scored topic signals — TrustRadius topics currently return score=0; meaningful TR data is in the activities array only.\n\nScores are bounded 0–100. intent_level thresholds: High ≥ 85, Medium 65–84, Low < 65 (approximate).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company domain to look up intent signals for (e.g., \"cisco.com\", \"salesforce.com\"). Either companyDomain 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 alphanumeric characters). When provided, this overrides companyDomain. Obtain from a previous company_search result." }, "vendor_name": { "type": "string", "maxLength": 200, "description": "Filter by vendor name for competitive/displacement analysis (e.g., \"Snowflake, Inc.\"). Pair with context_type=Displacement to surface companies moving off that vendor; shows displacement signals and context dispositions." }, "product_name": { "type": "string", "maxLength": 200, "description": "Filter by product name (e.g., \"Salesforce Sales Cloud\"). Scopes results to intent signals related to this product." }, "intent_level": { "type": "string", "enum": [ "High", "Medium", "Low" ], "description": "Filter by intent level." }, "buyers_journey": { "type": "string", "maxLength": 100, "description": "Filter by buyer journey stage (e.g., \"Researching\", \"Evaluating\", \"Purchasing\")." }, "context_type": { "type": "string", "maxLength": 100, "description": "Filter by context type (e.g., \"Whitespace\", \"Expansion\", \"Displacement\", \"Complementary\")." }, "source": { "type": "string", "enum": [ "hg", "trustradius" ], "description": "Filter by data source. Omit to include both HG and TrustRadius signals. Note: source=\"trustradius\" topic scores currently return 0 — meaningful TrustRadius data is in the activities array, not scored topics; use source=\"hg\" for scored topic signals." }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date in YYYY-MM-DD format. Defaults to 30 days ago." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date in YYYY-MM-DD format. Defaults to today." }, "signal": { "type": "string", "enum": [ "comparison", "pricing", "research", "evaluation" ], "description": "Filter by signal category. Activates activity search mode. Values: comparison (view Comparison, click Comparisons), pricing (view Product Pricing), research (view Product Listing, view Category), evaluation (view Review, view Reviews and Ratings)." }, "products": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 10, "description": "Array of product names with AND logic — returns only companies/events matching ALL products (e.g., [\"Databricks\", \"Snowflake Platform\"]). Activates activity search mode. Distinct from product_name which filters the intent endpoint." }, "filters": { "type": "object", "properties": { "employees_range": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Employee range filter (e.g., \"10,000+\", \"1,001-5,000\", \"201-500\")." }, "country_codes": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO country code filter (e.g., [\"US\", \"GB\"])." }, "category_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by product category name." } }, "additionalProperties": false, "description": "Firmographic and category filters for activity search mode." }, "group_by": { "type": "string", "enum": [ "company" ], "description": "\"company\" for aggregated company data, omit for raw individual events with evidence URLs. Activates activity search mode. Note: group_by=\"company\" combined with signal switches to cross-company activity search — companyDomain is ignored and the response follows a different schema (ranked companies, not a per-company lookup)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Pagination limit (1-200). Used in both intent and activity search modes." }, "offset": { "type": "integer", "minimum": 0, "description": "Pagination offset (default 0). Used in both intent and activity search modes." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "company_id": { "type": "string" }, "company_name": { "type": "string" }, "domain": { "type": "string" } }, "additionalProperties": true, "description": "Company identification details (intent mode)" }, "window": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": true, "description": "Date range for the intent query (intent mode)" }, "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 arrays." }, "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": { "total_active_topics": { "type": "number" }, "high_intent_topics": { "type": "number" }, "top_context_types": { "type": "object", "additionalProperties": {}, "description": "Context type counts" }, "sources": { "type": "object", "additionalProperties": {}, "description": "Signal counts by source" }, "latest_signal_date": { "type": [ "string", "null" ] } }, "required": [ "total_active_topics", "high_intent_topics" ], "additionalProperties": true, "description": "Aggregated intent signal summary (intent mode)" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": "string" }, "score": { "type": "number", "description": "Intent score (0-100)" }, "intent_level": { "type": [ "string", "null" ] }, "buyers_journey": { "type": [ "string", "null" ] }, "context_types": { "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" } }, "required": [ "topic_name", "score", "source" ], "additionalProperties": true }, "description": "Per-topic intent details (intent mode)" }, "activities": { "type": "array", "items": { "type": "object", "properties": { "activity_type": { "type": "string" }, "activity_label": { "type": "string" }, "products": { "type": "array", "items": { "type": "string" } }, "vendors": { "type": "array", "items": { "type": "string" } }, "activity_date": { "type": "string" }, "daily_views": { "type": "number" }, "intent_signal_url": { "type": "string" } }, "additionalProperties": true }, "description": "TrustRadius buyer activities (intent mode)" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string" }, "company_name": { "type": "string" }, "domain": { "type": "string" }, "employees_range": { "type": "string" }, "event_count": { "type": "number" }, "total_views": { "type": "number" }, "last_activity_date": { "type": "string" }, "products_compared": { "type": "array", "items": { "type": "string" } }, "vendors": { "type": "array", "items": { "type": "string" } }, "signals": { "type": "array", "items": { "type": "string" } }, "activity_labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "company_id", "company_name", "domain" ], "additionalProperties": true }, "description": "Companies matching the activity search query (returned when group_by='company')" }, "events": { "type": "array", "items": { "type": "object", "properties": { "activity_date": { "type": "string" }, "activity_type": { "type": "string" }, "activity_label": { "type": "string" }, "signal": { "type": "string" }, "daily_views": { "type": "number" }, "product_names": { "type": "array", "items": { "type": "string" } }, "vendor_names": { "type": "array", "items": { "type": "string" } }, "category_name_trees": { "type": "array", "items": { "type": "string" } }, "intent_signal_url": { "type": "string" }, "company_id": { "type": "string" }, "company_name": { "type": "string" }, "domain": { "type": "string" } }, "additionalProperties": true }, "description": "Individual activity events with evidence URLs (returned when group_by is omitted)" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "has_more": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "has_more" ], "additionalProperties": true, "description": "Pagination details for result set" } }, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_operating_signals", "description": "Get a single-company operational profile by rolling up HG mentions and AI-maturity data into ten labeled \"stage\" attributes for one company. Returns two groups: mentions (work_model, cloud_posture, esg_commitment, iot_posture, network_modernization, automation_stage) and genai_maturity (ai_trajectory, cloud_depth, genai_readiness, intent_adoption_gap). Each attribute carries a categorical stage (e.g. cloud_posture=\"private-first\", ai_trajectory=\"ai-leader-growing\"), a per-signal breakdown, and an intensity number — note mentions intensity is an UNBOUNDED sum of detection volume (often in the thousands), while genai_maturity intensity is a bounded 0–100 score. Use this when you want a fast qualitative read of how one company operates and where it sits on its AI/cloud/automation journey. Do NOT use this to browse or rank many companies (use search_companies), for raw technology installs or intent scores (use company_technographic or company_intent), or for just the AI-maturity numbers without the operating stages (use company_ai_maturity). Provide a company domain (e.g. \"cisco.com\") or an HG Insights company ID (hg_id).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company website domain to profile (e.g. \"cisco.com\"). Provide either companyDomain or hg_id — hg_id wins if both are given. 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 when you have already resolved the company and want an exact, domain-independent lookup. Overrides companyDomain when both are supplied." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "company_name": { "type": [ "string", "null" ], "description": "Company name from HG Insights" }, "company_domain": { "type": "string", "description": "Company domain queried" }, "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_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_research", "description": "EXPENSIVE — full-profile dashboard, ~10 credits per call. Builds one multi-signal company profile in a single call: firmographic (industry, size, revenue, HQ, rankings) + technographic (installed tech stack) + IT spend + cloud spend + intent signals + federal contracts + operating signals, aggregated into an interactive dashboard.\n\nUse this when the user explicitly asks for a broad company overview, briefing, or account snapshot spanning MULTIPLE data domains at once — the whole point is getting the complete picture in one call.\n\nDo NOT use this when you only need ONE signal — for any narrow question, call that individual tool instead: company_firmographic (industry/size/revenue), company_technographic (tech stack), company_intent (buying signals), or company_spend (IT spend). The specific tool is far faster, returns a smaller payload, and costs a fraction of this. Do not call this repeatedly for the same company.\n\nProvide a company domain (e.g., \"cisco.com\") or an HG Insights company ID (hg_id). All sections default to ON and you are billed for every section returned — pass include* booleans (false) to drop sections you do not need and pay less. Pass full: true to bypass per-section row caps (defaults trim spend/cloudSpend/intent so an unconstrained call stays under 40KB).", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to look up (e.g., \"cisco.com\"). At least one of companyDomain or hg_id must be provided. 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, e.g. from a company_search result). When provided, this overrides companyDomain. At least one of companyDomain or hg_id must be provided." }, "includeFirmographic": { "type": "boolean", "default": true, "description": "Include firmographic data — industry, size, revenue, HQ, rankings (default: true). Cannot be disabled: firmographic is the mandatory header source and is always fetched regardless of this flag." }, "includeTechnographic": { "type": "boolean", "default": true, "description": "Include the installed technology stack, top 20 products by intensity (default: true). Set false to drop this section and save credits when the tech stack is not needed." }, "includeSpend": { "type": "boolean", "default": true, "description": "Include IT spend broken down by category (default: true). Set false to skip the fetch and save credits." }, "includeCloudSpend": { "type": "boolean", "default": true, "description": "Include cloud spend by service and vendor (default: true). Set false to skip the fetch and save credits." }, "includeIntent": { "type": "boolean", "default": true, "description": "Include intent topics and activities (buying signals) (default: true). Set false to skip the fetch and save credits." }, "includeContracts": { "type": "boolean", "default": true, "description": "Include federal (government) contract data (default: true). Set false to skip the fetch and save credits." }, "includeOperatingSignals": { "type": "boolean", "default": true, "description": "Include operating signals (e.g. work model, operational posture) (default: true). Set false to skip the fetch and save credits." }, "full": { "type": "boolean", "default": false, "description": "When true, bypass the per-section row caps applied to technographic, spend, cloudSpend, intent, and contracts so every row is returned. Default: false (caps applied so a no-arg call stays under Claude's ~40KB inline cap). Only set true when the caller explicitly needs the complete, untruncated dataset." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "header": { "type": "object", "properties": { "companyName": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "string", "number", "null" ] }, "revenue": { "type": [ "string", "number", "null" ] }, "location": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "website": { "type": [ "string", "null" ] }, "foundedYear": { "type": [ "number", "null" ] }, "companyType": { "type": [ "string", "null" ] } }, "additionalProperties": true, "description": "Company header information" }, "keyMetrics": { "type": "object", "properties": { "itSpend": { "type": [ "number", "null" ] }, "fortune500Rank": { "type": [ "number", "null" ] }, "forbes2000Rank": { "type": [ "number", "null" ] }, "topTechCategories": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true, "description": "Key business metrics" }, "firmographic": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Firmographic data" }, "technographic": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Technographic data (top 10 products by default; bypassed when full=true)" }, "spend": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "IT spend data (top 10 categories by default; bypassed when full=true)" }, "cloudSpend": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Cloud spend data (top 5 services x top 10 vendors per service by default; bypassed when full=true)" }, "intent": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Intent signals (top 10 topics/activities by default; bypassed when full=true)" }, "contracts": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Contract data (50 rows by default; 100 when full=true)" }, "operatingSignals": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Operating signals" } }, "required": [ "header", "keyMetrics" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true, "title": "Company Research" } }, { "name": "company_spend", "description": "Estimate a company's annual IT spend in USD, broken down by spend category and country, from HG Insights modeled spend data. Values are HG's modeled dollar estimates (not billed/actual invoices) — e.g. Cisco returns ~$25.9B total, with per-category figures like \"Total IT\", \"Total External IT\", \"Services\", and \"Software\", each also split by country. Use this when you need budget/deal-sizing numbers: how much a company spends on IT overall or within a category (Security, Software, Cloud, Services), or the geographic distribution of that spend. Identify the company by domain (e.g., \"cisco.com\") or HG Insights company ID (hg_id); if both are given, hg_id wins. Filter to one category with spendCategory (fuzzy-matched). Do NOT use this when you want to know WHICH cloud/CDN/hosting vendors a company uses or when they adopted them — that is company_cloud_spend (vendor detail, no dollars). Do NOT use this to list installed on-prem software/products (CRM, databases, security tools) — that is company_technographic. Returns totalSpend (formatted like \"$25,929,336,774\") plus totalSpendAmount (numeric); \"N/A\"/null appears where HG has no value (see unknownRowCount). By default the top 50 categories (sorted by spend desc) are returned; raise limit (max 200), project rows with fields, or set full=true for everything.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company website domain to estimate IT spend for (e.g., \"cisco.com\"). Either companyDomain or hg_id is required. Protocol prefixes (http://, https://), a 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 (31-32 alphanumeric characters, e.g., \"0FF69D9F596504A1FF4FF5B16FF\"), typically from a prior search_companies / company_firmographic result. Takes precedence over companyDomain when both are supplied. Use this instead of a domain to pin an exact company entity." }, "spendCategory": { "type": "string", "description": "Restrict results to a single spend category, fuzzy-matched against HG's category names (e.g., \"Security\", \"Software\", \"Cloud\", \"Services\"). Omit to return every category (top ones by spend, subject to limit). No match raises an error rather than returning all categories." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of spendByCategory entries to return (default: 50, max: 200). Categories are sorted by total spend (descending) before truncation. Ignored when full=true." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "categoryId", "categoryName", "categoryTree", "totalSpend", "totalSpendAmount", "unknownCountryCount", "spendByCountry" ] }, "description": "Project each spendByCategory row to this subset of fields. categoryId, categoryName, totalSpend, totalSpendAmount, and unknownCountryCount are always included regardless of this list (they are required by the output schema). Useful for trimming large categoryTree or spendByCountry payloads. Ignored when full=true." }, "full": { "type": "boolean", "default": false, "description": "When true, return the full payload with no limit and no field projection. Default: false (limit and fields apply, keeping unconstrained payloads under 40KB)." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "The HGInsights company identifier" }, "companyDomain": { "type": "string", "description": "The company domain that was queried" }, "totalSpend": { "type": "string", "description": "Total IT spend formatted as currency (e.g., '$1,234,567'), or 'N/A' when every row in the response has unknown spend." }, "totalSpendAmount": { "type": [ "number", "null" ], "description": "Total IT spend as a numeric value. Null when every row has unknown spend; otherwise the sum of all rows whose `spendAmount` was not null. See `unknownRowCount` for how many rows were skipped." }, "unknownRowCount": { "type": "number", "description": "Number of country rows across all categories whose `spendAmount` was null (HG didn't have a value). Use this to gauge how much of the response is partial." }, "spendByCategory": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "string", "description": "Category identifier" }, "categoryName": { "type": "string", "description": "Category display name" }, "categoryTree": { "type": "array", "items": { "type": "string" }, "description": "Hierarchical category path" }, "totalSpend": { "type": "string", "description": "Category spend formatted as currency, or 'N/A' when every row in the category has unknown spend" }, "totalSpendAmount": { "type": [ "number", "null" ], "description": "Category spend as numeric value. Null when every row in the category has unknown spend; otherwise the sum of known rows." }, "unknownCountryCount": { "type": "number", "description": "Number of country rows in this category whose `spendAmount` was null." }, "spendByCountry": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string", "description": "ISO country code" }, "countryName": { "type": "string", "description": "Country name" }, "region": { "type": "string", "description": "Geographic region" }, "spend": { "type": "string", "description": "Spend formatted as currency, or 'N/A' when upstream spend is null" }, "spendAmount": { "type": [ "number", "null" ], "description": "Spend as numeric value. Null when upstream HG data is unknown for this row (e.g. certain subsidiary/country combinations)." } }, "required": [ "countryCode", "countryName", "spend", "spendAmount" ], "additionalProperties": true }, "description": "Geographic breakdown of spend" } }, "required": [ "categoryId", "categoryName", "totalSpend", "totalSpendAmount", "unknownCountryCount" ], "additionalProperties": true }, "description": "Breakdown of spend by category" }, "categoriesFound": { "type": "number", "description": "Number of spend categories found" }, "countriesFound": { "type": "number", "description": "Number of countries with spend data" } }, "required": [ "companyId", "companyDomain", "totalSpend", "totalSpendAmount", "unknownRowCount", "spendByCategory", "categoriesFound", "countriesFound" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "company_technographic", "description": "Get the current installed technology stack for a company. Returns products with productId (numeric), vendor, usage intensity (higher = stronger signal), product locations count, and first/last verified dates.\n\nUse this when: user asks \"what technology does [company] use?\", \"does [company] use Salesforce/AWS?\", \"what's [company]'s tech stack?\", or needs a current-install snapshot.\n\nDo NOT use this when:\n- User wants usage trends over time → use company_install_time_series\n- User wants which department/team uses a product → use company_fai\n- User wants spend estimates → use company_spend\n\nBEFORE filtering — resolve IDs first:\n- By vendor/product: call get_vendor_information(vendorName: '') to get vendorId, then pass here. Skipping causes misses (Snowflake is under vendor 'Snowflake Inc.', not just the string 'Snowflake').\n- By category: call get_product_category(categoryName: '') to get the exact category_name, then pass here. Categories use case-insensitive SUBSTRING matching — \"CRM\" matches both \"Customer Relationship Management Applications\" and \"Customer Relationship Management (CRM) BPO\". Empty results on a category filter do NOT include a warning field; inspect the response's categories[] array to confirm which categories matched.\n- For full unfiltered stack: call directly with no filters.\n\nproductId values in results can be passed directly to company_fai or company_install_time_series for deeper analysis. Default limit: 50; max: 500 (use filters instead of high maxResults). Sort by intensity (default) or date (most recently verified first). Empty results mean no data found — do NOT say the tool lacks functionality. Provide companyDomain (e.g., \"cisco.com\") or hg_id; hg_id takes precedence when both provided.", "inputSchema": { "type": "object", "properties": { "companyDomain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The company domain to lookup (e.g., 'example.com'). Either companyDomain 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 alphanumeric characters). When provided, this overrides companyDomain. Obtain from a previous company_search result." }, "categories": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Filter by technology category names (case-insensitive SUBSTRING match on category_name, not fuzzy). Call get_product_category first to find the exact category_name to pass here. Leave empty for all categories. WARNING: broad category filters can include peripheral products (upstream data-quality issue) — prefer vendorIds/productIds for precision when checking specific vendors." }, "productIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter by exact HG Insights product IDs (passed directly to API). Get IDs from get_vendor_information or from previous company_technographic results' productId field." }, "vendorIds": { "type": "array", "items": { "type": "integer" }, "description": "Filter by exact HG Insights vendor IDs (integers). Call `get_vendor_information(vendorName: '')` first to resolve the integer vendor_id, then pass it here. You can also reuse a vendor_id from a previous company_technographic result's `vendorId` field." }, "sort": { "type": "string", "enum": [ "intensity", "date" ], "default": "intensity", "description": "Sort results by usage intensity (high to low) or last verified date (most recent first)." }, "maxResults": { "type": "number", "minimum": 1, "maximum": 500, "default": 50, "description": "Maximum number of results to return (1-500, default 50). Use 'categories', 'productIds', or 'vendorIds' to filter for focused results instead of requesting large result sets." }, "provider": { "type": "string", "default": "auto", "description": "Data provider to use. Use 'auto' for automatic selection or specify provider name." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Unique company identifier" }, "companyDomain": { "type": "string", "description": "The company domain that was queried" }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "number", "description": "Unique product identifier" }, "productName": { "type": "string", "description": "Name of the technology product" }, "vendorName": { "type": "string", "description": "Name of the technology vendor" }, "productAttributes": { "type": "array", "items": { "type": "string" }, "description": "Product attributes/categories" }, "productLocations": { "type": "number", "description": "Number of product locations" }, "categoryId": { "type": "string", "description": "Category identifier" }, "categoryName": { "type": "string", "description": "Technology category name" }, "categoryNameTree": { "type": "array", "items": { "type": "string" }, "description": "Category hierarchy" }, "firstVerifiedDate": { "type": "string", "description": "Date when technology was first verified" }, "lastVerifiedDate": { "type": "string", "description": "Date when technology usage was last verified" }, "intensity": { "type": "number", "description": "Usage intensity level" }, "productDescription": { "type": "string", "description": "Description of the product" }, "countryCode": { "type": "string", "description": "Country code" }, "installDate": { "type": "string", "description": "Installation date" } }, "required": [ "productName", "vendorName" ], "additionalProperties": true }, "description": "List of technologies/products used by the company" }, "totalCount": { "type": "number", "description": "Total number of technologies found" }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Categories of technologies found" }, "lastUpdated": { "type": "string", "description": "When the data was last updated" }, "_truncation": { "type": "object", "properties": { "truncatedFrom": { "type": "number", "description": "Original number of products before truncation" }, "returnedCount": { "type": "number", "description": "Number of products returned after truncation" }, "note": { "type": "string", "description": "Guidance for retrieving more targeted results" } }, "required": [ "truncatedFrom", "returnedCount", "note" ], "additionalProperties": true, "description": "Present only when results are truncated to keep tool output within context limits." } }, "required": [ "companyId", "companyDomain", "products", "totalCount" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "contact_enrich", "description": "Enrich a KNOWN person: return their email, phone, seniority/title, social profiles, and employment history. Sourced from EXTERNAL contact providers — Apollo and ZoomInfo — NOT the HG Insights data API. Requires an Apollo or ZoomInfo integration; provider is auto-selected from org configuration unless you set `provider`. Use this when you already have a specific contact and want their missing details — pass a contactId from contact_search (most accurate), an email, a LinkedIn URL, or a first+last name with company domain/name. Batch up to 25 people via `contacts` for bulk enrichment. Do NOT use this to DISCOVER people you don't know yet (e.g. \"find the VPs of Marketing at Cisco\") — use contact_search for that, then enrich the best matches by id. USES CREDITS, billed per revealed detail on matched contacts (not per person): 0.2 credits per revealed email + 2 credits per revealed phone. revealPhone is OPT-IN (defaults false) because a phone reveal costs 10x an email — only set it when a phone number is specifically required. No-match calls, and calls revealing neither detail, cost 0. Response metadata.dynamicCreditCost reports the actual charge. Do NOT re-enrich a contact already in context — every call is billed regardless of whether the data changed.", "inputSchema": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Provider contact ID returned by contact_search. Most accurate identifier — resolves an exact person with no matching ambiguity. Use 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." }, "revealEmail": { "type": "boolean", "default": true, "description": "Whether to reveal email addresses (default: true). Billed at 0.2 credits per contact with a revealed email." }, "revealPhone": { "type": "boolean", "default": false, "description": "Whether to reveal phone numbers. OPT-IN and billed separately at 2 credits per contact with a revealed phone — 10x the cost of an email reveal. Defaults to false; only set true when a phone number is specifically required." }, "provider": { "type": "string", "default": "auto", "description": "External contact provider to enrich against. \"auto\" (default) picks the first configured provider; \"apollo\" or \"zoominfo\" force a specific one. Use the same provider that produced any contactId you pass." } }, "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": "Number of credits consumed" }, "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, not company facts. Use this to find contacts at an account (e.g. 'who are the VPs of Marketing at Salesforce', 'find IT decision-makers at Cisco') and identify prospects to reach out to. Do NOT use this when: you already know the specific person and want their email/phone — use contact_enrich; you want company-level firmographics (revenue, size, industry) rather than people — use company_firmographic. PROVIDER DEPENDENCY: results come from an EXTERNAL contact provider — Apollo or ZoomInfo — auto-selected from your org's configured integrations (NOT the HG Insights data API). Coverage and fields depend on which provider is configured; with none configured this tool is unavailable. Returns basic contact info (name, title, seniority, LinkedIn, org). Costs 2 credits per call regardless of result count — batch every filter into ONE call. Filter only via the declared parameters: personTitles, personSeniorities, personLocations, organizationLocations, organizationNumEmployeesRanges, contactEmailStatus. There is NO free-text or keyword search — express intent through personTitles and personSeniorities; unknown params are silently ignored (check metadata.warnings if filters seem to have no effect). LARGE COMPANIES: for big accounts an unfiltered search returns a default page that is NOT meaningfully ranked — always pass personTitles and/or personSeniorities. If a search returns 0 results, STOP and report 'no matches found' — do not retry with different title variations. Limit yourself to 2 searches per request (initial + optional pagination). Use contact_enrich to get email/phone for the best matches.", "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 into this ONE array (e.g., [\"VP Marketing\", \"CMO\", \"Head of Marketing\"]) rather than making separate calls per title. This is the primary way to express search intent; there is no free-text/keyword param. Do NOT pass q, keywords, or titles — those are not real parameters and are silently ignored." }, "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. Do NOT pass a \"seniority\" param — only personSeniorities is honored; anything else is silently ignored." }, "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 (see metadata.warnings)." }, "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": "Which external contact provider to use: \"auto\" (default — picks a configured provider), \"apollo\", or \"zoominfo\". A named provider must be configured for your org or the call fails." } }, "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 schema of YOUR ORGANIZATION'S OWN Snowflake data (the customer's connected warehouse), not HG Insights' datasets.\nDrill into one dataset: list the schemas 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 when you need 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_company_hierarchy", "description": "Traverse the full UCM corporate ownership tree (multi-level parent/subsidiary hierarchy) for one company, by HG id or domain.\n\nUse this when: you need the ownership TREE — \"who owns X\", direct or all subsidiaries, sister companies, or entities filtered by country/NAICS/industry. Do NOT use this when: you only need ONE company plus its immediate ultimate-parent — use company_firmographic (company_level + global_hq_* in a single cheaper call). For brand→domain resolution use search_companies.\n\nDEFAULTS: mode=\"children\", depth=1 (omit depth = direct children only, NOT the full subtree), no optional fields, nulls stripped. Bare call = matched node + direct children (id/name/country_code/company_level/parent_id).\n\nSIZE: mode=\"full\" or deep trees on Fortune-500 parents run 100–330+ nodes and can OVERFLOW the response. No client-side truncation — depth is the size lever; start narrow and escalate.\n\nBEWARE: (1) acquired co + mode=\"full\" returns the WHOLE parent family — check company_level, use mode=\"children\" if not \"Group HQ\". (2) depth is applied BEFORE filters, so filtering at the default depth:1 misses deeper matches — pair every filter with depth:5+. (3) naics_code/industry_name are sparse; null-valued nodes are dropped SILENTLY by those filters.\n\nRecipes: \"who owns X\"→mode:\"parents\" · all subs→depth:5 · sister cos→mode:\"parents\" then mode:\"full\" on GHQ · firmographic snapshot→depth:0,all_fields:true.\n\nDomain is LITERAL — \"alphabet.com\" = a UK fleet co, not Google (Alphabet→\"abc.xyz\", Meta→\"meta.com\"); sub-brands resolve to their GHQ. Matched node is always kept even if it fails a filter. hierarchy:null = unresolved. Credit: 0.1/node.", "inputSchema": { "type": "object", "properties": { "hierarchy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{31,32}$", "description": "HG company ID (31–32 alphanumeric characters), e.g. from search_companies or company_firmographic. Resolves faster and more precisely than a domain. Mutually exclusive with domain." }, "domain": { "type": "string", "description": "Company domain, e.g. \"microsoft.com\". URLs and \"www.\" are normalized. Matched LITERALLY, not as a brand alias — \"alphabet.com\" resolves to an unrelated UK fleet company, not Google (use \"abc.xyz\" for Alphabet, \"meta.com\" for Meta). For brand→domain resolution, call search_companies first. Mutually exclusive with id." } }, "additionalProperties": false, "description": "Company identifier — exactly one of id or domain required." }, "mode": { "type": "string", "enum": [ "full", "children", "parents" ], "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 — filter by company_level client-side for \"real\" businesses." }, "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", "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." }, "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 country_code 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. naics_code 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 (e.g. [\"software\",\"technology\"]). A node is kept when its industry_name contains ANY of the provided values. industry_name 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). Deep trees can be very large (100–330+ nodes on Fortune-500 parents) and may overflow the response — depth is the size lever. 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", "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\"." } }, "required": [ "hierarchy" ], "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). Null when no match or tree fully pruned by filters." }, "count": { "type": "number", "description": "Total nodes in the returned tree." }, "total_count_in_scope": { "type": [ "number", "null" ], "description": "Nodes directly matching country_codes filter (excludes bridge-node connectors). Null when no country filter is active." } }, "required": [ "hierarchy", "count" ], "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. 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 when present; often null for broad root attributes), `attribute_parent_id` (0 = root), `attribute_level` (1 = root theme, 2+ = more specific sub-attribute), and `product_count` (how many products carry the attribute — a rough breadth signal). The taxonomy is hierarchical: a search like 'Cloud' returns both the root 'Cloud Computing' and its children (e.g. 'Cloud Workloads'). 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). 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`. It is a taxonomy lookup, not a company data source: it never returns which companies use an attribute.", "inputSchema": { "type": "object", "properties": { "attributeName": { "type": "string", "minLength": 1, "description": "Free-text theme to search attribute names by. Case-insensitive substring match on `attribute_name` and 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 returns sub-attributes (e.g. 'Cloud' → 'Cloud Computing' and its children)." }, "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/details; 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 for results: '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)." }, "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 `has_more` is true." } }, "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": { "type": "number", "description": "0 = root-level attribute with no parent." }, "attribute_level": { "type": "number" }, "product_count": { "type": "number" } }, "required": [ "attribute_id", "attribute_name", "attribute_parent_id", "attribute_level", "product_count" ], "additionalProperties": true }, "description": "Matching attribute rows, ordered by sortBy." }, "total": { "type": "number", "description": "Total matching attributes before pagination." }, "has_more": { "type": "boolean" }, "credits_consumed": { "type": "number" } }, "required": [ "attributes", "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": "get_product_category", "description": "Search for product categories in the HG Insights taxonomy. Free — no credits consumed.\n\nMatching: categoryName and treeContains use case-insensitive LIKE substring matching — NOT fuzzy or semantic. Misspellings return zero results with no warning; use common partial terms (e.g. 'CRM', 'Security', 'Cloud') rather than guessing full names. Both filters can be combined with hasInstalls: true to exclude catalog-only categories with no install signals.\n\nReturns: category_id (Int128 hex), category_code, category_name, category_name_tree (root → leaf), has_category_installs, product_count (direct products only — NOT subtree rollup; intermediate/parent nodes typically show product_count=1 even when their subtree contains thousands of products). Prefer deeper leaf categories (longer category_name_tree) for precise filtering.\n\nUse this when:\n- You need to find the exact category name to pass to company_technographic's categories[] filter. Pass the category_name string — not the category_id. Use hasInstalls: true to limit to categories with real install data.\n- You want to explore the category taxonomy by keyword before building a technographic query.\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 to browse warehouse table schemas for SQL queries — use hg_catalog (that tool is for data query planning, not product taxonomy).\n\nDo NOT call without at least one filter (categoryName, treeContains, categoryCode, or categoryId). When providing both categoryId and categoryCode, both must match the same record (AND logic) — if in doubt, provide only categoryId. Many intermediate nodes have category_code: null; prefer categoryId for exact lookups.", "inputSchema": { "type": "object", "properties": { "categoryName": { "type": "string", "minLength": 1, "description": "Case-insensitive substring match on `category_name` (LIKE). Activates relevance ranking. Use to search categories by name, e.g. 'CRM', 'Security'." }, "treeContains": { "type": "string", "minLength": 1, "description": "Case-insensitive substring scanned across every node in `category_name_tree` (root → leaf). Useful for scoping to a 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 meaningful with `categoryName` or `treeContains`), '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": { "type": "number" } }, "required": [ "category_id", "category_name", "category_id_tree", "category_name_tree", "has_category_installs", "product_count" ], "additionalProperties": true }, "description": "Matching category rows, ordered by sortBy." }, "total": { "type": "number", "description": "Total matching categories before pagination." }, "has_more": { "type": "boolean" }, "credits_consumed": { "type": "number" } }, "required": [ "categories", "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": "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 `vendorName` substring (case-insensitive, relevance-ranked) and/or `description` substring, or look up an exact `vendorId`. Returns ranked vendor rows: `vendor_id` (UInt64), `vendor_name`, `vendor_url`, `vendor_parent_id` (null if top-level), `vendor_company_description`, and `product_count`. Set `includeProducts: true` to attach up to `productsLimit` 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 `vendorIds` 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 `vendorName`, `description`, or `vendorId`.", "inputSchema": { "type": "object", "properties": { "vendorName": { "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'. A single name can return multiple rows (a parent plus its subsidiaries — e.g. 'Oracle' → 'Oracle Corporation' and 'Oracle NetSuite'); 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 `vendorName` when both are provided: the stored description must contain the exact substring AND the name must match. If results are empty when combining both, retry with only `vendorName`; the stored description text may not contain your exact phrase." }, "vendorId": { "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." }, "hasProductsWithInstalls": { "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`." }, "includeProducts": { "type": "boolean", "default": false, "description": "When true, each vendor row carries a `products[]` of `{product_id, product_name}` ordered by presence frequency, capped at `productsLimit`." }, "productsLimit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Cap on the `products[]` list per vendor when `includeProducts` is true (1–100)." }, "sortBy": { "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 `vendorName`), 'vendor_name' (A→Z), or 'product_count' (most products first)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of vendor 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": { "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 `includeProducts` is false/omitted." } }, "required": [ "vendor_id", "vendor_name", "product_count" ], "additionalProperties": true }, "description": "Matching vendor rows, ordered by sortBy." }, "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 to plan an hg_data_query — returns table names, descriptions, approximate row counts, and per-column definitions (name, type, description), plus table relationships for joins.\n\nUse this when:\n - Discovering which tables and columns exist before writing SQL for hg_data_query (this is the required first step).\n - Confirming a column's exact name, data type, or join key before referencing it in a query.\n - Inspecting one specific table's schema — pass table_name to filter to a single table.\n\nDo NOT use this when:\n - You want to RUN a query and get rows back — call hg_data_query instead (this tool returns schema metadata only, never data).\n - You need the product/technology taxonomy (categories, vendors, product IDs) — call get_product_category or get_vendor_information; those describe HG's product catalog, NOT warehouse table schemas.\n\nResponse: tables[]{name, description, approximate_row_count, columns[]{name, type, description}} and relationships[] between tables. Omit table_name to list every table; pass it to filter to one (unknown name errors and points you back to the unfiltered call).", "inputSchema": { "type": "object", "properties": { "table_name": { "type": "string", "pattern": "^[a-z_][a-z0-9_]{0,63}$", "description": "Optional exact table name (lowercase, underscores; e.g. \"company_spend\") to return just that table's schema. Omit to list every table. An unrecognized name errors — call with no table_name first to see valid names." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Table name." }, "description": { "type": "string", "description": "Table description." }, "approximate_row_count": { "type": "number", "description": "Approximate number of rows." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name." }, "type": { "type": "string", "description": "Column data type." }, "description": { "type": "string", "description": "Column description." } }, "required": [ "name", "type" ], "additionalProperties": true }, "description": "Columns in this table." } }, "required": [ "name", "columns" ], "additionalProperties": true }, "description": "Available tables in the data warehouse." } }, "required": [ "tables" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "hg_data_query", "description": "Run a structured read-only SQL SELECT query over the HG Insights data warehouse tables; returns rows, column names, a row count, and credits consumed. Use this when you need a custom aggregation, multi-table join, time-series rollup, competitive-displacement (category IN / product NOT IN), or raw exploration that no purpose-built HG tool can express. \n\nALWAYS call hg_catalog FIRST for exact table/column names — do NOT invent columns. Queries must be SELECT-only (no INSERT/UPDATE/DELETE/DROP); `SELECT *` is not allowed; violations are rejected upstream. \n\nDo NOT use this when a purpose-built tool already answers the question — they are cheaper, simpler, and need no SQL: company_technographic (a company's tech stack), search_companies (find/count companies by vendor/product/category/geo/size, with built-in groupBy and technologyIds), company_spend, company_install_time_series, get_vendor_information (a vendor's product IDs). Prefer those first. \n\nCOST: billed at ~1 credit per row returned (exact amount reported as credits_consumed). Prefer COUNT/aggregate queries and a tight max_rows — thousands of rows cost thousands of credits. A 0-row match returns an empty `columns` array. \n\nCommon columns (confirm via hg_catalog): company_locations has `name`, `country_name`, `employees_min`, `employees_max`, `company_id`, `url_id`; install_global has `product_id`, `product_name`, `vendor_name`, `category_leaf_name`, `url_id` (NO category_id). Join the two with `USING (url_id)`. \n\nFor TAM: get_vendor_information returns a vendor's product IDs, then join install_global to company_locations for installed-base/displacement counts; derive categories from install_global (never guess a category_leaf_name value). See this tool's examples for full SQL.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "A single read-only SQL statement to run against the HG 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 and reference at least one allowed warehouse table." }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000, "description": "Row cap for the result set (default 1000, max 10000). Billed at ~1 credit per row returned, so set this as low as the task allows — prefer COUNT/aggregate queries over pulling raw rows to control cost." } }, "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": "intent_category", "description": "Find WHICH COMPANIES are showing buyer intent for a specific topic, vendor, or product. Given one topic (e.g. \"cloud security\"), returns the ranked list of companies researching it — merged HG proprietary + TrustRadius signals with signal strength (0–100, where 100 = strongest), intent levels (High/Medium/Low), buyer journey stages, and context types. This is the INVERSE of company_intent: topic → companies here, vs. company → its top topics there.\n\nUse this when: you have a topic/product/vendor and want the account list (topic → companies) — e.g. \"which companies are researching Snowflake?\", \"who is in-market for ERP right now?\", or building a target/ABM list from an intent theme. Narrow with vendor_name, product_name, intent_level, buyers_journey, context_type, source, or a date window.\n\nDo NOT use this when:\n- You have ONE company and want its top intent topics → use company_intent (company → its top topics).\n- You do not yet know a valid topic name → call list_intent_topics FIRST to discover exact topic names/IDs (topic_name is fuzzy-matched, but a bad guess returns topic_matched:false and zero companies).\n\ntopic_name is REQUIRED. Passing signal, products, group_by, or filters switches this tool into activity-search mode (raw events / cross-company aggregates) and cannot be combined with the intent-only filters above.", "inputSchema": { "type": "object", "properties": { "topic_name": { "type": "string", "maxLength": 200, "description": "REQUIRED. The topic/category whose intent-showing companies you want returned (e.g., \"Siemens Teamcenter\", \"cloud security\", \"ERP\"). Fuzzy-matched server-side; an unmatched guess yields topic_matched:false with zero companies, so call list_intent_topics first to get a valid name." }, "vendor_name": { "type": "string", "maxLength": 200, "description": "Narrow the returned companies to those whose intent signals relate to this vendor (e.g., \"Snowflake, Inc.\"). Pair with context_type=Displacement to find accounts moving off the vendor. Intent-mode only." }, "product_name": { "type": "string", "maxLength": 200, "description": "Narrow the returned companies to those whose intent signals relate to this product (e.g., \"Salesforce Sales Cloud\"). Intent-mode only. Distinct from the `products` array, which activates activity-search mode." }, "intent_level": { "type": "string", "enum": [ "High", "Medium", "Low" ], "description": "Return only companies at this intent strength. Intent-mode only." }, "buyers_journey": { "type": "string", "maxLength": 100, "description": "Return only companies at this buyer-journey stage (e.g., \"Researching\", \"Evaluating\", \"Purchasing\"). Intent-mode only." }, "context_type": { "type": "string", "maxLength": 100, "description": "Return only companies with this context type (e.g., \"Whitespace\", \"Expansion\", \"Displacement\", \"Complementary\"). Intent-mode only." }, "source": { "type": "string", "enum": [ "hg", "trustradius" ], "description": "Restrict to one data source. Omit to merge both HG and TrustRadius signals. Intent-mode only." }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date in YYYY-MM-DD format. Defaults to 30 days ago." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date in YYYY-MM-DD format. Defaults to today." }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of intent-showing companies to return (1-200, default 50). Intent mode; `limit` overrides it when both are set." }, "signal": { "type": "string", "enum": [ "comparison", "pricing", "research", "evaluation" ], "description": "Buyer-activity signal category to search for. Activates activity-search mode (raw events / aggregates), NOT the topic intent list. Values: comparison (view Comparison, click Comparisons), pricing (view Product Pricing), research (view Product Listing, view Category), evaluation (view Review, view Reviews and Ratings)." }, "products": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 10, "description": "Array of product names with AND logic — returns only companies/events matching ALL products (e.g., [\"Databricks\", \"Snowflake Platform\"]). Activates activity-search mode. Distinct from product_name, which filters intent mode." }, "filters": { "type": "object", "properties": { "employees_range": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Employee range filter (e.g., \"10,000+\", \"1,001-5,000\", \"201-500\")." }, "country_codes": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 50, "description": "ISO country code filter (e.g., [\"US\", \"GB\"])." }, "category_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by product category name." } }, "additionalProperties": false, "description": "Firmographic and category filters. Presence activates activity-search mode." }, "group_by": { "type": "string", "enum": [ "company" ], "description": "\"company\" for aggregated per-company rows, omit for raw individual events with evidence URLs. Activates activity-search mode." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Page size (1-200). Overrides maxResults when provided. Applies to both intent and activity-search modes." }, "offset": { "type": "integer", "minimum": 0, "description": "Zero-based pagination offset (default 0). Applies to both modes." } }, "required": [ "topic_name" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "context": { "type": "object", "properties": { "date_range": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": true }, "source": { "type": "string", "description": "Data sources queried" }, "topic_resolved": { "type": "object", "properties": { "topic_id": { "type": "string" }, "topic_name": { "type": "string" } }, "required": [ "topic_id", "topic_name" ], "additionalProperties": true, "description": "The resolved topic. Absent when topic_matched is false." }, "topic_matched": { "type": "boolean", "description": "False when the requested topic_name matched no known topic (companies will be empty). Absent when a topic resolved." }, "no_match_reason": { "type": "string", "description": "Human-readable explanation when topic_matched is false, naming the unmatched topic." }, "generated_at": { "type": "string" } }, "required": [ "date_range", "source", "generated_at" ], "additionalProperties": true, "description": "Query context including date range, sources queried, and resolved topic (intent mode)" }, "companies": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "string" }, "company_name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "signal_strength": { "type": "number", "description": "Intent signal strength 0-100 (intent mode)" }, "intent_level": { "type": [ "string", "null" ], "description": "High, Medium, or Low (intent mode)" }, "buyers_journey": { "type": [ "string", "null" ] }, "context_types": { "type": "array", "items": { "type": "string" } }, "topics_matched": { "type": "array", "items": { "type": "string" } }, "last_seen_at": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "employees_range": { "type": "string", "description": "Activity search mode" }, "event_count": { "type": "number", "description": "Activity search mode" }, "total_views": { "type": "number", "description": "Activity search mode" }, "last_activity_date": { "type": "string", "description": "Activity search mode" }, "products_compared": { "type": "array", "items": { "type": "string" }, "description": "Activity search mode" }, "vendors": { "type": "array", "items": { "type": "string" }, "description": "Activity search mode" }, "signals": { "type": "array", "items": { "type": "string" }, "description": "Activity search mode" } }, "additionalProperties": true }, "description": "Intent mode: companies with signal strength. Activity search mode (group_by=company): companies with event counts." }, "events": { "type": "array", "items": { "type": "object", "properties": { "activity_date": { "type": "string" }, "activity_type": { "type": "string" }, "activity_label": { "type": "string" }, "signal": { "type": "string" }, "daily_views": { "type": "number" }, "product_names": { "type": "array", "items": { "type": "string" } }, "vendor_names": { "type": "array", "items": { "type": "string" } }, "category_name_trees": { "type": "array", "items": { "type": "string" } }, "intent_signal_url": { "type": "string" }, "company_id": { "type": "string" }, "company_name": { "type": "string" }, "domain": { "type": "string" } }, "additionalProperties": true }, "description": "Individual activity events with evidence URLs (returned when group_by is omitted)" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "has_more": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "has_more" ], "additionalProperties": true, "description": "Pagination details for result set" } }, "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 name, or to correlate against the departmentId/roleId fields returned by company_fai. 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": 0, "description": "Maximum number of departments to return (>= 0). Omit for the upstream default (returns the full catalog, which is small). Combine with offset to page." }, "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: discover valid intent topic names/IDs from the official HG Insights catalog. Intent topics are buying-signal themes companies research online (e.g. \"Cloud Security\", \"ERP\", \"Salesforce Sales Cloud\"). This tool ONLY lists/searches the topic vocabulary — it does not return any company or intent data.\n\nUse this when: you need the exact spelling of a topic before filtering intent — i.e. discover valid topic names before feeding one into intent_category or company_intent. Always resolve topic names here rather than guessing; a bad guess elsewhere returns topic_matched:false and zero companies.\n\nQuery with a SINGLE keyword (e.g. 'security', 'cloud', 'ERP', 'Salesforce'). Multi-word descriptive phrases (e.g. 'cloud storage solution') return 0 results because the search matches catalog topic NAMES, not natural language. For broader coverage run several single-word queries with different keywords or word forms (e.g. 'cloud', then 'storage', then 'infrastructure').\n\nDo NOT use this when:\n- You want a specific company's top intent topics → use company_intent (company → its topics).\n- You want the companies showing intent for a topic → use intent_category (topic → companies).", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "REQUIRED. Single-keyword substring matched against catalog topic NAMES (e.g., 'security', 'cloud', 'ERP', 'Salesforce'). Returns the closest matching topic names/IDs sorted by relevance. WARNING: Multi-word descriptive phrases (e.g., 'cloud storage solution', 'data warehouse platform') return 0 results — this matches topic names, not natural language. To widen coverage, make several calls with different single-word keywords or word forms (e.g., 'cloud', then 'storage', then 'infrastructure')." }, "is_tech": { "type": "boolean", "description": "When true, return only technology-related intent topics. Omit to include all topic categories." }, "limit": { "type": "number", "description": "Maximum topic names to return (default 50). Raise to retrieve more matches; values above the 500-per-page size are fetched via pagination up to a 5000-topic cap." } }, "required": [ "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of intent topics returned" }, "totalAvailable": { "type": "number", "description": "Total number of intent topics matching the query" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique intent topic identifier" }, "name": { "type": "string", "description": "Intent topic name" }, "category": { "type": "string", "description": "Topic category" }, "is_tech_related": { "type": "boolean", "description": "Whether this is a technology-related topic" } }, "required": [ "id", "name" ], "additionalProperties": true }, "description": "List of intent topic information" } }, "required": [ "count", "totalAvailable", "topics" ], "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 that recommends 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\"). Do NOT use this when you already know which specific data tool to call (e.g. the user asked for a company's firmographics, technographics, or intent) — call that tool directly. 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 the `role`, `company`, and `recommended_prompts` parameters. Faster first run: you MAY call with `role` and `recommended_prompts` while OMITTING `company` rather than stalling — Phoenix pre-fills it from signup data when it can (see the `company` parameter).", "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 pre-fill the company from the user's signup data when it can (corporate email domains only) instead of stalling; otherwise the recommendation asks for the company before running." }, "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\"). 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). Two actions on one tool. 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. action='enrich' (1 credit per successful match) hydrates 1-50 known product_ids into full catalog records: product_details, category_info, vendor_info. Use this when you need to look up a product in the catalog, resolve a product name to an id, browse products under a vendor/category, or fetch full catalog metadata for specific product_ids. Typical flow: search to find the id, then enrich the chosen id(s). Failed enrich ids return a per-row NO_MATCH_FOUND error at HTTP 200 and are not billed. Do NOT use this when you only need a category's canonical id or the category taxonomy — use get_product_category (it resolves category_name → category_id, which you then pass here as a filter). Do NOT use this to resolve a vendor/company to its vendor_id or to read vendor firmographics — use get_vendor_information. Because category_name/attribute_name/vendor_name are substring matches that can silently select the wrong entry (e.g. 'CRM' can match a BPO/outsourcing category rather than CRM software), prefer resolving the exact id first — category_id via get_product_category, attribute_ids via get_product_attribute, vendor_id via get_vendor_information — and pass those ids as filters.", "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). 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 tiebreaker order). 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. Unknown/missing ids return a per-row NO_MATCH_FOUND error at HTTP 200 and cost no credits." } }, "required": [ "action" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "number" }, "product_name": { "type": "string" }, "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" ] } }, "required": [ "product_id", "product_name" ], "additionalProperties": true }, "description": "search only. Slim product hit list." }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "has_more": { "type": "boolean" } }, "required": [ "total", "limit", "offset", "has_more" ], "additionalProperties": true, "description": "search only." }, "products": { "type": "array", "items": { "type": "object", "properties": { "input_key": { "type": "object", "additionalProperties": {} }, "product_id": { "type": [ "number", "null" ] }, "product_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" } ] }, "error": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "input_key" ], "additionalProperties": true }, "description": "enrich only. One result row per input product_id." }, "credits_consumed": { "type": "number", "description": "search: always 0. enrich: 1 per successful match." } }, "required": [ "credits_consumed" ], "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" }, "annotations": { "readOnlyHint": true, "openWorldHint": true, "destructiveHint": false, "idempotentHint": true } }, { "name": "search_companies", "description": "Search for companies by firmographic and technographic criteria — list/filter workflow (e.g. \"find US tech companies using Snowflake with 1K–10K employees\"). Use for building prospect/ICP lists, filtering by technology install across many companies, or segmenting by geography, employee band, revenue range, industry, or NAICS.\n\nDo NOT use when:\n - You already know the domain or hg_id — call company_firmographic (faster, exact match, richer data).\n - You want a full company profile (intent, spend, technographics) — call company_research.\n - You want one company's full tech stack — call company_technographic (returns installs, not a list).\n\nGUARDRAIL: a zero-param call is rejected with HTTP 422 (server enforces ≥1 filter). Firmographic-only filters are too broad alone — countries=[\"US\"] matches 500K+ records, revenue/employee filters 100K+. Always pair any firmographic-only filter with a meaningful one: technology_ids, vendor_ids, category_ids, countries, or industry_ids.\n\n⚠ TOKEN BUDGET: limit above 50 with a broad geo/revenue filter can produce 100–250KB responses that overflow the context window. Default limit=10; use 10–50 for exploration; paginate with offset for bulk. Do NOT set limit=1000 unless batching results outside this conversation.\n\nNOTE: rank and last_verified_date are no-ops on firmographic-only queries — they only apply when technology_ids, vendor_ids, or category_ids is present (metadata still echoes rank_mode).\n\nBad technology_ids/vendor_ids/category_ids return HTTP 422 (not empty results) — resolve via get_vendor_information.\n\nResponse: companies[]{hg_id (→ enrichment tools), domain, company_name, relative_revenue (HG USD est, nullable), relative_employees (HG est), country_code (ISO-2), industry, industry_id}; total_count = total matches (paginate with offset).", "inputSchema": { "type": "object", "properties": { "technology_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 10, "description": "HG Insights product IDs — exact match, max 10. Validated: an unrecognized ID returns HTTP 422 (no silent empty result). Resolve IDs via get_vendor_information or product_search_and_enrich before filtering — there is no technology_name param." }, "vendor_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 10, "description": "HG Insights vendor IDs — matches all products from that vendor, max 10. Validated: unknown vendor ID returns HTTP 422. Resolve via get_vendor_information. Use technology_ids instead when you want specific products." }, "category_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}$|^[0-9A-Fa-f]{32}$" }, "maxItems": 10, "description": "HG Insights category IDs (UUID, e.g. \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"), max 10. Validated: unknown category ID returns HTTP 422. Resolve via get_vendor_information — it returns category_ids on each product row." }, "exclude_technology_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 10, "description": "Product IDs to exclude from results, max 10. Applied after inclusion filters (technology_ids, vendor_ids, category_ids). Validated: unknown product ID returns HTTP 422." }, "technology_mode": { "type": "string", "enum": [ "AND", "OR" ], "description": "AND = company must have ALL listed technology_ids (default). OR = company needs any one. IMPORTANT: this setting only controls how multiple technology_ids are combined — vendor_ids and category_ids are always OR-matched regardless of this value." }, "industry_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 20, "description": "HG industry IDs — exact match on the company's own industry_id, max 20. Validated: unknown ID returns HTTP 422. Resolve valid IDs via search_industries_naics_sic." }, "naics_codes": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "NAICS code prefixes, max 10. \"54\" matches all 54xxxx codes; \"541512\" is exact. Validated: unrecognized prefix returns HTTP 422. Find valid codes via search_industries_naics_sic." }, "sic_codes": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "SIC codes — array membership match on the company's sic_codes field, max 20. Validated: unknown code returns HTTP 422. Find valid codes via search_industries_naics_sic." }, "countries": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Exact match on company HQ country (ISO-2, e.g. \"US\", \"DE\", \"GB\"), max 10. Filters by headquarters location, not where the tech was detected. Can be combined with technology_countries — e.g. countries=[\"US\"] + technology_countries=[\"DE\"] finds US-HQ companies where the technology signal was detected in Germany." }, "technology_countries": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "ISO-2 country codes for WHERE the technology signal was detected (not company HQ), max 10. ⚠ ENFORCED — requires is_localized=true (omitting returns HTTP 422). ⚠ ENFORCED — requires at least one companion filter (technology_ids, vendor_ids, category_ids, or a firmographic filter); omitting all companions returns HTTP 422. NOTE: Without a technology filter (technology_ids/vendor_ids/category_ids), returns companies with any install signal in that country — not a specific product. Results may include companies with a country_code different from this filter (signal location ≠ HQ location). Can be combined with countries — e.g. technology_countries=[\"DE\"] + countries=[\"US\"] finds US-HQ companies with the tech detected in Germany." }, "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Exact match on normalised company domain (e.g. \"salesforce.com\") — exact spelling, no protocol or www prefix, max 100. Preferred over company_name when you know the domain." }, "last_verified_date": { "type": "string", "description": "ISO 8601 date (e.g. \"2024-01-01\"). Excludes installs last verified before this date. Combine with rank=3m to restrict to recently re-confirmed installs only." }, "revenue_min": { "type": "number", "minimum": 0, "description": "Minimum annual revenue in USD (e.g. 1000000 = $1M, 1000000000 = $1B). HG proprietary estimate — may differ from self-reported figures. Do NOT use as the only filter — pair with technology_ids, vendor_ids, category_ids, or countries to avoid matching millions of companies." }, "revenue_max": { "type": "number", "minimum": 0, "description": "Maximum annual revenue in USD (e.g. 1000000000 = $1B). HG proprietary estimate — may differ from self-reported figures. Do NOT use as the only filter — pair with technology_ids, vendor_ids, category_ids, or countries." }, "employee_min": { "type": "integer", "minimum": 0, "description": "Minimum employee count. Common bands: 1–100 (SMB), 101–1000 (mid-market), 1001+ (enterprise). HG proprietary estimate — may differ from self-reported figures. Pair with technology_ids or countries to avoid overly broad results." }, "employee_max": { "type": "integer", "minimum": 0, "description": "Maximum employee count. Pair with employee_min to define a band. HG proprietary estimate — may differ from self-reported figures. Pair with technology_ids or countries to avoid overly broad results." }, "company_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring (ILIKE) match on company name. Only use for known, specific names (e.g. \"Salesforce\", \"Cisco Systems\"). Do NOT pass descriptive phrases like \"fast-growing SaaS\" — this is a direct database string match, not semantic search; descriptive phrases return zero results. Prefer the domains filter for known companies." }, "is_localized": { "type": "boolean", "description": "Use localized install data (per-country signals). Default false = global signals. Must be true for technology_countries to have any effect." }, "rank": { "type": "string", "enum": [ "3m", "all_time" ], "description": "all_time (default): historically strongest installs — best for ICP lists. 3m: recent adoption momentum — best for intent-based outreach. Combine with last_verified_date to further restrict to recently re-confirmed installs. NOTE: rank and last_verified_date only affect results when at least one of technology_ids, vendor_ids, or category_ids is present — they filter install recency, not company-level recency; on firmographic-only queries they have no effect." }, "limit": { "type": "number", "minimum": 1, "maximum": 1000, "default": 10, "description": "Maximum companies to return (default: 10, max: 1000). Use 10–50 for exploratory queries; paginate with offset for bulk workflows." }, "offset": { "type": "integer", "minimum": 0, "description": "Pagination offset (default: 0). Use with limit to page through results. total_count in the response gives total matches across all pages regardless of limit." } }, "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 (32 alphanumeric chars). Pass directly to hg_id param on any enrichment tool (company_firmographic, company_technographic, company_research, etc.)." }, "company_name": { "type": "string" }, "domain": { "type": "string" }, "relative_revenue": { "type": [ "number", "null" ], "description": "HG Insights proprietary annual revenue estimate in USD (e.g. 582900000000 = ~$583B). May differ from self-reported figures. Null when unknown." }, "relative_employees": { "type": [ "number", "null" ], "description": "HG Insights proprietary headcount estimate. May differ from self-reported figures. Null when unknown." }, "country_code": { "type": [ "string", "null" ], "description": "ISO-2 country code (e.g. \"US\", \"DE\") — same format as the countries filter." }, "industry": { "type": [ "string", "null" ] }, "industry_id": { "type": [ "number", "null" ], "description": "HG industry ID — use for industry_ids filter." } }, "additionalProperties": true }, "description": "Array of company results (empty when group_by is specified)." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "product_id": { "type": "string" }, "product_name": { "type": "string" }, "vendor_name": { "type": "string" }, "category": { "type": "string" }, "industry": { "type": "string" }, "company_count": { "type": "number" } }, "additionalProperties": true }, "description": "Present when group_by is specified." }, "total_count": { "type": "number", "description": "Total matches across all pages — always the full count regardless of limit/offset. Use to decide whether to paginate." }, "credits_consumed": { "type": "number", "description": "Credits billed for this call: 1 credit per 100 companies returned on this page (not per total_count). Fractional." }, "metadata": { "type": "object", "properties": { "filters_applied": { "type": "array", "items": { "type": "string" } }, "unresolved_countries": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "required": [ "companies", "credits_consumed" ], "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 ICT/GSI and, optionally, federal awards); (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 so you can feed them into `search_companies` (`industry_ids`, `naics_codes`, `sic_codes`). Searches and translates across HG industry (23 buckets), NAICS 2012 (~2,200 codes), and SIC 1987 (~1,500 codes) in one call. Use this when you have an industry NAME or colloquial sector term (\"fintech\", \"software publishers\") and need its numeric code(s) before an industry-scoped company search — resolve the code here first. Do NOT use this to actually find companies — that is `search_companies` (pass the `industry_ids`/`naics_codes`/`sic_codes` you resolved here). Do NOT use this to find what industry a specific company belongs to — call `company_firmographic` (pass `companyDomain` or `hg_id`). This tool searches taxonomy definitions, not company records, and returns no revenue, headcount, or company counts. When chaining codes downstream: pass `industry_id` integers to `industry_ids`; pass `sic.sic_standard_code` (e.g. \"7372\"), NOT `sic.sic_code` (the \"I7372\" HG-extended form has an internal letter prefix and will not match); and prefer leaf NAICS (`is_leaf=true`), since rollups will not match a single company's classification. The response includes `alias_expansions` (colloquial terms rewritten server-side) and, when `results` is empty on a near-miss, a `suggestions` array of the closest taxonomy names — check it before retrying; if it is absent too, rephrase to a broader category. Free — no credits consumed.", "inputSchema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 2, "description": "Optional. Text input → case-insensitive substring match against industry/NAICS/SIC name columns. A known code works as a translation lookup (\"541511\", \"7372\") returning the full crosswalk. 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, ecommerce, healthcare, cybersecurity, cleantech, ev, biotech, gaming, streaming, logistics, adtech, proptech, insurtech, edtech, airline, hospitality, renewable, semiconductor, …) are expanded server-side into the substrings actually present in NAICS/SIC names; 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 (`naics_count`, `sic_count`) 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`. Prefer this grouped mode for most use-cases. Omit it only when you need the raw NAICS↔SIC crosswalk table (unscoped mode repeats the same NAICS once per SIC partner). Each `naics` block exposes `hierarchy_level` (sector|subsector|industry_group|naics_industry|national_industry), `is_leaf`, and `display_name_with_level` (disambiguates same-named adjacent levels, e.g. \"Commercial Banking (subsector 5221)\" vs \"(national_industry 522110)\")." }, "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 (1,590 of 2,209) — 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. If you page past the end, `pagination.offset_exceeds_total` is true (disambiguates empty results with `has_more=false`)." } }, "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" }, "industry_name": { "type": "string" }, "naics_count": { "type": "number", "description": "Crosswalk count — populated only in grouped mode (taxonomy=industry)." }, "sic_count": { "type": "number", "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" }, "naics_name": { "type": "string" }, "naics_top_parent_code": { "type": "string" }, "naics_top_parent_name": { "type": "string" }, "hierarchy_level": { "type": "string", "enum": [ "sector", "subsector", "industry_group", "naics_industry", "national_industry" ], "description": "NAICS level derived from code length (2/3/4/5/6 digits)." }, "is_leaf": { "type": "boolean", "description": "True iff `hierarchy_level == \"national_industry\"`. Only leaves are safe to chain into downstream code-based filters." }, "display_name_with_level": { "type": "string", "description": "Disambiguating label, e.g. \"Commercial Banking (subsector 5221)\"." }, "sic_count": { "type": "number", "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", "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", "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" }, "is_hg_extension": { "type": "boolean", "description": "True when `sic_code` carries an HG-internal letter prefix (currently true for every SIC row)." }, "naics_count": { "type": "number", "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": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "expanded_to": { "type": "array", "items": { "type": "string" } } }, "required": [ "term", "expanded_to" ], "additionalProperties": true }, "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": { "type": "array", "items": { "type": "string" }, "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 and per-section caveats are in the \"section\" parameter). Returns the single most recent matching filing.\n\nUse this 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 this 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, tech stack) use company_research; for non-SEC web info use web_search.\n\nSCOPE: US domestic issuers only (10-K / 10-Q / 8-K). Foreign private issuers (e.g., Barclays, BP, SAP, Toyota) file 20-F / 6-K / 40-F instead — this tool returns \"No filing found\" for them, redirecting you to 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 targeting recurring 8-K events, e.g. 2.02 earnings, to a specific window).\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\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 (under 50 words). If content is under 100 words and mentions a Proxy Statement, the full data is not available via this tool.\n8-K EXHIBIT NOTE: items like \"2.02\" (earnings) often contain only a stub referencing Exhibit 99.1; the exhibit text is not returned. For the full earnings narrative, use sec_full_text_search.\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": "Keyword full-text search ACROSS SEC filings — finds which filings mention a term or phrase, spanning many companies at once. Thin wrapper around the sec-api.io full-text-search API; ticker symbols are resolved to CIKs automatically. Supports AND, OR, NOT, wildcards (*), and exact phrases (\"quoted\").\n\nUse this when: you want to find every filing that mentions a term across companies (\"who disclosed a 'material weakness' this quarter?\"), scan for an event or risk phrase, or discover filings for a company by ticker without knowing the specific document.\n\nDo NOT use this when: you already know the specific filing and want to READ one named section from it (\"risk factors\", \"MD&A\") — use sec_filing_section instead (it calls this concept filingType, a singular enum string, not the array formTypes here). For general company background (revenue, employees, technographics) use company_research; for non-SEC web info use web_search.\n\nCORPUS: Covers incident-reporting and event-driven filings. Common financial terms (\"revenue\", \"earnings\") are not indexed and return zero results.\n\nDATE WARNING: startDate defaults to the last 30 days. Annual filings (10-K, 20-F, 40-F) are filed yearly — pass startDate \"2020-01-01\" for them or you get zero results.\n\nQUERY EXAMPLES: \"material weakness\" · cybersecurity AND breach · layoff* · \"going concern\" OR \"substantial doubt\" · acquisition NOT merger.\n\nForeign issuers: formTypes [\"20-F\"] (Barclays/BP/Toyota/Shell), [\"6-K\"] (interim), [\"40-F\"] (Canadian) — some ADR issuers (e.g. SAP) have no 20-F on EDGAR.\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 any warnings) before treating results as company-specific.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "default": "cybersecurity incident", "description": "Keyword/phrase query to match in filing text. Supports AND, OR, NOT, wildcards (*), and exact phrases (\"quoted\"). This searches ACROSS filings — it does not extract a named section from one known filing (use sec_filing_section for that). Common financial terms (\"revenue\", \"earnings\") are not indexed and return zero results." }, "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\", \"SAP\"]). 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 (e.g., SAP, LVMH) 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, public-web context, and anything about people, products, or events outside HG's firmographic/technographic/intent datasets. Runs a live search (Tavily) and returns relevant results with title, URL, a content snippet, and an optional AI-generated answer summary. Use this 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. Do NOT use this when a purpose-built HG tool covers the request — reach for company_firmographic (company profile/size/HQ/industry), company_technographic (installed technologies), company_intent (buying signals), search_companies (find companies by criteria), or sec_full_text_search / company_contracts (filings, contracts) instead, since those return richer, structured, billable HG data. Cost: 0.05 credits (searchDepth='basic') or 0.10 credits (searchDepth='advanced' deep extraction). Set includeRawContent=true to also get full cleaned page content (no extra credit cost, slightly higher latency).", "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." }, "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. 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 } } ] }