Skip to main content
Glama
scrape-mcp
by guanyuyan

web_search

Search keywords to get structured titles, URLs, and snippets; optionally fetch top results' content within a token budget for combined search-and-read workflows.

Instructions

搜索关键词,返回结构化的结果列表(标题 / URL / 摘要),不抓结果页正文。

适合"先找入口再抓正文"的两步流程:本工具负责发现候选 URL,正文仍交给 web_fetch。 传 read=true 时会并发抓取 top_k 条结果的正文并在 token 预算内返回, 一次调用即可完成"搜索 + 阅读";传 read="excerpt" 时只返回与 query 最相关的 段落(更省 token,适合问答型调用)。

Args: query: 搜索关键词,不能为空。 max_results: 期望返回条数,超出配置上限 search_max_results 时按上限截断。 provider: 搜索后端。duckduckgo=HTML 端点,无需 key(默认,取配置 search_provider); searxng=自托管实例的 JSON API,需设置 SCRAPE_MCP_SEARCH_SEARXNG_URL; brave / tavily=商业 API,需分别设置 SCRAPE_MCP_SEARCH_BRAVE_API_KEY / SCRAPE_MCP_SEARCH_TAVILY_API_KEY。 site: 限定站点,填域名或站内路径;会以 site: 运算符透传给后端, 是否严格限定取决于该后端引擎的支持程度。 time_range: 时间范围,day / week / month / year 之一,按后端映射成各自参数。 engines: SearXNG 的引擎名单(如 ["bing", "startpage"]),仅对 searxng 生效。 fallback: 当前后端失败时是否自动回退到其他已配置的后端;不传取配置 search_fallback(默认开启)。关闭后只请求 provider 指定的后端。 bypass_cache: 跳过并绕过搜索结果缓存,强制现查。 deadline_ms: 整次调用的总预算(毫秒),不传表示不限;回退同样受此预算约束。 proxy: 本次请求使用的代理;不传则按代理池分配,未配池时沿用全局配置。 read: false=不读正文(默认);true=抓整页正文;"excerpt"=只返回与 query 最相关的段落(召回不足时回退整页并标记 excerpt_fallback)。 top_k: read 生效时要读正文的条数,1~10,默认 3。 max_tokens: read 生效时的正文 token 总预算;不传取配置 search_read_max_tokens。 content_format: read=true 时正文形态,markdown(默认)或 text;excerpt 模式固定 在 markdown 上选段(text 输出的片段会去格式)。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "web_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
readNo
siteNo
proxyNo
queryYes
top_kNo
enginesNo
fallbackNo
providerNo
max_tokensNo
time_rangeNo
deadline_msNo
max_resultsNo
bypass_cacheNo
content_formatNomarkdown

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.35.0
    • addedInput schema / properties / content_format
      Added value: +{
      +  "default": "markdown",
      +  "title": "Content Format",
      +  "type": "string"
      +}
    • addedInput schema / properties / max_tokens
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Max Tokens"
      +}
    • addedInput schema / properties / read
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "string"
      +    }
      +  ],
      +  "default": false,
      +  "title": "Read"
      +}
    • addedInput schema / properties / top_k
      Added value: +{
      +  "default": 3,
      +  "title": "Top K",
      +  "type": "integer"
      +}
  2. Changed4 schema fields changedv0.25.0
    • addedInput schema / properties / engines
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Engines"
      +}
    • addedInput schema / properties / fallback
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Fallback"
      +}
    • addedInput schema / properties / site
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Site"
      +}
    • addedInput schema / properties / time_range
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Time Range"
      +}
  3. Addedv0.21.0

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: it discloses cache behavior (bypass_cache forces a live query), automatic provider fallback and its override, a total deadline budget that also bounds fallbacks, proxy-pool allocation, per-provider credential requirements, and token budgeting for read mode. Remaining gaps are failure signaling (what happens when all providers fail) and rate-limit/blocking behavior for the default DuckDuckGo HTML endpoint, which the description does not mention.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the web_fetch handoff are front-loaded, then parameters are documented in a scannable per-argument block, which is the right structure for 14 parameters. It runs long and the read/top_k/max_tokens/content_format entries overlap somewhat, but almost every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't explain return values, and it correctly stops at describing that results are a structured list. For a 14-parameter tool with 0% schema coverage and no annotations, it covers the operational essentials: auth prerequisites per provider, fallback, budget, cache, and reading modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate entirely, and it does: all 14 parameters are explained with semantics beyond their names, including enum-like value sets for time_range (day/week/month/year), numeric bounds for top_k (1-10), the truncation rule for max_results against search_max_results, and the three-way read flag with its excerpt_fallback behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: search keywords, return a structured list of title/URL/snippet, and explicitly not the result-page body. It immediately names the sibling boundary (web_fetch handles the body), so an agent can distinguish the two without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the two-step 'discover then fetch' flow and states that discovery belongs here while body extraction belongs to web_fetch. It also gives concrete alternative modes with selection criteria: read=true for one-shot search+read, read="excerpt" for token-cheap Q&A where only the most relevant passages are needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.