google-surf-mcp
Server Quality Checklist
Latest release: v0.8.0
- Disambiguation5/5
Each tool has a clearly distinct purpose: single search, scholar search, parallel search, URL extraction, combined search+extract, and health status. The combined search_extract tool could be confused as a mere composition, but its description explicitly frames it as a one-shot enrichment workflow, eliminating ambiguity.
Naming Consistency4/5Most tools follow a consistent verb_noun snake_case pattern (search, scholar_search, search_parallel, extract, search_extract). The 'health' tool is a noun and deviates from the verb-led pattern, but it is a single outlier and the names remain predictable.
Tool Count5/5With 6 tools, the set is well-scoped for a web search and extraction server. Each tool addresses a distinct workflow (single, scholarly, parallel, extraction, combined, and operational health), and none are redundant.
Completeness4/5The surface covers core search (web and academic), parallel queries, content extraction with mode options, a combined search-extract workflow, and server diagnostics. A minor gap is the lack of a dedicated batch-extract tool for arbitrary URLs, but search_extract and the existing modes cover most practical needs.
Average 4.4/5 across 6 of 6 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- 15 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior. The description adds useful behavioral context by mentioning the search implementation options (browser, SearchApi primary, fallback), caching TTL, and a max result limit. It does not contradict annotations, but could disclose failure modes or rate limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and each clause adds value: the search method, return fields, caching, and result limit. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the return fields are already documented. The description covers additional context like caching and fallback behavior. Missing details include potential error handling or performance implications, but overall it is sufficient for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter semantics beyond what the schema already states, such as the max limit and query operator support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Google Scholar and lists specific return fields (title, authors, publication, year, snippet, citation count, links). The name and description distinguish it from general search siblings like 'search' and 'search_parallel' by focusing on academic/scholarly content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it's for Google Scholar searches, which implies when to use it over general search tools. However, it does not explicitly state alternatives or when-not scenarios, so it lacks the explicit exclusion guidance required for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already marking readOnlyHint and openWorldHint, the description adds essential operational details: results cached for 24h, environment variable to bypass cache, provider fallback logic, and no API key requirement for the default browser provider. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary action, and every sentence delivers operational value (provider, return fields, cache, limits, auth). No unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with a small schema and output schema, the description covers all essential aspects: provider selection, caching and bypass, authentication, return fields, and limits. No major gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for both parameters, including default/max limit and query search operators. The description only reiterates the default limit and max, adding minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs a single Google search and specifies the return fields (title, URL, snippet). It distinguishes itself from sibling tools like search_parallel by emphasizing 'single' and from scholar_search by being a general Google search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use it, including default provider, caching behavior, and the cache-bypass instruction for breaking queries. However, it does not explicitly mention alternatives or state when not to use it versus siblings like search_parallel or scholar_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), the description reveals critical behavioral traits: per-page extract failures are isolated, the tool is disabled in cloud mode, and there are token/performance trade-offs between modes. These details add significant value and do not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, each earning its place: purpose, mode guidance, performance trade-off, failure isolation, and cloud-mode restriction. It is front-loaded with the main purpose and wastes no words on fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key operational aspects: combined search+extract, mode selection, token costs, failure handling, and cloud availability. An output schema exists (as indicated in context signals), so the description need not explain return values. It falls slightly short of a 5 by not mentioning rate limits or Google-specific limitations, but it is complete enough for effective tool selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds context about default modes and token efficiency, but these largely mirror the schema's own parameter descriptions (e.g., mode enum and max_chars). The description does not introduce new parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'One-shot Google search + parallel extract of the top results,' which is a specific verb-resource pairing that clearly distinguishes this tool from siblings like search (only search) and extract (only extract). The combined action is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use each mode: 'abstract' for a cheap survey and 'full' only when actual article texts are needed. It does not explicitly mention alternatives like 'for search-only use search' or warn against using this tool in cloud mode (beyond noting it is disabled), so it lacks explicit exclusions, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, openWorld, non-idempotent), the description adds valuable operational context: provider selection via SURF_SEARCH_PROVIDER, worker pool in browser mode, cloud mode for SearchApi, and per-query failure isolation in fallback mode. This significantly enriches the behavioral model and goes well beyond annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. The first sentence states the core function, the second details browser mode, and the third explains fallback behavior. Every sentence adds operational value, and the description is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description adequately covers the operational matrix: provider selection, modes, and fallback isolation. It lacks explicit comparison to siblings or details about environment variable configuration, but these are minor given the schema and annotations. Overall, the description is sufficiently complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value by emphasizing the 2-10 query range (schema allows min 1, so the description corrects/clarifies the intended batch size) and the parallel nature. However, the 'limit' parameter is not explained further than the schema, so the description does not fully compensate for any gaps, but it provides useful clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs 2-10 Google searches, specifying the resource and action. It also distinguishes from sibling tools like 'search' by explicitly indicating parallel execution and fallback behavior. The verb 'run' and resource 'Google searches' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batched searches but never explicitly states when to choose this tool over alternatives like 'search' or 'scholar_search'. No exclusions or alternative tool names are mentioned. The parallel search context is clear but not framed as a decision guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true, so the tool is safe. The description adds context about the specific status information returned, such as cascade.totalCaptchas and rateLimiter.queueSize, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no unnecessary words. It efficiently states purpose, usage scenario, and actionable guidance, making it front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only), the description covers all necessary aspects: what the tool returns, when to call it, and what to look for. The presence of an output schema further supports completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty with 100% coverage. Per guidelines, 0 parameters gives a baseline of 4. The description does not need to add parameter information since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns server status including cascade mode, rate-limiter usage, cache size, and config. It distinguishes itself from sibling tools (extract, search, etc.) by focusing on health diagnostics rather than data extraction or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this tool 'if searches start failing or returning empty' and suggests checking specific fields. It does not explicitly state when not to use it, but the usage scenario is clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and open-world. The description adds critical behavior: HTML via Mozilla Readability, academic PDF auto-detection methods, tiered depth, and errorInfo on failures. This goes well beyond annotations, providing rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of about 5 sentences, efficiently packing purpose, PDF detection, tiered modes, and error handling. No redundant information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, output schema exists), the description covers all key aspects: URL requirements, PDF detection, mode semantics, truncation, and error behavior. It is fully sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enhances understanding: explains abstract mode as cheap survey (~1500 chars, page 1 or meta description), full mode uses Playwright, and max_chars truncation. It adds use-case context that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one public URL -> clean article text', specifying the verb and resource. It distinguishes itself from siblings like 'search' and 'search_extract' by focusing on extraction from a given URL, not search. The mention of HTML and academic PDFs adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode: abstract for cheap survey/triage, full for full article. It also notes best-effort failure handling. However, it does not explicitly contrast with alternatives like 'search_extract' or specify when not to use the tool, missing some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/HarimxChoi/google-surf-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server