google-surf-mcp

Overview Schema Source Related Servers Discussions Admin

Web Search and Extract

search

Perform live Google searches and ingest web content in one call. Fetch abstracts, full text, PDFs, or GitHub source directly, avoiding separate downloads or parsers.

Instructions

PRIMARY SINGLE-QUERY LIVE DISCOVERY AND CONTENT INGESTION TOOL. ALWAYS PERFORMS LIVE WEB SEARCH. 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 new external information from Google, public websites, papers, or repositories is required. When the task requires both finding and 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. Providing project_id also fuses stored project evidence with live results, but never makes this a local-only search. For stored project knowledge without live web discovery, use project_memory_search. limit accepts integers from 1 to 20. extract_limit accepts integers from 1 to 10, defaults to 5, and limits unique extracted URLs. Final results use one bounded response budget after ranking; 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, live web, exact, BM25, vector, code, and graph lanes are fused by RRF and one reranker. With research disabled, provider order and query BM25 rank are fused by a lightweight in-memory RRF reranker without opening local storage or loading the vector model. research_context returns up to three prior searches for deeper or adjacent follow-up work. Captured search, source, session, and project provenance form data lineage; extracted bodies become evidence while unread hits remain metadata. include_project_ids adds read-only cross-project retrieval through versioned ontology and verified schema/entity links without merging records. Browser search is the no-key default and SearchApi is the configured primary or fallback provider. Results are cached for 24h unless the TTL is disabled.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results. Integer 1-20, default 10.
`query`	Yes	Google search query. Use site: filters and quotes for exact match.
`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	Maximum unique result URLs to extract. Integer 1-10, default 5.
`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 the returned body. summary is the default and returns a 1500-character evidence excerpt; 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
`query`	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 / body_handle
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / index_freshness

Added value: +{
+  "enum": [
+    "current",
+    "stale"
+  ],
+  "type": "string"
+}

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

addedOutput schema / 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"
+}

Changed2 schema fields changedv1.0.6Sep 3, 2026

changedInput schema / properties / response_content / default
```
Previous value: -"full"New value: +"summary"
```

changedInput schema / properties / response_content / description

Previous value: -"Controls only the returned body. full returns up to max_chars; summary returns a 1500-character evidence excerpt. Research storage keeps the full captured text in deterministic chunks."New value: +"Controls only the returned body. summary is the default and returns a 1500-character evidence excerpt; full returns up to max_chars. Research storage keeps the full captured text in deterministic chunks."

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."

Changed6 schema fields changedv1.0.2Sep 1, 2026

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: +"Maximum unique result URLs to extract. Integer 1-10, default 5."

changedInput schema / properties / limit / description

Previous value: -"Max results (default 10)."New value: +"Maximum results. 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": "full",
+  "description": "Controls only the returned body. full returns up to max_chars; summary returns a 1500-character evidence excerpt. Research storage keeps the full captured text in deterministic chunks.",
+  "enum": [
+    "summary",
+    "full"
+  ],
+  "type": "string"
+}

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

Changed37 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"
+}

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"
+}

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

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

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

addedOutput schema / properties / results / items / properties / fresh_web
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / results / items / properties / is_pdf
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / results / items / properties / keywords

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / results / items / properties / language
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / length
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / modified_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / page_count
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / results / items / properties / producer
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / project_ids

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

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

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

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

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

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

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

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

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

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

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

Changed8 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 (default 10)"New value: +"Max results (default 10)."

changedInput schema / properties / limit / type

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

changedInput schema / properties / query / description

Previous value: -"Search query"New value: +"Google search query. Use site: filters and quotes for exact match."

addedInput schema / properties / query / maxLength
```
Added value: +400
```
addedInput schema / properties / query / minLength
```
Added value: +1
```

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"
+    },
+    "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"
+    }
+  },
+  "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 provide readOnlyHint=false, openWorldHint=true, and idempotentHint=false, but the description adds substantial behavioral context: it performs live web searches, caches results for 24h, describes response fields (applied, skipped, truncated, total_chars, bounded remaining_urls), explains research-mode fusion, and notes provenance tracking. None of this contradicts the annotations; it enriches them significantly.

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 dense single paragraph of over 300 words. While every sentence adds value, the lack of structure (no bullets, headings, or logical breaks) makes it hard to scan. It front-loads the primary purpose well, but the sheer length and monolithic formatting hurt readability. It is informative but not concise or well-organized, so a 3 is appropriate.

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 tool's complexity (11 parameters, enums, output schema, multiple modes), the description is remarkably complete. It covers use cases, extraction modes, research-mode behavior, caching, response structure, provenance, and sibling differentiation. The output schema exists, so return values are documented there. Nothing critical for an agent to correctly invoke the tool is missing.

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?

The input schema already documents all 11 parameters (coverage 100%), so the baseline is 3. However, the description adds meaning beyond the schema: it clarifies when to set extract_mode (abstract vs full), explains the relationship between extract_limit and unique URLs, details the effect of response_content, and describes how include_project_ids works with read-only cross-project retrieval. This goes beyond what the schema's individual descriptions provide, justifying a 4.

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 'PRIMARY SINGLE-QUERY LIVE DISCOVERY AND CONTENT INGESTION TOOL. ALWAYS PERFORMS LIVE WEB SEARCH.' which states a specific verb, resource, and scope. It explicitly contrasts itself with siblings like project_memory_search and extract, clarifying it is for external live information only. This removes any ambiguity about what the tool does.

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?

It gives explicit when-to-use criteria: 'Use this tool only when new external information from Google, public websites, papers, or repositories is required.' It also names alternatives and conditions, such as 'Use extract separately only when the exact public URL is already known' and 'For stored project knowledge without live web discovery, use project_memory_search.' This is textbook usage guidance with clear exclusions.

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

Deploy Server