google-surf-mcp

by HarimxChoi

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Parallel Web Search and Extract

search_parallel

Run 2-12 live web searches in parallel and extract full text, PDFs, or GitHub content into ranked results.

Instructions

PRIMARY MULTI-QUERY LIVE DISCOVERY AND CONTENT INGESTION TOOL. ALWAYS PERFORMS MULTIPLE LIVE WEB SEARCHES. With research enabled, one local broker lets multiple MCP sessions query the same knowledge base concurrently and orders writes safely. Use this tool only when 2-12 new external queries are required. Providing project_id adds stored evidence but never makes the searches local-only. When the task requires broad discovery plus reading public web pages, PDFs, papers, or GitHub repositories, set extract_mode=abstract or full in this call. Do not download public PDFs, clone repositories, or invoke local parsers first. Select extract_mode=full, not abstract, when the user asks to read originals, full text, document bodies, or code, or to compare source contents. Use extract separately only when the exact public URL is already known and no new discovery is required. Use general repository tools only for editing, building, testing, or full Git history. For stored project knowledge without live web discovery, use project_memory_search. Each query limit accepts integers from 1 to 20. Call-wide extract_limit accepts 1-20 with default 12 for abstract, and 1-10 with default 10 for full. Final results use one call-wide bounded response budget after ranking; at most 36 ranked rows are returned across query groups and full captured bodies remain local. Use extract on one selected URL when longer response text is explicitly required. The response includes applied, skipped, truncated, total_chars, and a bounded remaining_urls list. GitHub none mode reads the README; abstract and full can sparse-index eligible repositories with Tree-sitter. With research enabled and project_id set, each query fuses live, exact, BM25, vector, code, and graph lanes through RRF and one reranker. With research disabled, each query independently fuses provider order and query BM25 rank through a lightweight in-memory RRF reranker without opening local storage or loading the vector model. research_context returns prior project searches; capture retains data lineage and include_project_ids uses versioned ontology and verified cross-project schema/entity links. Extracted bodies become evidence while unread hits remain metadata. Native Chrome uses one authenticated local broker across MCP sessions and keeps one hidden process with up to four reusable tabs. Query starts are staggered and each tab continuously consumes the remaining queue. SearchApi fallback replaces failed queries individually.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results per query. Integer 1-20, default 10.
`queries`	Yes	2-12 independent live queries.
`max_chars`	No	Maximum returned characters per extracted result in response_content=full. Defaults to 1500 for abstract and 50000 for full.
`project_id`	No	Project memory id.
`session_id`	No	Stable host task id. Reuses the same project session after restart.
`extract_mode`	No	Content depth in this search call. Use none only when titles and snippets are enough, abstract for relevance evidence, and full when the user asks to read originals, full text, document bodies, or code, or to compare source contents. Use abstract or full here instead of following search with separate extraction, PDF download, or repository clone. For GitHub results, none reads the README; abstract and full use the same repository eligibility gate but index different source amounts.	none
`extract_limit`	No	Call-wide maximum unique result URLs to extract. Integer 1-20, default 12 for abstract; full defaults to and allows at most 10.
`memory_handle`	No	Reuse the handle returned by a prior project-aware call.
`session_intent`	No	Current durable task intent. A changed value creates an immutable revision.
`response_content`	No	Controls only returned bodies. summary is the default and returns 1500-character evidence excerpts; full returns up to max_chars. Research storage keeps the full captured text in deterministic chunks.	summary
`include_project_ids`	No	Additional read-only projects joined through ontology-aligned schema and identity links. New records stay in project_id.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`meta`	No
`error`	No
`memory`	No
`results`	No
`elapsed_ms`	No
`memory_handle`	No
`research_context`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv1.1.3Sep 11, 2026
- addedOutput schema / properties / error / properties / cancel_reason
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / error / properties / phase
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / error / properties / request_id
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / results / items / properties / body_handle
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / results / items / properties / index_freshness
```
Added value: +{
+  "enum": [
+    "current",
+    "stale"
+  ],
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / results / items / properties / record_id
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / results / items / properties / revision_id
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / results / items / properties / source_span
```
Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "end": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "start": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "start",
+    "end"
+  ],
+  "type": "object"
+}
```

Changed1 schema field changedv1.0.4Sep 2, 2026

changedInput schema / properties / extract_mode / description

Previous value: -"Content depth in this search call. Use abstract or full during research instead of following search with separate extract calls. For GitHub results, none reads the README; abstract and full use the same repository eligibility gate but index different source amounts."New value: +"Content depth in this search call. Use none only when titles and snippets are enough, abstract for relevance evidence, and full when the user asks to read originals, full text, document bodies, or code, or to compare source contents. Use abstract or full here instead of following search with separate extraction, PDF download, or repository clone. For GitHub results, none reads the README; abstract and full use the same repository eligibility gate but index different source amounts."

Changed8 schema fields changedv1.0.2Sep 1, 2026

removedInput schema / properties / extract_limit / default
```
Removed value: -5
```

changedInput schema / properties / extract_limit / description

Previous value: -"Maximum unique result URLs to extract. For parallel search this is one call-wide limit, not a per-query limit."New value: +"Call-wide maximum unique result URLs to extract. Integer 1-20, default 12 for abstract; full defaults to and allows at most 10."

changedInput schema / properties / extract_limit / maximum
```
Previous value: -10New value: +20
```

changedInput schema / properties / limit / description

Previous value: -"Max results per query."New value: +"Maximum results per query. Integer 1-20, default 10."

changedInput schema / properties / max_chars / description

Previous value: -"Maximum characters per extracted result. Defaults to 1500 for abstract and 50000 for full."New value: +"Maximum returned characters per extracted result in response_content=full. Defaults to 1500 for abstract and 50000 for full."

addedInput schema / properties / response_content

Added value: +{
+  "default": "summary",
+  "description": "Controls only returned bodies. summary is the default and returns 1500-character evidence excerpts; full returns up to max_chars. Research storage keeps the full captured text in deterministic chunks.",
+  "enum": [
+    "summary",
+    "full"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / results / items / properties / source_length
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / truncated
```
Added value: +{
+  "type": "boolean"
+}
```

Changed43 schema fields changedv1.0.0Aug 28, 2026

addedInput schema / properties / extract_limit

Added value: +{
+  "default": 5,
+  "description": "Maximum unique result URLs to extract. For parallel search this is one call-wide limit, not a per-query limit.",
+  "maximum": 10,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / extract_mode

Added value: +{
+  "default": "none",
+  "description": "Content depth in this search call. Use abstract or full during research instead of following search with separate extract calls. For GitHub results, none reads the README; abstract and full use the same repository eligibility gate but index different source amounts.",
+  "enum": [
+    "none",
+    "abstract",
+    "full"
+  ],
+  "type": "string"
+}

addedInput schema / properties / include_project_ids

Added value: +{
+  "description": "Additional read-only projects joined through ontology-aligned schema and identity links. New records stay in project_id.",
+  "items": {
+    "maxLength": 64,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 8,
+  "type": "array"
+}

addedInput schema / properties / max_chars

Added value: +{
+  "description": "Maximum characters per extracted result. Defaults to 1500 for abstract and 50000 for full.",
+  "maximum": 50000,
+  "minimum": 200,
+  "type": "integer"
+}

addedInput schema / properties / memory_handle

Added value: +{
+  "description": "Reuse the handle returned by a prior project-aware call.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

addedInput schema / properties / project_id

Added value: +{
+  "description": "Project memory id.",
+  "maxLength": 64,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / queries / description

Previous value: -"2-10 queries to run concurrently."New value: +"2-12 independent live queries."

addedInput schema / properties / queries / items / maxLength
```
Added value: +400
```
addedInput schema / properties / queries / items / minLength
```
Added value: +1
```
changedInput schema / properties / queries / maxItems
```
Previous value: -10New value: +12
```
changedInput schema / properties / queries / minItems
```
Previous value: -1New value: +2
```

addedInput schema / properties / session_id

Added value: +{
+  "description": "Stable host task id. Reuses the same project session after restart.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / session_intent

Added value: +{
+  "description": "Current durable task intent. A changed value creates an immutable revision.",
+  "maxLength": 2000,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / memory
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / memory_handle
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / research_context

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "prior_searches": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "query": {
+            "type": "string"
+          },
+          "relation": {
+            "enum": [
+              "same",
+              "related",
+              "recent"
+            ],
+            "type": "string"
+          },
+          "results": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "searched_at": {
+            "type": "string"
+          },
+          "surface": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "query",
+          "relation",
+          "searched_at",
+          "results"
+        ],
+        "type": "object"
+      },
+      "maxItems": 3,
+      "type": "array"
+    }
+  },
+  "required": [
+    "prior_searches"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / results / items / properties / provider / enum

Previous value: -[
-  "browser",
-  "searchapi"
-]New value: +[
+  "browser",
+  "searchapi",
+  "local"
+]

addedOutput schema / properties / results / items / properties / results / items / properties / authors
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / canonical_url
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / content
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / created_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / creator
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / document_id
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / doi
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / excerpt
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / extract_error
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / results / items / properties / extraction_quality

Added value: +{
+  "enum": [
+    "full_text",
+    "abstract",
+    "meta_abstract",
+    "metadata_only"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / results / items / properties / fresh_web
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / is_pdf
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / keywords
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / language
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / length
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / modified_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / page_count
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / producer
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / project_ids
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / publication
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / results / items / properties / published_at
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / results / items / properties / retrieval_families

Added value: +{
+  "items": {
+    "enum": [
+      "exact",
+      "bm25",
+      "vector",
+      "graph"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / results / items / properties / results / items / properties / score
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / results / items / properties / results / items / properties / source_family

Added value: +{
+  "enum": [
+    "live",
+    "document",
+    "code",
+    "graph"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / results / items / properties / subject
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / results / items / properties / year

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed3 schema fields changedv0.8.0Aug 12, 2026
- addedOutput schema / properties / results / items / properties / degraded_reasons
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
- addedOutput schema / properties / results / items / properties / fallback_reason
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / results / items / properties / provider
```
Added value: +{
+  "enum": [
+    "browser",
+    "searchapi"
+  ],
+  "type": "string"
+}
```
Addedv0.6.5May 27, 2026
Removedv0.6.1May 21, 2026
Addedv0.5.2May 18, 2026
Removedv0.5.1May 18, 2026
Addedv0.4.8May 16, 2026
Removedv0.4.7May 15, 2026

Changed6 schema fields changedv0.3.5May 14, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / properties / limit / default
```
Added value: +10
```

changedInput schema / properties / limit / description

Previous value: -"Max results per query"New value: +"Max results per query."

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / queries / description

Previous value: -"Queries"New value: +"2-10 queries to run concurrently."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "elapsed_ms": {
+      "type": "number"
+    },
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "retry_after_ms": {
+          "type": "number"
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "user_action": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message",
+        "retryable"
+      ],
+      "type": "object"
+    },
+    "meta": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "query": {
+            "type": "string"
+          },
+          "results": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "description": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "title",
+                "url",
+                "description"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "query",
+          "results"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

First observedv0.3.2May 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations are minimal (readOnlyHint false, openWorldHint true, idempotentHint false), so the description carries the full burden. It discloses writes ('orders writes safely'), concurrency ('one local broker lets multiple MCP sessions query the same knowledge base concurrently'), fallback behavior ('SearchApi fallback replaces failed queries individually'), and result bounds ('at most 36 ranked rows are returned'). This far exceeds what annotations provide and is fully consistent with them.

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

Conciseness3/5

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

The description is a single dense paragraph exceeding 300 words. While every sentence adds substantive information, the lack of paragraph breaks or bullets makes it harder to scan. The content is front-loaded with the primary purpose, but the wall of text could be better structured without losing information. It is not concise, though it is thorough.

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?

With 11 parameters, an output schema, and complex behavioral nuances (research modes, extract modes, browser fallback, response budgets), the description covers all essential aspects. It explains return fields ('applied, skipped, truncated, total_chars, and a bounded remaining_urls list'), clarifies modes, and addresses edge cases like project_id not making searches local-only. An agent can confidently invoke this 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% and parameter descriptions are already detailed. The description adds meaningful context beyond the schema, such as clarifying the relationship between extract_mode and extract_limit, explaining that 'Use abstract or full here instead of following search with separate extraction, PDF download, or repository clone,' and detailing the response budget. This adds value beyond the schema, though not every nuance is covered.

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 opens with a clear statement of what the tool does: 'PRIMARY MULTI-QUERY LIVE DISCOVERY AND CONTENT INGESTION TOOL. ALWAYS PERFORMS MULTIPLE LIVE WEB SEARCHES.' It also distinguishes itself from siblings by specifying when to use it: 'Use this tool only when 2-12 new external queries are required.' This makes its purpose unambiguous and clearly differentiated from extract, project_memory_search, and repository tools.

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?

The description provides explicit usage guidance: 'Use this tool only when 2-12 new external queries are required,' 'Use extract separately only when the exact public URL is already known and no new discovery is required,' and 'Use general repository tools only for editing, building, testing, or full Git history.' It also names alternatives like project_memory_search for stored knowledge without live discovery. This is comprehensive and actionable.

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

Deploy Server