web-access

Search the web

web_access_search

Read-only

Search the public web for a caller-specified query and get ranked organic results back, plus whatever Google rendered around them: knowledge panel, AI overview, People also ask, local pack, videos, discussions. Google's images, videos, shopping, books, places and forums tabs are searched with searchType.

Primary use: pass a query string. There is no engine or domain-filter parameter; any other key is rejected before the call.

{ "query": "site:arxiv.org retrieval augmented generation" }

Optional targeting fields: country — ISO 3166-1 alpha-2 code the search runs from, e.g. GB (default US); language — results language tag such as en or pt-br.

{ "query": "plumbers", "country": "GB", "language": "en" }

To search from a place, send location, a place name such as London or Austin,Texas,United States (1 to 200 characters), or coordinates, { latitude, longitude, radius } with radius in meters (default 5000). The search is sent from that place's country; if both are sent, coordinates win. A name that cannot be placed fails, so send coordinates instead. On the results page the place biases results toward it. The effect is strongest for queries like plumbers near me, and it is not exact city targeting: a bare query such as coffee shops may still return results from a wider area.

{ "query": "plumbers near me", "location": "Austin,Texas,United States" }

Optional request field: searchCount — how many organic results you want, an integer from 1 to 300 (above 300 is rejected). Google is paged, up to 36 pages, until that many are in hand; each page is billed as one search. Many queries run out before 300: Google often has 100-200 results for a query, and you get what it has, with paging.complete: true and paging.stoppedBy: "end_of_results". Omit it for one page, about 10 results, and the response then carries no paging. Not with format: "raw", which returns one page per call.

{ "query": "construction consulting firms Ohio", "searchCount": 30 }

Optional Google field: searchType — the Google tab to search: "web" (the default, the ordinary results page), "images", "videos", "shopping", "books", "places" or "forums". There is no news tab. Each page fetched is billed as one search, as on the web.

videos, books, forums answer results, paged like the web; each video carries video (channel, platform, duration) and each book book (authors, published).
images answers images, about 100 a page, each with title, url (the page it is on), source, imageUrl (the file), imageWidth, imageHeight and thumbnail. It has 3 pages; searchCount up to 300 collects across them, usually about 270 images.
shopping answers products, the one page of about 55 product cards: title, productId, price and originalPrice as shown, merchant and moreMerchants, delivery, returns, rating, reviews. A card has no url. Google does not page this tab, so page must be 1.
places answers places, 20 businesses a page, paged like the web up to page 15. results is empty for images, shopping and places. dateRange, sortBy and verbatim apply to web, videos and forums only; format: "raw" and aiOverview to web only.

{ "query": "eames lounge chair", "searchType": "images", "searchCount": 150 }

Optional Google filters: safeSearch — true removes explicit results; includeOmittedResults — true includes the results Google hides as very similar to ones shown; autocorrect — false searches the query exactly as typed instead of Google's correction; restrictCountry — a two-letter code — keeps only pages from that country (unlike country, which sets where the search runs from); verbatim — true matches the words exactly, without synonyms. None combines with aiMode.

{ "query": "climate policy", "restrictCountry": "FR", "safeSearch": true }

Optional Google fields: page, dateRange and sortBy apply to Google results only; none of them combines with aiMode.

page — the results page to start from, an integer from 1 to 30 (default 1), where page N is the page Google shows as N. Without searchCount the response is that one page; with it, searchCount results are collected starting from that page. page and searchCount together stay within the first 300 results: (page - 1) × 10 + (searchCount, or 10 without it) must be at most 300. A page past Google's last result returns no results with zeroResults: true. Pages hold 8-10 results, so separate page calls can repeat or skip a result; for one list without repeats, send one call with searchCount.
dateRange — limit results to a publication window: one of "hour", "day", "week", "month" or "year" for the past hour through the past year, or { "from": "2024-01-01", "to": "2024-06-30" } for a custom range of ISO dates (YYYY-MM-DD), inclusive. Either end is optional but at least one is required, and from must not be after to.
sortBy — "relevance" (the default) or "date" for the newest results first.

{ "query": "heat pump grants", "page": 2, "dateRange": "month", "sortBy": "date" }

Optional Google field: format — "structured" (the default, recommended) for the parsed results above as JSON, or "raw" for the Google results page as HTML, one page per call. The response is then html, htmlBytes and htmlTruncated in place of results and the surfaces. This tool sends at most 60,000 bytes of markup per call and sets htmlTruncated: true when it cuts the page; for the whole page, call the HTTP API's POST /v1/search with format: "raw". Raw supports page only, not searchCount: a raw call with searchCount is rejected (the API answers 400), so ask for page N with page and send one call per page, each billed as one search. dateRange and sortBy work with raw. Not combinable with aiMode.

{ "query": "heat pump grants", "format": "raw" }

Optional request field: aiMode: true — ask Google AI Mode instead of the results page. The response is aiMode, one generated answer with the pages it cites and any products, places and videos it shows, and results is empty. Billed as one search. It cannot be combined with searchCount. If an AI Mode answer isn't available for the query, the call fails instead of returning a results page; retry, or search without it.

{ "query": "how does a heat pump work", "aiMode": true }

With aiMode, location or coordinates sets the place the answer is given for; the answer stays in language. Without either, a question that depends on where you are, such as today's weather, may be answered without a location.

{ "query": "best bakeries nearby", "aiMode": true, "coordinates": { "latitude": 48.8566, "longitude": 2.3522 } }

Optional request field: aiOverview: true — fill the AI Overview Google streams in after the results page loads. It makes a second, sequential fetch and adds latency: about 64% of results pages carry a streamed overview, and filling it adds about 2.8 s at p50 and 5.6 s at p90. A request with aiOverview: true costs 2x a normal search. Off by default: without it, an overview already present in the page is still returned, and a streamed one comes back as declined: true. Not combinable with aiMode.

{ "query": "best cushioned marathon shoes", "aiOverview": true }

Best for: a request that names no URL, or one that needs sources found before anything is read. Not for: a URL you already have — use web_access_fetch instead.

Query operators: quoted phrases and site: pass through to the search engine, so site:example.com pricing keeps results on that host. Other operators are untested — do not rely on them.

Returns: results, the ranked web documents, each with position (its place in this response, from 1), rank (its absolute Google rank, so page 3 starts at 21; Google only), title, url (the link to fetch; absent when Google hid the destination, and the result is still returned), snippet, displayUrl (Google's displayed URL line, empty when Google shows none, as on Reddit and YouTube results), displayText (the source line Google shows under the title, verbatim: a URL, engagement counts such as 20+ comments · 3 months ago, or other text), source when Google names the site (such as Reddit · r/buildapc), and timestamp when the engine dates it; and zeroResults, true when the engine itself reported no match (broaden the query; retrying will not help). Every other field is a surface Google rendered around the documents, present only when the page carried it, never merged into results, and only Google returns them:

entity — the knowledge panel for the one business or person the query named: title, subtitle, description with its descriptionSource, rating, reviews, website, labelled attributes (address, phone, hours…), social profiles, and unread module ids the read skipped. Often the whole answer for a query naming a single business, with results empty.
places — local-pack business listings: name, category, rating, reviews, address, phone, hours, url, mapsUrl. Also often answers a business query with results empty, so read entity and places before treating an empty results as no answer. With searchType: "places" it is the whole answer.
products — only with searchType: "shopping", the product cards described above.
overviews — Google's AI overviews. The first entry with no topic is the query's own summary; entries with a topic and question are the "Things to know" tabs; an entry with declined: true is a frame Google rendered and did not fill, which includes an overview Google streams in when aiOverview was not set. Each carries text (paragraphs and - list items on their own lines) and sources, the cited pages as { title, url } — fetch those to verify a claim.
peopleAlsoAsk — { question } entries; answers are not on the page. relatedSearches — query strings Google suggests.
answers — one single-purpose widget under localTime, currency, unitConversion, weather, translation, sports or flights.
spelling — { kind, query, asked }: substituted means the results are for the corrected query, suggested means they are for the query as typed.
ads (sponsored, with advertiser), videos and shortVideos (platform, channel, date, duration), discussions (site, forum, comments, age, excerpt), images (source; with searchType: "images" the whole answer, with the image file too), sitelinks (resultPosition of the result they sit under). Every entry has position and title, and url when its destination is known.
aiMode — only with aiMode: true: Google's AI Mode answer. text is plain text (one block per line, list items as - , table rows with cells joined by |); markdown is the same answer as Markdown, with headings, lists, tables and code; blocks is its structure in reading order, each { type } of paragraph, heading (text, level), list (ordered, items), table (header, rows, one cell per column) or code (text, language). sources are the cited pages as { title, url, snippet, source }: snippet is the passage quoted, source the site's name, and url is absent when a citation could not be resolved. When the answer shows them, products (title, price and oldPrice as displayed, merchant and moreSellers, rating, reviews, thumbnail, productId, url), places (name, category, rating, reviews, priceLevel, status, address, description, url) and videos (title, url, channel, duration, thumbnail). Every field but text and sources is absent when empty. Fetch the sources to verify a claim.
paging — { pages, complete, stoppedBy }, only when searchCount was sent. pages is how many results pages answered, each billed as one search. stoppedBy is why paging stopped: search_count (the count was reached), end_of_results (Google had no more), page_cap (the 36-page depth limit; Google may have more), page_failed (a later page could not be fetched) or deadline (the time budget ran out). complete is false only for page_failed and deadline, and results then holds what was collected. Surfaces describe the first page only; positions run on across pages.

A snippet is not the page, and an overview is not a source. To read a result, call web_access_fetch on its url before answering from it.

Requests must comply with destination policy, rate limits, and access controls.

Input Schema

Name	Required	Description
`page`	No	Google only: the results page to start from, an integer from 1 to 30 (default 1), where page N is the page Google shows as N. Without searchCount the response is that one page; with it, searchCount results are collected starting from that page. page and searchCount together stay within the first 300 results: (page-1)*10 + (searchCount, or 10) must be at most 300. A page past the last result returns zeroResults true. Pages hold 8-10 results, so separate page calls can repeat or skip a result; use one call with searchCount for a list without repeats. Not combinable with aiMode.
`query`	Yes	The search query. Be specific and descriptive for best results.
`aiMode`	No	Answer from Google AI Mode instead of the results page: the response carries aiMode (the answer as text, Markdown and structured blocks, its cited sources, and any products, places and videos it shows) and no results. Billed as one search; not combinable with searchCount.
`format`	No	Google only: 'structured' (the default) for parsed results, or 'raw' for html: the Google results page as HTML, one page per call. The tool sends at most 60,000 bytes of markup per call and sets htmlTruncated when it cuts the page. Raw supports page only: searchCount is rejected with raw, so send one call per page. dateRange and sortBy work with raw. Web only; not combinable with aiMode.
`sortBy`	No	Google only: 'relevance' (the default) or 'date' for the newest results first. Not combinable with aiMode.
`country`	No	ISO 3166-1 alpha-2 country code the search runs from, e.g. 'GB'. Defaults to US.
`language`	No	Results language tag: two letters, optionally a two-letter region, e.g. 'en' or 'pt-br'.
`location`	No	A place name such as 'London' or 'Austin,Texas,United States', 1 to 200 characters; the search is sent from its country. Google results are biased toward the place, most strongly for 'near me' queries, and may still cover a wider area; with aiMode the answer is given for that place. A name that cannot be placed is rejected, so send coordinates instead. coordinates win when both are sent.
`verbatim`	No	Google only: true matches the query's words exactly, without synonyms or stemming. Web, videos and forums only; not combinable with aiMode.
`dateRange`	No	Google only: limit results to a publication window. One of 'hour', 'day', 'week', 'month' or 'year' for the past hour through the past year, or {from, to} for a custom range of ISO dates (YYYY-MM-DD), inclusive; either end is optional but at least one is required, and from must not be after to. Not combinable with aiMode.
`aiOverview`	No	Fill the AI Overview Google streams in after the results page loads. A second, sequential fetch: about 64% of pages carry one, and filling it adds about 2.8 s at p50 and 5.6 s at p90. Costs 2x a normal search. Off by default; an overview already on the page is returned without it. Not combinable with aiMode.
`safeSearch`	No	Google only: true removes explicit results (SafeSearch). Not combinable with aiMode.
`searchType`	No	Google only: the tab to search. 'web' (the default) is the results page; 'videos', 'books' and 'forums' answer results; 'images' answers images (3 pages of about 100); 'shopping' answers products (one page of about 55, so page must be 1); 'places' answers places (20 a page). No news tab. Not combinable with aiMode.
`autocorrect`	No	Google only: false searches the query exactly as typed rather than Google's corrected spelling. On by default. Not combinable with aiMode.
`coordinates`	No	A point to search from, sent from the country it lies in. Google results are biased toward it, most strongly for 'near me' queries; with aiMode the answer is given for it. Wins over location when both are sent.
`searchCount`	No	Organic results wanted, an integer from 1 to 300; above 300 is rejected. Google is paged, up to 36 pages, until that many are in hand or it has no more, and each page is billed as one search. Omit for one page (about 10 results). Not with format raw, which returns one page per call; use page there.
`restrictCountry`	No	Google only: keep only results from pages in this country, a two-letter ISO code such as 'FR'. Unlike country, it does not change where the search runs from. Not combinable with aiMode.
`includeOmittedResults`	No	Google only: true includes the results Google omits as very similar to ones already shown. Not combinable with aiMode.

Output Schema

Name	Required	Description
`ads`	No	Sponsored results, kept apart from results.
`html`	No	Only with format raw: the Google results page as HTML, in place of results and the surfaces. Cut at a tag boundary when htmlTruncated is true.
`aiMode`	No	Google's AI Mode answer, only when aiMode was requested: text (plain), markdown, and blocks (paragraph, heading, list, table, code) in reading order; sources it cites, each with title, url (absent when the citation could not be resolved), snippet and source (the site's name); and products, places and videos when the answer shows them. Fields other than text and sources are absent when empty.
`entity`	No	The knowledge panel for the one business or person the query named.
`images`	No	Source pages of the Images block; with searchType images, the whole answer, each with imageUrl, imageWidth, imageHeight and thumbnail too.
`paging`	No	How a searchCount request was filled: pages that answered (each billed as one search); stoppedBy, why paging stopped (search_count, end_of_results, page_cap, page_failed or deadline); and complete, false only for page_failed and deadline, when results holds what was collected. Absent unless searchCount was sent.
`places`	No	Business listings from a local pack.
`videos`	No	Entries of the Videos block.
`answers`	No	Single-purpose widgets: local time, currency, unit conversion, weather, translation, sports, flights.
`results`	Yes	Ranked web documents, in engine order. Empty when the page carried no documents, and on a format raw search, which answers html instead.
`products`	No	Only with searchType shopping: the product cards, each with title, productId, price, originalPrice, merchant, moreMerchants, delivery, returns, rating and reviews; no url.
`spelling`	No	Google's correction of the query: substituted when results are for the corrected query, suggested when they are for the query as typed.
`htmlBytes`	No	Only with format raw: UTF-8 bytes of the whole page the API returned.
`overviews`	No	Google's AI overviews: the query's own first (no topic), then the Things to know tabs (topic and question); declined marks a frame Google did not fill. Each has text and the cited sources.
`sitelinks`	No	Sub-pages listed under a navigational result.
`discussions`	No	Threads from Discussions and forums.
`shortVideos`	No	Entries of the Short videos block.
`zeroResults`	Yes	True when the engine itself reported that nothing matched the query; broaden it rather than retry.
`htmlTruncated`	No	Only with format raw: true when html stops short of the page because the tool sends at most 60,000 bytes of markup per call. The HTTP API's format raw returns the whole page.
`peopleAlsoAsk`	No	Questions from the People also ask block; answers are not on the page.
`relatedSearches`	No	Query strings from the Related searches block.

Schema Changelog

Changes observed during successful MCP inspections.

Changed47 schema fields changedOct 8, 2026

addedInput schema / properties / aiMode

Added value: +{
+  "description": "Answer from Google AI Mode instead of the results page: the response carries aiMode (the answer as text, Markdown and structured blocks, its cited sources, and any products, places and videos it shows) and no results. Billed as one search; not combinable with searchCount.",
+  "type": "boolean"
+}

addedInput schema / properties / aiOverview

Added value: +{
+  "description": "Fill the AI Overview Google streams in after the results page loads. A second, sequential fetch: about 64% of pages carry one, and filling it adds about 2.8 s at p50 and 5.6 s at p90. Costs 2x a normal search. Off by default; an overview already on the page is returned without it. Not combinable with aiMode.",
+  "type": "boolean"
+}

addedInput schema / properties / autocorrect

Added value: +{
+  "description": "Google only: false searches the query exactly as typed rather than Google's corrected spelling. On by default. Not combinable with aiMode.",
+  "type": "boolean"
+}

addedInput schema / properties / coordinates

Added value: +{
+  "additionalProperties": false,
+  "description": "A point to search from, sent from the country it lies in. Google results are biased toward it, most strongly for 'near me' queries; with aiMode the answer is given for it. Wins over location when both are sent.",
+  "properties": {
+    "latitude": {
+      "description": "Latitude in decimal degrees, -90 to 90.",
+      "type": "number"
+    },
+    "longitude": {
+      "description": "Longitude in decimal degrees, -180 to 180.",
+      "type": "number"
+    },
+    "radius": {
+      "description": "How precise the point is, in meters: a whole number from 1 to 1000000. Omit for 5000.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "latitude",
+    "longitude"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedInput schema / properties / country

Added value: +{
+  "description": "ISO 3166-1 alpha-2 country code the search runs from, e.g. 'GB'. Defaults to US.",
+  "type": "string"
+}

addedInput schema / properties / dateRange

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "hour",
+        "day",
+        "week",
+        "month",
+        "year"
+      ],
+      "type": "string"
+    },
+    {
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "from": {
+          "description": "First day of the range, inclusive, YYYY-MM-DD.",
+          "format": "date",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "type": "string"
+        },
+        "to": {
+          "description": "Last day of the range, inclusive, YYYY-MM-DD.",
+          "format": "date",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  ],
+  "description": "Google only: limit results to a publication window. One of 'hour', 'day', 'week', 'month' or 'year' for the past hour through the past year, or {from, to} for a custom range of ISO dates (YYYY-MM-DD), inclusive; either end is optional but at least one is required, and from must not be after to. Not combinable with aiMode.",
+  "type": [
+    "string",
+    "object"
+  ]
+}

addedInput schema / properties / format

Added value: +{
+  "description": "Google only: 'structured' (the default) for parsed results, or 'raw' for html: the Google results page as HTML, one page per call. The tool sends at most 60,000 bytes of markup per call and sets htmlTruncated when it cuts the page. Raw supports page only: searchCount is rejected with raw, so send one call per page. dateRange and sortBy work with raw. Web only; not combinable with aiMode.",
+  "enum": [
+    "structured",
+    "raw"
+  ],
+  "type": "string"
+}

addedInput schema / properties / includeOmittedResults

Added value: +{
+  "description": "Google only: true includes the results Google omits as very similar to ones already shown. Not combinable with aiMode.",
+  "type": "boolean"
+}

addedInput schema / properties / language

Added value: +{
+  "description": "Results language tag: two letters, optionally a two-letter region, e.g. 'en' or 'pt-br'.",
+  "type": "string"
+}

addedInput schema / properties / location

Added value: +{
+  "description": "A place name such as 'London' or 'Austin,Texas,United States', 1 to 200 characters; the search is sent from its country. Google results are biased toward the place, most strongly for 'near me' queries, and may still cover a wider area; with aiMode the answer is given for that place. A name that cannot be placed is rejected, so send coordinates instead. coordinates win when both are sent.",
+  "type": "string"
+}

addedInput schema / properties / page

Added value: +{
+  "description": "Google only: the results page to start from, an integer from 1 to 30 (default 1), where page N is the page Google shows as N. Without searchCount the response is that one page; with it, searchCount results are collected starting from that page. page and searchCount together stay within the first 300 results: (page-1)*10 + (searchCount, or 10) must be at most 300. A page past the last result returns zeroResults true. Pages hold 8-10 results, so separate page calls can repeat or skip a result; use one call with searchCount for a list without repeats. Not combinable with aiMode.",
+  "maximum": 30,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / restrictCountry

Added value: +{
+  "description": "Google only: keep only results from pages in this country, a two-letter ISO code such as 'FR'. Unlike country, it does not change where the search runs from. Not combinable with aiMode.",
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}

addedInput schema / properties / safeSearch

Added value: +{
+  "description": "Google only: true removes explicit results (SafeSearch). Not combinable with aiMode.",
+  "type": "boolean"
+}

addedInput schema / properties / searchCount

Added value: +{
+  "description": "Organic results wanted, an integer from 1 to 300; above 300 is rejected. Google is paged, up to 36 pages, until that many are in hand or it has no more, and each page is billed as one search. Omit for one page (about 10 results). Not with format raw, which returns one page per call; use page there.",
+  "type": "integer"
+}

addedInput schema / properties / searchType

Added value: +{
+  "description": "Google only: the tab to search. 'web' (the default) is the results page; 'videos', 'books' and 'forums' answer results; 'images' answers images (3 pages of about 100); 'shopping' answers products (one page of about 55, so page must be 1); 'places' answers places (20 a page). No news tab. Not combinable with aiMode.",
+  "enum": [
+    "web",
+    "images",
+    "videos",
+    "shopping",
+    "books",
+    "places",
+    "forums"
+  ],
+  "type": "string"
+}

addedInput schema / properties / sortBy

Added value: +{
+  "description": "Google only: 'relevance' (the default) or 'date' for the newest results first. Not combinable with aiMode.",
+  "enum": [
+    "relevance",
+    "date"
+  ],
+  "type": "string"
+}

addedInput schema / properties / verbatim

Added value: +{
+  "description": "Google only: true matches the query's words exactly, without synonyms or stemming. Web, videos and forums only; not combinable with aiMode.",
+  "type": "boolean"
+}

removedOutput schema / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / ads

Added value: +{
+  "description": "Sponsored results, kept apart from results.",
+  "items": {
+    "properties": {
+      "advertiser": {
+        "type": "string"
+      },
+      "block": {
+        "type": "string"
+      },
+      "displayUrl": {
+        "type": "string"
+      },
+      "format": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "format",
+      "block"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / aiMode

Added value: +{
+  "description": "Google's AI Mode answer, only when aiMode was requested: text (plain), markdown, and blocks (paragraph, heading, list, table, code) in reading order; sources it cites, each with title, url (absent when the citation could not be resolved), snippet and source (the site's name); and products, places and videos when the answer shows them. Fields other than text and sources are absent when empty.",
+  "properties": {
+    "blocks": {
+      "items": {
+        "properties": {
+          "header": {
+            "items": {
+              "type": "string"
+            },
+            "type": [
+              "null",
+              "array"
+            ]
+          },
+          "items": {
+            "items": {
+              "type": "string"
+            },
+            "type": [
+              "null",
+              "array"
+            ]
+          },
+          "language": {
+            "type": "string"
+          },
+          "level": {
+            "type": "integer"
+          },
+          "ordered": {
+            "type": "boolean"
+          },
+          "rows": {
+            "items": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "null",
+                "array"
+              ]
+            },
+            "type": [
+              "null",
+              "array"
+            ]
+          },
+          "text": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "declined": {
+      "type": "boolean"
+    },
+    "markdown": {
+      "type": "string"
+    },
+    "places": {
+      "items": {
+        "properties": {
+          "address": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "priceLevel": {
+            "type": "string"
+          },
+          "rating": {
+            "type": "number"
+          },
+          "reviews": {
+            "type": "integer"
+          },
+          "status": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "products": {
+      "items": {
+        "properties": {
+          "merchant": {
+            "type": "string"
+          },
+          "moreSellers": {
+            "type": "boolean"
+          },
+          "oldPrice": {
+            "type": "string"
+          },
+          "price": {
+            "type": "string"
+          },
+          "productId": {
+            "type": "string"
+          },
+          "rating": {
+            "type": "number"
+          },
+          "reviews": {
+            "type": "integer"
+          },
+          "thumbnail": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "title"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "question": {
+      "type": "string"
+    },
+    "sources": {
+      "items": {
+        "properties": {
+          "snippet": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "text": {
+      "type": "string"
+    },
+    "topic": {
+      "type": "string"
+    },
+    "videos": {
+      "items": {
+        "properties": {
+          "channel": {
+            "type": "string"
+          },
+          "duration": {
+            "type": "string"
+          },
+          "thumbnail": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "title"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    }
+  },
+  "required": [
+    "text",
+    "sources"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / answers

Added value: +{
+  "description": "Single-purpose widgets: local time, currency, unit conversion, weather, translation, sports, flights.",
+  "properties": {
+    "currency": {
+      "properties": {
+        "amount": {
+          "type": "number"
+        },
+        "asOf": {
+          "type": "string"
+        },
+        "from": {
+          "type": "string"
+        },
+        "fromId": {
+          "type": "string"
+        },
+        "rate": {
+          "type": "number"
+        },
+        "result": {
+          "type": "number"
+        },
+        "source": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        },
+        "toId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "amount",
+        "from",
+        "result",
+        "to",
+        "text"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "flights": {
+      "properties": {
+        "cabin": {
+          "type": "string"
+        },
+        "departure": {
+          "type": "string"
+        },
+        "destination": {
+          "type": "string"
+        },
+        "options": {
+          "items": {
+            "properties": {
+              "airline": {
+                "type": "string"
+              },
+              "duration": {
+                "type": "string"
+              },
+              "price": {
+                "type": "string"
+              },
+              "stops": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "airline"
+            ],
+            "type": "object"
+          },
+          "type": [
+            "null",
+            "array"
+          ]
+        },
+        "origin": {
+          "type": "string"
+        },
+        "return": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "tripType": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "options"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "localTime": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "place": {
+          "type": "string"
+        },
+        "time": {
+          "type": "string"
+        },
+        "timezone": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "time"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "sports": {
+      "properties": {
+        "games": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "note": {
+                "type": "string"
+              },
+              "status": {
+                "type": "string"
+              },
+              "teams": {
+                "items": {
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    },
+                    "score": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "name",
+                    "score"
+                  ],
+                  "type": "object"
+                },
+                "type": [
+                  "null",
+                  "array"
+                ]
+              }
+            },
+            "required": [
+              "teams"
+            ],
+            "type": "object"
+          },
+          "type": [
+            "null",
+            "array"
+          ]
+        },
+        "team": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "team",
+        "games"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "translation": {
+      "properties": {
+        "detected": {
+          "type": "boolean"
+        },
+        "dictionary": {
+          "items": {
+            "properties": {
+              "meanings": {
+                "items": {
+                  "type": "string"
+                },
+                "type": [
+                  "null",
+                  "array"
+                ]
+              },
+              "partOfSpeech": {
+                "type": "string"
+              },
+              "term": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "term"
+            ],
+            "type": "object"
+          },
+          "type": [
+            "null",
+            "array"
+          ]
+        },
+        "source": {
+          "type": "string"
+        },
+        "sourceLanguage": {
+          "type": "string"
+        },
+        "sourceTransliteration": {
+          "type": "string"
+        },
+        "targetLanguage": {
+          "type": "string"
+        },
+        "translation": {
+          "type": "string"
+        },
+        "transliteration": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "sourceLanguage",
+        "detected",
+        "targetLanguage",
+        "source",
+        "translation"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "unitConversion": {
+      "properties": {
+        "category": {
+          "type": "string"
+        },
+        "formula": {
+          "type": "string"
+        },
+        "from": {
+          "type": "string"
+        },
+        "result": {
+          "type": "number"
+        },
+        "to": {
+          "type": "string"
+        },
+        "value": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "value",
+        "from",
+        "result",
+        "to"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "weather": {
+      "properties": {
+        "condition": {
+          "type": "string"
+        },
+        "forecast": {
+          "items": {
+            "properties": {
+              "condition": {
+                "type": "string"
+              },
+              "day": {
+                "type": "string"
+              },
+              "highC": {
+                "type": "number"
+              },
+              "highF": {
+                "type": "number"
+              },
+              "lowC": {
+                "type": "number"
+              },
+              "lowF": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "day",
+              "highF",
+              "highC",
+              "lowF",
+              "lowC"
+            ],
+            "type": "object"
+          },
+          "type": [
+            "null",
+            "array"
+          ]
+        },
+        "humidity": {
+          "type": "number"
+        },
+        "location": {
+          "type": "string"
+        },
+        "observed": {
+          "type": "string"
+        },
+        "precipitation": {
+          "type": "number"
+        },
+        "temperatureC": {
+          "type": "number"
+        },
+        "temperatureF": {
+          "type": "number"
+        },
+        "windKmh": {
+          "type": "string"
+        },
+        "windMph": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "temperatureF",
+        "temperatureC",
+        "precipitation",
+        "humidity",
+        "forecast"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / discussions

Added value: +{
+  "description": "Threads from Discussions and forums.",
+  "items": {
+    "properties": {
+      "age": {
+        "type": "string"
+      },
+      "comments": {
+        "type": "string"
+      },
+      "excerpt": {
+        "type": "string"
+      },
+      "forum": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "site": {
+        "type": "string"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / entity

Added value: +{
+  "description": "The knowledge panel for the one business or person the query named.",
+  "properties": {
+    "attributes": {
+      "items": {
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "label",
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "description": {
+      "type": "string"
+    },
+    "descriptionSource": {
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "profiles": {
+      "items": {
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "rating": {
+      "type": "number"
+    },
+    "reviews": {
+      "type": "integer"
+    },
+    "subtitle": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "unread": {
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "website": {
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "title",
+    "descriptionSource",
+    "website",
+    "attributes",
+    "profiles",
+    "unread"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / html

Added value: +{
+  "description": "Only with format raw: the Google results page as HTML, in place of results and the surfaces. Cut at a tag boundary when htmlTruncated is true.",
+  "type": "string"
+}

addedOutput schema / properties / htmlBytes

Added value: +{
+  "description": "Only with format raw: UTF-8 bytes of the whole page the API returned.",
+  "type": [
+    "null",
+    "integer"
+  ]
+}

addedOutput schema / properties / htmlTruncated

Added value: +{
+  "description": "Only with format raw: true when html stops short of the page because the tool sends at most 60,000 bytes of markup per call. The HTTP API's format raw returns the whole page.",
+  "type": [
+    "null",
+    "boolean"
+  ]
+}

addedOutput schema / properties / images

Added value: +{
+  "description": "Source pages of the Images block; with searchType images, the whole answer, each with imageUrl, imageWidth, imageHeight and thumbnail too.",
+  "items": {
+    "properties": {
+      "imageHeight": {
+        "type": "integer"
+      },
+      "imageUrl": {
+        "type": "string"
+      },
+      "imageWidth": {
+        "type": "integer"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "source": {
+        "type": "string"
+      },
+      "thumbnail": {
+        "type": "string"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / overviews

Added value: +{
+  "description": "Google's AI overviews: the query's own first (no topic), then the Things to know tabs (topic and question); declined marks a frame Google did not fill. Each has text and the cited sources.",
+  "items": {
+    "properties": {
+      "blocks": {
+        "items": {
+          "properties": {
+            "header": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "null",
+                "array"
+              ]
+            },
+            "items": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "null",
+                "array"
+              ]
+            },
+            "language": {
+              "type": "string"
+            },
+            "level": {
+              "type": "integer"
+            },
+            "ordered": {
+              "type": "boolean"
+            },
+            "rows": {
+              "items": {
+                "items": {
+                  "type": "string"
+                },
+                "type": [
+                  "null",
+                  "array"
+                ]
+              },
+              "type": [
+                "null",
+                "array"
+              ]
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      },
+      "declined": {
+        "type": "boolean"
+      },
+      "markdown": {
+        "type": "string"
+      },
+      "places": {
+        "items": {
+          "properties": {
+            "address": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "description": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "priceLevel": {
+              "type": "string"
+            },
+            "rating": {
+              "type": "number"
+            },
+            "reviews": {
+              "type": "integer"
+            },
+            "status": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      },
+      "products": {
+        "items": {
+          "properties": {
+            "merchant": {
+              "type": "string"
+            },
+            "moreSellers": {
+              "type": "boolean"
+            },
+            "oldPrice": {
+              "type": "string"
+            },
+            "price": {
+              "type": "string"
+            },
+            "productId": {
+              "type": "string"
+            },
+            "rating": {
+              "type": "number"
+            },
+            "reviews": {
+              "type": "integer"
+            },
+            "thumbnail": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "title"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      },
+      "question": {
+        "type": "string"
+      },
+      "sources": {
+        "items": {
+          "properties": {
+            "snippet": {
+              "type": "string"
+            },
+            "source": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      },
+      "text": {
+        "type": "string"
+      },
+      "topic": {
+        "type": "string"
+      },
+      "videos": {
+        "items": {
+          "properties": {
+            "channel": {
+              "type": "string"
+            },
+            "duration": {
+              "type": "string"
+            },
+            "thumbnail": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "title"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      }
+    },
+    "required": [
+      "text",
+      "sources"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / paging

Added value: +{
+  "description": "How a searchCount request was filled: pages that answered (each billed as one search); stoppedBy, why paging stopped (search_count, end_of_results, page_cap, page_failed or deadline); and complete, false only for page_failed and deadline, when results holds what was collected. Absent unless searchCount was sent.",
+  "properties": {
+    "complete": {
+      "type": "boolean"
+    },
+    "pages": {
+      "type": "integer"
+    },
+    "stoppedBy": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "pages",
+    "complete"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / peopleAlsoAsk

Added value: +{
+  "description": "Questions from the People also ask block; answers are not on the page.",
+  "items": {
+    "properties": {
+      "question": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "question"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / places

Added value: +{
+  "description": "Business listings from a local pack.",
+  "items": {
+    "properties": {
+      "address": {
+        "type": "string"
+      },
+      "category": {
+        "type": "string"
+      },
+      "hours": {
+        "type": "string"
+      },
+      "mapsUrl": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "phone": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "rating": {
+        "type": "number"
+      },
+      "reviews": {
+        "type": "integer"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "name"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / products

Added value: +{
+  "description": "Only with searchType shopping: the product cards, each with title, productId, price, originalPrice, merchant, moreMerchants, delivery, returns, rating and reviews; no url.",
+  "items": {
+    "properties": {
+      "delivery": {
+        "type": "string"
+      },
+      "merchant": {
+        "type": "string"
+      },
+      "moreMerchants": {
+        "type": "boolean"
+      },
+      "originalPrice": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "price": {
+        "type": "string"
+      },
+      "productId": {
+        "type": "string"
+      },
+      "rating": {
+        "type": "number"
+      },
+      "returns": {
+        "type": "string"
+      },
+      "reviews": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / relatedSearches

Added value: +{
+  "description": "Query strings from the Related searches block.",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / results / description

Added value: +"Ranked web documents, in engine order. Empty when the page carried no documents, and on a format raw search, which answers html instead."

removedOutput schema / properties / results / items / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / results / items / properties / book

Added value: +{
+  "properties": {
+    "authors": {
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "published": {
+      "type": "string"
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / results / items / properties / displayText
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / results / items / properties / rank
```
Added value: +{
+  "type": "integer"
+}
```
addedOutput schema / properties / results / items / properties / source
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / results / items / properties / video

Added value: +{
+  "properties": {
+    "channel": {
+      "type": "string"
+    },
+    "duration": {
+      "type": "string"
+    },
+    "platform": {
+      "type": "string"
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / properties / results / items / required

Previous value: -[
-  "position",
-  "title",
-  "url",
-  "snippet",
-  "displayUrl"
-]New value: +[
+  "position",
+  "title",
+  "snippet",
+  "displayUrl"
+]

addedOutput schema / properties / shortVideos

Added value: +{
+  "description": "Entries of the Short videos block.",
+  "items": {
+    "properties": {
+      "channel": {
+        "type": "string"
+      },
+      "date": {
+        "type": "string"
+      },
+      "duration": {
+        "type": "string"
+      },
+      "platform": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / sitelinks

Added value: +{
+  "description": "Sub-pages listed under a navigational result.",
+  "items": {
+    "properties": {
+      "description": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "resultPosition": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "resultPosition",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / spelling

Added value: +{
+  "description": "Google's correction of the query: substituted when results are for the corrected query, suggested when they are for the query as typed.",
+  "properties": {
+    "asked": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "query": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "query"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / videos

Added value: +{
+  "description": "Entries of the Videos block.",
+  "items": {
+    "properties": {
+      "channel": {
+        "type": "string"
+      },
+      "date": {
+        "type": "string"
+      },
+      "duration": {
+        "type": "string"
+      },
+      "platform": {
+        "type": "string"
+      },
+      "position": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "position",
+      "title"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / zeroResults

Added value: +{
+  "description": "True when the engine itself reported that nothing matched the query; broaden it rather than retry.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "results"
-]New value: +[
+  "results",
+  "zeroResults"
+]

First observedJul 14, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent), so the description carries real weight: billing semantics (each page billed as one search, aiOverview at 2x cost), latency figures (2.8s p50 / 5.6s p90), truncation behavior (60,000 bytes, htmlTruncated), hard failure modes (aiMode unavailable fails rather than falling back), and paging stop reasons ('page_failed', 'deadline', 'page_cap'). No contradiction with 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.

Conciseness4/5

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

It is a very long description, but it is front-loaded and strongly segmented with bold headers ('Primary use', 'Optional targeting fields', 'Best for', 'Not for', 'Returns') and inline JSON examples, so an agent can skim to the relevant block. The 'Returns' section restates much of what the existing output schema already carries, which is the main source of excess length.

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?

For an 18-parameter tool spanning seven search tabs and many optional result surfaces, the description covers query construction (which operators pass through), targeting, filtering, paging/billing, cost, failure behavior, and the crucial caveat that snippets and AI overviews are not sources to answer from. Nothing an agent needs to call it correctly 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?

Schema description coverage is 100%, so a baseline of 3 is warranted since the schema itself documents all 18 parameters. The description still adds value beyond the schema by spelling out cross-parameter interactions and precedence — coordinates win over location, (page-1)*10 + searchCount must stay within 300, searchCount is rejected with format raw — plus worked JSON examples for the common combinations.

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?

Opens with a specific verb and resource: 'Search the public web for a caller-specified query and get ranked organic results back', and enumerates the surfaces returned. It explicitly distinguishes itself from the sibling it is most likely to be confused with: 'Not for: a URL you already have — use web_access_fetch instead.' An agent can route between the two without opening either schema.

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?

Provides explicit 'Best for' and 'Not for' sections naming web_access_fetch as the alternative, and layers per-parameter when-to-use rules on top (when to send searchCount vs page, when location/coordinates apply, which filters are mutually exclusive with aiMode). Coverage of when and when-not is unusually complete.

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

All web-access tools Inspect

Try in Browser

Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

Glama MCP Gateway

Add one secure layer between your agents and this server.