Skip to main content
Glama

Visibility Genies

Get search results

get_serp_results

Fetch Google's organic search results for 1-10 keywords, or with type their Google News articles or Google Images results. Use this to inspect who ranks for a query, verify competitors, compare SERPs across keywords, or gather source URLs before content planning. Returns the top depth organic rows per keyword (default 20). Estimated price per keyword: $0.01 at the default depth of 20, $0.04 at 100; News $0.01 for 20 articles, Images $0.01. Results are the SERP analysis Keyword Research shows: a keyword bought here opens free there, and a keyword it holds a current copy of, as deep as asked, is answered here at no charge for 12 hours. Per-keyword errors don't fail the batch. Each call may spend up to the workspace's agent spend limit ($2.00 unless changed in Settings) without asking: it holds at most its estimate plus a margin while it runs and is charged what it bought, never more. A call whose maximum is above the limit is refused before anything is bought, with its estimate and maximum: ask the user, then call again with approvedMaxCostUsd set to the amount they approved.

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": {
      "projectId": "<projectId>",
      "queries": "<queries>"
    },
    "name": "get_serp_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoWhich Google results: organic (default), news (Google News articles, billed per 10) or images (Google Images, billed per 100).
depthNoHow many SERP rows to crawl per keyword: a multiple of 10 from 10 to 100, default 20. Google has no offset, so a deeper crawl re-fetches the top too, and each further 10 results costs more. Only raise it when you need ranks past the top 20. Images ignores it and always returns up to 100.
queriesYes1-10 queries. Bulk-friendly: prefer this over multiple single-query calls.
projectIdYesRequired. The Visibility Genies project this call works in and is billed to. Call list_projects to find one.
approvedMaxCostUsdNoThe most, in USD, the user approved for this call after seeing its estimate and maximum. Only needed after a call was refused for costing more than the workspace's agent spend limit; never set it without asking the user.

Output Schema

NameRequiredDescriptionDefault
costNo
metaNo
resultsYes
savedResultIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

With readOnlyHint=false and openWorldHint=true already in annotations, the description still adds substantial behavior: per-call cost estimates at different depths, that partial keyword errors do not fail the batch, that a refused call must be re-issued with approvedMaxCostUsd after user approval, and that deeper crawls re-fetch the top rather than offsetting. These are real operational traits an agent cannot see in the schema. It is only slightly thin on what the response contains relative to a charged call.

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?

Structure is front-loaded: purpose first, then use cases, then return shape, then pricing and the spend-limit workflow. Every sentence carries information, though the billing and cached-result passage is dense and runs long for a single tool. It rewards a careful read but does not bury the lede.

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

Completeness4/5

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

Given an output schema and annotations that cover safety and world-openness, the description does not need to describe return rows, and it correctly focuses on cost, caching, and partial-failure behavior, which are the residual risks of a paid batch call. The one gap is that it never clarifies how this differs from the local SERP sibling, leaving an ambiguity an agent may hit at call time.

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 description coverage is 100%, so the baseline is 3, but the description adds cost semantics that the schema does not: $0.01 per keyword at default depth 20, $0.04 at 100, and separate News/Images pricing. It also frames the spend limit and the approvedMaxCostUsd approval loop that the schema only gestures at. The added meaning is about spend consequences rather than the parameters' value space, which keeps it from a 5.

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

Purpose4/5

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

The opening sentence names a specific verb (Fetch) and resource (Google's organic search results), and enumerates the three result types (organic/news/images) selectable via the `type` parameter. It is clear what the tool returns. It does not, however, distinguish itself from the sibling `get_local_serp_results`, so an agent must infer the organic-vs-local boundary from the names alone.

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 concrete use cases: inspecting who ranks for a query, verifying competitors, comparing SERPs across keywords, and gathering source URLs before content planning, plus a bulk-friendly nudge via the schema (1-10 queries). It also explains the relationship to Keyword Research data (already-owned keywords are free for 12 hours), which is genuine routing guidance. It stops short of any explicit when-not-to-use or a named alternative for a single-query lookup.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources