Tools Reference

BetterWebSearch MCP exposes 6 tools (5 unique + 1 alias). All are keyless-first — DuckDuckGo provides search without any API keys.

Overview#

web_search#

Fast multi-provider search. Aggregates results from all enabled providers, deduplicates, re-ranks by relevance, and returns the top matches.

Input parameters:

Response shape:

{
  "answer": "Top N results for \"query\"",
  "sources": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "snippet": "Short description...",
      "published": "2026-08-29T10:00:00Z",
      "relevance": 0.85
    }
  ],
  "queries_used": ["query"]
}

web_research (alias: deep_search)#

Deep research orchestrator. Rewrites a question into multiple search variants, runs them in parallel across providers, merges/deduplicates/ranks, opens the top pages through the extraction pipeline (bounded concurrency 3, 8s per page timeout), and returns the passages that actually address the question, each with a citation anchor. No LLM is involved — passages are selected with BM25 against the question, so the calling agent receives evidence rather than page intros.

Input parameters:

Response shape:

{
  "answer": "Based on N sources:\n\n[1] excerpt...\n[2] excerpt...",
  "sources": [...],
  "queries_used": ["original question", "variant 2", "..."],
  "extraction_stats": {
    "method_counts": { "http_fetch": 5, "hydration_data": 3 },
    "avgConfidence": 0.91
  }
}

Key behaviors:

• Query expansion: unlimited mobile internet Germany → 4–6 variants incl. unbegrenztes Datenvolumen ... Deutschland
• Bounded concurrency: 3 pages opened simultaneously
• Per-page timeout: 8 seconds
• Max pages extracted: 10
• Max cited passages in answer: 5 (at most 2 considered per page, best-first across independent sources)
• Sources are clustered by content before citing: syndicated reprints and multiple pages from one host count as one account, and derivative copies are not quoted
• The evidence block reports measured counts only (sources_opened, independent_sources, derivative_sources, query_term_coverage, cited_spans). No confidence score is returned, because nothing in this server can compute one

web_extract#

Extracts readable content from one or more URLs using the three-tier escalation pipeline (HTTP fetch → structured hydration → Playwright browser). Returns per-URL content with extraction method, confidence score, structured data, and API endpoints.

Input parameters:

Response shape (per URL):

{
  "url": "https://example.com/page",
  "title": "Page Title",
  "content": "Extracted markdown content...",
  "extraction": {
    "method": "http_fetch",
    "confidence": 0.85,
    "rendered": false
  },
  "structured_data": {...},
  "api_endpoints": {...},
  "metadata": {
    "title": "...",
    "description": "...",
    "published": "...",
    "author": "...",
    "siteName": "..."
  }
}

web_find#

Site-restricted search. Builds a site:<domain> <query> query and returns the top matching pages.

Input parameters:

Response shape:

{
  "answer": "Top N results from example.com for \"query\"",
  "sources": [...],
  "queries_used": ["site:example.com query"]
}

web_news#

Recency-filtered news search with timeline grouping and domain diversity enforcement.

Input parameters:

Response shape:

{
  "answer": "Top N recent news results for \"topic\" within 7 days",
  "sources": [...],
  "timeline": {
    "2026-08-29": [...],
    "2026-08-28": [...]
  },
  "queries_used": ["topic"]
}

Key behaviors:

• Filters results strictly by publication date within the recency window
• Enforces domain diversity: at most one result per host
• Groups results into a timeline keyed by publication date (YYYY-MM-DD)
• Uses 3× max_results from providers before filtering for diversity

Shared response structure#

All search tools return SearchSource entries:

{
  "title": "Page Title",
  "url": "https://example.com/page",
  "snippet": "Short text description",
  "published": "2026-08-29T10:00:00Z",
  "relevance": 0.85
}

Relevance scores range from 0 to 1, computed by the reranker using: 0.5 × text_overlap + 0.2 × domain_score + 0.2 × recency + 0.1 × provider_score.