web_search next channel

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

Search the web for current public information, news, and research via Tavily. Returns relevant results (title/url/content) plus a synthesized answer. Use it for live/current public facts — announcements, press coverage, executive/leadership changes, product launches, and general public facts — that are not in HG's proprietary data.

When NOT to use:

• HG company data — for firmographics, technographics, IT/cloud spend, or AI maturity, use company_enrich, company_firmographic, company_technographic, or company_spend instead. HG serves this data canonically.
• SEC filing text — use sec_full_text_search.
• General knowledge you already know — reserve web_search for live/current facts.

Operators: Boolean exclusion syntax (e.g. -term) is NOT honored. Do not assume Google-style minus-sign exclusion works — filter unwanted results yourself.

Verbosity: includeRawContent=true returns full cleaned page content per result (no extra Tavily cost) but can add ~10KB+ of boilerplate per result — enable it only when you need full text, and keep maxResults low. searchDepth: "advanced" improves extraction (recommended alongside includeRawContent) at 2× cost.

Integration required: tavily Cache schema version: super.getCacheSchemaVersion() + 1 (differs from base — bumped per the manifest invariant even for a description-only override; stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
query	string	Required	—	The search query (trimmed, 1–500 chars). Be specific for better results. Boolean exclusion (-term) is NOT supported — do not rely on Google-style minus-sign syntax.
maxResults	integer	Optional	5	Maximum number of search results to return (1–20).
includeRawContent	boolean	Optional	false	Returns full cleaned page content for each result. No additional Tavily credit cost; small latency increase. Can return ~10KB+ of boilerplate per result — keep maxResults low when enabling.
searchDepth	string (basic | advanced)	Optional	basic	basic (0.05 credits) or advanced (0.10 credits, better extraction quality, recommended when includeRawContent is true).

Credit cost: Dynamic — 0.05 credits for basic, 0.10 credits for advanced.

Response Format

{
  "query": "latest developments in artificial intelligence",
  "answer": "Recent AI developments include …",
  "results": [
    {
      "title": "Example headline",
      "url": "https://example.com/article",
      "content": "Snippet of page content …",
      "rawContent": null,
      "score": 0.92,
      "publishedDate": "2026-08-01"
    }
  ],
  "images": [],
  "responseTime": 1.23
}

Response fields

Field	Meaning
query	The search query that was executed.
answer	AI-generated answer summarizing the search results (null when not available).
results	Array of search results.
results[].title	Page title.
results[].url	Page URL.
results[].content	Snippet of page content.
results[].rawContent	Raw page content when requested (null when includeRawContent is false).
results[].score	Relevance score.
results[].publishedDate	Publication date if available.
images	Related images when available; each has url and description.
responseTime	Time taken for the search, in seconds.

Example Usage

{
  "tool": "web_search",
  "parameters": {
    "query": "latest developments in artificial intelligence",
    "maxResults": 5,
    "searchDepth": "advanced",
    "includeRawContent": true
  }
}

Related Tools

• company_enrich — HG company enrichment; use instead of web search for HG-served company data.
• company_firmographic — HG firmographics; use instead of web search for firmographic facts.
• company_technographic — HG technographics; use instead of web search for installed-technology data.
• company_spend — HG IT/cloud spend; use instead of web search for spend data.
• sec_full_text_search — search SEC filing text; use instead of web search for filing content.

Changelog

2026-08-12 — Description accuracy fixes (PR 1/2)

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

Why this changed: A live audit found the description had no "when NOT to use" guidance and no back-references to HG's proprietary company tools, creating two-way selection ambiguity: a model could use generic web search for company firmographics/technographics/spend that HG serves canonically, or reach for a company tool when a public-news query was intended. The audit also found includeRawContent=true can return ~10KB+ of boilerplate per result with no size warning, and that Google-style minus-sign exclusion (-term) is silently ignored.

Added:

• When-NOT-to-use with neighbor cross-references — the description now says to use web_search for current public web/news info NOT in HG's data, and to NOT use it for HG firmographics/technographics/IT-cloud-spend/AI-maturity (use company_enrich / company_firmographic / company_technographic / company_spend) or SEC filing text (use sec_full_text_search).
• Minus-sign exclusion caveat — both the description and the query param describe() now state that boolean exclusion syntax (e.g. -term) is NOT honored, so callers do not assume Google-style syntax works.
• includeRawContent size-cap note — the description and the includeRawContent param describe() now warn that enabling it can add ~10KB+ of boilerplate per result and advise keeping maxResults low.

Unchanged:

• All parameters (query, maxResults, includeRawContent, searchDepth) are unchanged.
• Output shape (query, answer, results[], images[], responseTime, …) is unchanged.
• Tool key (web_search), the dynamic credit cost (0.05 basic / 0.10 advanced), and the Tavily upstream are identical to v1.

Cache schema version: super.getCacheSchemaVersion() + 1 — required by the manifest invariant even for a description-only override.