mcpsurfr

Overview Schema Source Related Servers Discussions Admin

Deep research

deep_research

Read-only

Research a topic across multiple search terms and engines, re-ranking results locally, removing duplicates, and fetching the best pages as text.

Instructions

Research a topic across several search terms and engines. Each term is searched on each backend, results are re-ranked locally by relevance, duplicates are removed, and the best pages are fetched as text.

Backends: auto, brave, duckduckgo, google, grokipedia, mojeek, startpage, wikipedia, yahoo.

"auto" (default): ddgs metasearch over several engines, skipping blocked ones. Most reliable.
"brave": fast and usually available.
"wikipedia": exact article lookups, best with title-like terms.
"google", "startpage", "yahoo", "mojeek": often blocked. Empty engines are reported as warnings, and if every chosen engine is empty the terms are retried with "auto".

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": {
      "search_terms": "<search_terms>"
    },
    "name": "deep_research"
  }
}

Input Schema

Name	Required	Description
`news`	No	Search news articles instead of the web. Results then carry their published "date". News backends: auto, bing, duckduckgo, yahoo. Pair with recency for current events.
`region`	No	Region-language code like "us-en", "uk-en" or "de-de". Default: ddgs's own (us-en).
`recency`	No	Applied to every term. Only results from the past "day", "week", "month" or "year".
`backends`	No	Backends to use. Defaults to ["auto"]. Unknown names are skipped with a warning.
`passages`	No	True returns only the passages that answer each term, about a tenth of the text of full pages: prefer it unless whole pages are needed. False returns full pages. Left out, the server's MCPSURFR_DEEP_RESEARCH_MODE decides (pages by default).
`include_urls`	No	Whether to include each page's source URL.
`max_passages`	No	Passages to return in passages mode, shared across terms. Default 12.
`search_terms`	Yes	2-5 specific, related search queries covering different angles. Example: ["postgres query planner", "postgres index types", "EXPLAIN ANALYZE tutorial"]
`top_k_per_term`	No	Number of top-ranked results to keep per search term per backend.
`exclude_domains`	No	Never results from these sites. Example: ["pinterest.com"]
`include_domains`	No	Only results from these sites, subdomains included. Example: ["python.org", "stackoverflow.com"]
`num_results_per_term`	No	Number of results to rank per search term per backend.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.2.3Oct 30, 2026

addedInput schema / properties / max_passages

Added value: +{
+  "default": 12,
+  "description": "Passages to return in passages mode, shared across terms. Default 12.",
+  "type": "integer"
+}

addedInput schema / properties / passages

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "True returns only the passages that answer each term, about a\ntenth of the text of full pages: prefer it unless whole pages are needed. False returns\nfull pages. Left out, the server's MCPSURFR_DEEP_RESEARCH_MODE decides (pages by default)."
+}

Changed5 schema fields changedv1.2.0Oct 29, 2026

addedInput schema / properties / exclude_domains

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Never results from these sites. Example: [\"pinterest.com\"]"
+}

addedInput schema / properties / include_domains

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only results from these sites, subdomains included.\nExample: [\"python.org\", \"stackoverflow.com\"]"
+}

addedInput schema / properties / news

Added value: +{
+  "default": false,
+  "description": "Search news articles instead of the web. Results then carry their published\n\"date\". News backends: auto, bing, duckduckgo, yahoo. Pair with recency for current events.",
+  "type": "boolean"
+}

addedInput schema / properties / recency

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "day",
+        "week",
+        "month",
+        "year"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Applied to every term. Only results from the past \"day\", \"week\", \"month\" or \"year\"."
+}

addedInput schema / properties / region

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Region-language code like \"us-en\", \"uk-en\" or \"de-de\". Default: ddgs's own (us-en)."
+}

Changed5 schema fields changedv1.1.1Oct 23, 2026

changedInput schema / properties / backends / description

Previous value: -"List of search backends to use. Defaults to [\"duckduckgo\", \"google\"].\n                 Can include: bing, brave, duckduckgo, google, grokipedia, \n                 mojeek, yandex, yahoo, wikipedia. If None, uses default."New value: +"Backends to use. Defaults to [\"auto\"]. Unknown names are skipped with a warning."

changedInput schema / properties / include_urls / description

Previous value: -"Whether to include URLs in the results."New value: +"Whether to include each page's source URL."

changedInput schema / properties / num_results_per_term / description

Previous value: -"Number of results to fetch per search term per backend."New value: +"Number of results to rank per search term per backend."

changedInput schema / properties / search_terms / description

Previous value: -"List of search terms to research. Provide multiple \n                      related search queries for comprehensive coverage.\n                      Example: [\"machine learning fundamentals\", \"neural networks\", \"deep learning best practices\"]"New value: +"2-5 specific, related search queries covering different angles.\n                      Example: [\"postgres query planner\", \"postgres index types\", \"EXPLAIN ANALYZE tutorial\"]"

changedInput schema / properties / top_k_per_term / description

Previous value: -"Number of top scored results to keep per search term per backend."New value: +"Number of top-ranked results to keep per search term per backend."

Changed5 schema fields changedv1.0.4Jun 10, 2026

addedInput schema / properties / backends / description

Added value: +"List of search backends to use. Defaults to [\"duckduckgo\", \"google\"].\n                 Can include: bing, brave, duckduckgo, google, grokipedia, \n                 mojeek, yandex, yahoo, wikipedia. If None, uses default."

addedInput schema / properties / include_urls / description
```
Added value: +"Whether to include URLs in the results."
```

addedInput schema / properties / num_results_per_term / description

Added value: +"Number of results to fetch per search term per backend."

addedInput schema / properties / search_terms / description

Added value: +"List of search terms to research. Provide multiple \n                      related search queries for comprehensive coverage.\n                      Example: [\"machine learning fundamentals\", \"neural networks\", \"deep learning best practices\"]"

addedInput schema / properties / top_k_per_term / description

Added value: +"Number of top scored results to keep per search term per backend."

Addedv1.0.1May 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the readOnly and openWorld annotations, the description discloses the full pipeline: each term is searched on each backend, results are locally re-ranked by relevance, duplicates are removed, and best pages are fetched as text. It also explains blocked-engine behavior, warnings for empty engines, and automatic retry with auto when all chosen engines are empty.

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

Conciseness5/5

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

The description is front-loaded with the core research workflow and then uses a compact backend list to convey selection guidance. Every section earns its place, and the structure makes the default and fallback behavior easy to scan.

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?

Given the 12-parameter schema, full parameter descriptions, output schema, and read-only/open-world annotations, the description supplies the missing operational context: the multi-backend search pipeline, ranking, deduplication, page fetching, and engine fallback behavior. An agent has enough information to invoke this complex tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents most parameters in detail. The description still adds meaningful semantics for the backends parameter by explaining the practical behavior of auto, brave, wikipedia, and commonly blocked engines, which goes beyond the schema's brief default/unknown-name note.

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?

The description states a specific verb and resource: research a topic across multiple search terms and engines, then rank, deduplicate, and fetch pages. This is clearly distinguishable from a simple search or URL reader because it describes a multi-query, multi-backend research pipeline.

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

Usage Guidelines4/5

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

The description gives clear contextual guidance for backend selection: auto is most reliable, brave is fast, wikipedia suits exact article lookups, and several engines are often blocked with fallback to auto. It does not explicitly compare against sibling tools like search or rag_search_ddgs, so it lacks named alternatives or when-not-to-use guidance.

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

Deploy Server