Web research across search, Reddit, YouTube, local businesses, reviews, ad libraries and more. Every answer carries line-numbered citations; up to 1,000 rows per call without loading them into context.
Scored across 7 tools
Each tool has a clearly distinct role: search, fetch, read, grep, ask, poll, and SEO metrics. Even the three record-reading tools are sharply separated by purpose (full read, literal match, interpreted synthesis), so an agent should not confuse them.
Most tools follow a verb_noun pattern in snake_case: read_collected_records, grep_collected_records, ask_collected_records, get_task_results. The advanced_ prefix on search and fetch is a minor deviation but still readable and predictable.
Seven tools is a well-scoped set for a research and SEO analysis server. Each tool covers a distinct stage of the workflow from discovery to retrieval to analysis, with no redundant or padding tools.
The surface covers the full research loop: search, fetch, persist, read, filter, synthesize, and poll async results, plus SEO metrics. Minor gaps exist around managing or listing collected records directly, but these are workable through the search/fetch responses.
Fetch a webpage or any URL and get everything on it.
Content is saved for re-reading. It also reaches what a plain fetch cannot: the rendered page including JavaScript-generated text, the whole reply tree under a post, what was spoken in a video, the text of a PDF, what an image shows.
Best for: reading any known URL in full, including what a plain fetch misses.
Examples:
a news article → the article text, not the surrounding page
a thread with 300 replies → the whole tree, not the opening post
a 40-minute review video → transcript plus what commenters said about it
a long PDF report → text plus a line index to read only the relevant part
a site's sitemap or an RSS feed → the pages or entries it lists, with their dates
Use after advanced_web_search to open a result it found. Every relevant result carries mdOrHtmlDownloadUrl — a ready-to-use link that downloads that record as Markdown, no key attached, so it can be passed on as-is. Swap its ?type=md for ?type=html and the same link hands back the page's original HTML exactly as the site served it, markup and all — what an SEO reader needs and what Markdown drops; web-page fetches only.
If status: "running" is returned, poll get_task_results({ taskIds }).
| Name | Required | Description | Default |
|---|---|---|---|
| requests | Yes | One or more fetch requests; they run in parallel. | |
| isResearch | No | Default true. True means this call is part of an investigation: you will come back to what it collects, weigh it against other sources and cite it, so it is worth preparing the material for repeated use. Set false for a one-off question you are waiting on right now and will answer in this same turn — that trades the preparation for the fastest reply the source allows. | |
| maxWaitSec | No | How long to wait before returning `status: "running"` with a `taskId` to poll via `get_task_results`. Defaults to 50 seconds, which is also the server's ceiling — a larger value is clamped down to it, not honoured. Results stream as they are produced: each completed unit of work appears in `streaming.chunks[]` as soon as it is ready. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that content is saved for re-reading, that per-URL failures are reported in failed[] without aborting, and that async results come with status 'running' and streaming chunks. This goes well beyond the readOnlyHint and openWorldHint annotations, adding important operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured: a summary, a 'best for' line, concrete examples, search integration, and async handling. It is front-loaded with the core purpose and uses examples to clarify. For a tool of this complexity, the length is justified, though it could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the full lifecycle: fetching, saving, reading results via read_collected_records, async polling, and error handling. Even without an output schema, the agent knows what to do with the citable Data records and how to navigate each step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented, but the description adds practical meaning: it distinguishes objective (what you seek) from fetchOptions (how to read), explains isResearch's tradeoff between preparation and speed, and notes maxWaitSec clamping. This is beyond the schema's literal descriptions, though some redundancy exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a webpage or any URL and get everything on it' and differentiates from advanced_web_search by specifying it opens a known URL after search. It lists many source types (PDFs, videos, social networks), making its scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Best for: reading any known URL in full' and instructs to use it after advanced_web_search. It also guides on polling via get_task_results when status is 'running' and reading results with read_collected_records. Alternatives are clear, though it doesn't explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web and major platforms and get the content back.
Use whenever an answer needs current material rather than recall — what a page says now, what people posted about something, what a video covers, how a place is rated. One call reaches web results, social platforms, video, places, review sites, app stores and ad libraries at once, so a single tool covers what would otherwise take several.
Best for: finding current information, news, facts, people, companies, opinions and reviews, discussions and comments, what people report from use, company and product ratings, mobile apps, hotels and restaurants, video and places.
Examples:
"what's wrong with most standing desks" → discussions and reviews
"current pricing and terms for a service" → web results
"how did viewers react to that keynote" → video and social
"well-rated dentists near Alexanderplatz" → places
"what customers complain about in reviews of this company" → company reviews
"what users say about this app in the store" → app reviews
Each source's results are saved as a Data record you can read again later. The reply lists those records by id and title; open one with read_collected_records to see the individual hits with their URLs, then pass a URL to advanced_web_fetch to pull the full page behind it. Every relevant result carries mdOrHtmlDownloadUrl — a ready-to-use link that downloads that record as Markdown, no key attached, so it can be passed on as-is. Swap its ?type=md for ?type=html and the same link hands back the page's original HTML exactly as the site served it, markup and all — what an SEO reader needs and what Markdown drops; web-page fetches only.
If status: "running" is returned, poll get_task_results({ taskIds }).
| Name | Required | Description | Default |
|---|---|---|---|
| requests | Yes | One or more search requests. Each pairs a query with the sources to run it against; requests and sources run in parallel. | |
| isResearch | No | Default true. True means this call is part of an investigation: you will come back to what it collects, weigh it against other sources and cite it, so it is worth preparing the material for repeated use. Set false for a one-off question you are waiting on right now and will answer in this same turn — that trades the preparation for the fastest reply the source allows. | |
| maxWaitSec | No | How long to wait before returning `status: "running"` with a `taskId` to poll via `get_task_results`. Defaults to 50 seconds, which is also the server's ceiling — a larger value is clamped down to it, not honoured. Results stream as they are produced: each completed unit of work appears in `streaming.chunks[]` as soon as it is ready. |
Answer from collected records, with quotes tied to exact lines.
Extracts and synthesises across material too large to fit in context, and returns every claim traceable to a line range in the original. Use instead of summarising from memory whenever the evidence has to hold up — quotes come back with their locations, so they can be checked against the source.
Not for: exact wording or counting occurrences — grep_collected_records does that without an LLM call; or material small enough to read directly — use read_collected_records.
In quotes and both modes the output is quotes: [{ id: '{<uuid>}', index }] — one block per record, with index formatted like the index field of advanced_web_search / advanced_web_fetch results. Empty array when no quotable evidence is found. If status: "running" is returned, poll get_task_results({ taskIds }).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | `answer` for narrative prose, `quotes` for a per-record line-range index, `both` for both. | |
| query | Yes | The question to answer over the selected records. | |
| dataIds | Yes | One or more Data records to answer the question over. Each item is `{ id, version?, from?, to? }` — pass `{from, to}` to scope the citation to a specific line range; `version` is optional and defaults to latest. URLs are not accepted; collect them via `advanced_web_search` or `advanced_web_fetch` first. | |
| maxWaitSec | No | How long to wait before returning `status: "running"` with a `taskId` to poll via `get_task_results`. Defaults to 50 seconds, which is also the server's ceiling — a larger value is clamped down to it, not honoured. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the readOnlyHint annotation: it explains the asynchronous status: 'running' path with polling via get_task_results, the empty-array result when no quotable evidence exists, and the exact quote block format. This is far more than the annotation alone communicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well front-loaded and organized into purpose, usage, and output-format sections, but it repeats the same idea several times: line-tied quotes are mentioned in the opening line, the second sentence, and again in the third sentence. Each point is useful, but the redundancy is noticeable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully explains return shapes, empty results, line-range indexing format, and async polling. Given the tool's complexity — 4 parameters, 3 modes, async behavior, and no output schema — nothing necessary for a correct call or interpretation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is fully documented, so the baseline is 3; the description goes beyond it by tying mode values to concrete output shapes ('In quotes and both modes the output is quotes: [{ id... }]') and clarifying the polling contract for maxWaitSec. It does not deeply re-explain each parameter, but the schema already handles that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Answer from collected records, with quotes tied to exact lines.' It clearly distinguishes the tool from siblings by contrasting it with grep_collected_records and read_collected_records, and by emphasizing synthesis over exact matching or direct reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('material too large to fit in context', 'evidence has to hold up') and when not to ('exact wording or counting occurrences', 'material small enough to read directly'), naming the alternative tools for those cases. This gives an agent decisive routing criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Required after any call that returned status: running.
The task keeps working, but its results are not delivered until polled. The call waits for the next event — a new streaming chunk on any listed task, or a task settling — then returns the state of all listed tasks. Tasks settle one at a time: keep calling with the still-running ids to collect the rest (settledInThisCall lists the ones that just finished).
Streaming chunks from advanced_web_fetch, advanced_web_search and seo_metrics arrive in streaming.chunks; chunks already delivered are never redelivered. Act on partial chunks: fire follow-up calls in parallel and pass their new ids to the next get_task_results.
credits.spent is what was charged since the previous response for the same tasks — a running task keeps charging after the call that started it answers — so spent summed over that first response and every poll is the full cost.
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes | Ids of tasks that returned `status: "running"`. Up to 64 per call. | |
| maxWaitSec | No | Maximum seconds to wait for the next event. Both the default and the ceiling are the server's 50 seconds — a larger value is clamped down to it. Pass `0` for an immediate non-blocking read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint annotation, disclosing several behavioral traits: the call waits for the next event, tasks settle one at a time, chunks are never redelivered, and credits.spent is incremental since the previous response. It also explains the semantics of settledInThisCall and the streaming.chunks location. No contradiction with annotations, and the description adds 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but packed with essential operational details (polling, streaming, credits). It is front-loaded with the primary condition and then organizes information into clear paragraphs. While not every sentence is strictly necessary, the density justifies the length; it earns a 4 for being well-structured despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—polling, streaming, partial results, and cost accounting—the description is remarkably complete. It explains the wait behavior, the one-at-a-time settling, the streaming chunks from specific sibling tools, and the precise meaning of credits.spent. With no output schema, it also conveys the result structure (state, settledInThisCall, streaming.chunks). Nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of both parameters, including detailed descriptions for taskIds (ids that returned running, max 64) and maxWaitSec (default/clamp and 0 for immediate). The description adds minimal extra parameter semantics; it reinforces that taskIds must be running ids and mentions the default wait, but these are already in the schema. Thus a baseline 3 is appropriate, as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it is required after any call that returned status running, and it waits for events then returns the state of all listed tasks. It names the specific verb (get task results) and distinguishes from siblings like advanced_web_fetch and advanced_web_search, which are the task initiators. The phrase 'Required after any call that returned status: running' leaves no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Required after any call that returned status: running.' It also explains the polling pattern: keep calling with still-running ids, and how to act on partial chunks. It does not explicitly name alternative tools or say when not to use it, but the context makes it clear this is the only polling mechanism, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find and count matches across everything collected, without loading it.
Returns only matching lines with their line numbers — the records themselves never enter context. Use to count how often a theme recurs across many sources, or to locate the exact line ranges worth loading in full via read_collected_records. Matching is literal: use grep_collected_records for exact wording and counts, ask_collected_records when the question needs interpretation across records.
| Name | Required | Description | Default |
|---|---|---|---|
| regex | Yes | Pattern to search for across the selected records. | |
| dataIds | Yes | The Data records to scan. Each item is `{ id, version?, from?, to? }` — pass `{from, to}` to narrow the scan range within that record; emitted line numbers stay absolute. Required: scanning is always scoped to records you name. | |
| maxMatches | No | Cap on matches returned across all records (default 100, max 2000). When the cap is hit, every record with matches keeps representation — tighten the regex or scan fewer records. | |
| regexFlags | No | Standard JavaScript RegExp flags as one contiguous string, e.g. `"i"`, `"im"`, `"is"`. Common ones: `i` (case-insensitive), `m` (^/$ match line boundaries), `s` (dot matches newlines). Omit for the default: case-sensitive, single-line. Matching is per-line, so `g` has no effect. An invalid flag rejects the call with INVALID_REGEX. | |
| contextLines | No | Lines of context around each match (default 2); each window spans up to `2 × contextLines + 1` lines. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the operation is non-loading and that records never enter context, which is critical for context management. It also states matching is literal, directly informing expectations. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the core purpose in the first sentence, return behavior in the second, and usage guidance in the third. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, and usage guidance, and the schema fully documents all parameters. The only gap is that 'everything collected' could be misread as global scope until the schema clarifies dataIds is required; also output format is only summarized. Still, the combination of description and rich schema is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. The description adds general behavior (literal matching, returns lines/line numbers) but does not clarify parameter-specific semantics beyond what the schema already provides, such as regex flags or line-range behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: find and count matches across collected records without loading them. It explicitly distinguishes itself from `read_collected_records` (which loads full records) and `ask_collected_records` (which interprets), so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use this tool: for exact wording and counts, and for locating line ranges to load via `read_collected_records`. It also names the alternative (`ask_collected_records`) for interpretive questions, giving clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read collected records in full, or just the line ranges you need.
Records persist across turns, so nothing is fetched twice. Pass line ranges to bring only the relevant parts into context instead of an entire thread or transcript.
| Name | Required | Description | Default |
|---|---|---|---|
| dataIds | Yes | One or more Data records to render. Each item is `{ id, version?, from?, to? }` — pass `{from, to}` to scope rendering to a specific line range; `version` is optional and defaults to latest. A `to` past the end is clipped; a `from` past the end fails with `QUOTE_OUT_OF_BOUNDS`. URLs are not accepted; collect them via `advanced_web_search` or `advanced_web_fetch` first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description is not expected to repeat safety. It adds valuable behavioral context: records persist across turns (avoiding duplicate fetches) and reading brings content into context. This is beyond the annotation and aligns with read-only semantics. No contradictions; the description supports the readOnly hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and then a practical tip. Every sentence adds value—no filler, no redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive schema (covering edge cases and URL restrictions), the readOnly annotation, and the absence of an output schema, the description covers all necessary context. It explains persistence, context loading, and line-range usage. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed per-property explanations (id format, from/to defaults, clipping, QUOTE_OUT_OF_BOUNDS, version pinning). The description's mention of line ranges adds minimal semantics beyond the schema, as the schema already covers these behaviors. Baseline 3 applies since the schema carries the parameter documentation load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read collected records in full, or just the line ranges you need.' It identifies the specific verb (read) and resource (collected records), and the ability to scope to line ranges distinguishes it from search (grep) or fetching (advanced_web_fetch) siblings. The phrase 'Records persist across turns' further clarifies that this reads stored data, not new content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance: 'Pass line ranges to bring only the relevant parts into context instead of an entire thread or transcript.' This tells the agent when to use line ranges for efficiency. However, it does not explicitly name alternative tools or state when to choose this over siblings like grep_collected_records or ask_collected_records; such comparison is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer questions about search visibility and search demand — keywords, rankings, links, domains, and how interest in a subject moves over time and across a country.
Use when the question is about how a site or a market performs in search rather than about what a page says: which keywords a domain ranks for, which pages earn its traffic, who competes with it, what links to it, how a keyword's demand and difficulty compare, whether interest in a subject is rising or falling, and which of a country's regions search for it most.
Examples:
"keywords ahrefs.com ranks in the top 3 for, with real volume"
"which pages of this site bring the most organic traffic"
"who competes with this domain and how big are they"
"keyword ideas around link building that are not brutally competitive"
Ask in plain language. Do not write field names, operators or query syntax — the request is composed from your question, and what came back is described in the answer so you can check it matched what you meant.
Not for: what a specific page says (use advanced_web_fetch), or what people are posting right now (use advanced_web_search).
Results are stored as citable Data records — a large report comes back as a summary plus a line index, so read the parts you need with read_collected_records or search across them with grep_collected_records. Every relevant result carries mdOrHtmlDownloadUrl — a ready-to-use link that downloads that record as Markdown, no key attached, so it can be passed on as-is. Swap its ?type=md for ?type=html and the same link hands back the page's original HTML exactly as the site served it, markup and all — what an SEO reader needs and what Markdown drops; web-page fetches only.
If status: "running" is returned, poll get_task_results({ taskIds }).
| Name | Required | Description | Default |
|---|---|---|---|
| requests | Yes | One or more questions. Each pairs a question with the sources to ask it of; requests and sources run in parallel. | |
| isResearch | No | Default true. True means this call is part of an investigation: you will come back to what it collects, weigh it against other sources and cite it, so it is worth preparing the material for repeated use. Set false for a one-off question you are waiting on right now and will answer in this same turn — that trades the preparation for the fastest reply the source allows. | |
| maxWaitSec | No | How long to wait before returning `status: "running"` with a `taskId` to poll via `get_task_results`. Defaults to 50 seconds, which is also the server's ceiling — a larger value is clamped down to it, not honoured. Results stream as they are produced: each completed unit of work appears in `streaming.chunks[]` as soon as it is ready. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true; the description adds substantial behavior beyond that: async semantics (status:'running' → poll get_task_results), streaming chunks, results persisted as citable Data records with a line index, and the mdOrHtmlDownloadUrl ?type=md→?type=html swap. It also explains clamping of maxWaitSec rather than honoring oversized values. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, then operational details in a logical order. It is long, but the tool is complex and most paragraphs earn their place; the main cost is mild redundancy — the prose inventory of question types partly repeats the five examples and the sources enum in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complex tool (nested request objects, five source enums, async polling, streaming, download links) with no output schema, so the description must explain returns — and it does: summary plus line index, Data records with mdOrHtmlDownloadUrl, streaming.chunks[], and the running-status path. Coverage of the trends source's three limits appears both in schema and description. Nothing an agent needs to call or follow up on this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with richly described parameters, so the baseline is 3. The description adds value beyond the schema: it instructs the agent to speak in plain language and avoid syntax (directly shaping query/options), explains that requests and sources run in parallel, and clarifies the isResearch trade-off in operational terms. A modest but real increment over the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource — 'Answer questions about search visibility and search demand' — and enumerates the exact data kinds (keywords, rankings, links, domains, trends). It explicitly names the sibling tools it is not (advanced_web_fetch for page content, advanced_web_search for current posts), so an agent can distinguish it from all six siblings without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit 'Use when' test ('how a site or a market performs in search rather than about what a page says'), a 'Not for' section naming the alternatives, concrete example queries, and even routes follow-up behavior to read_collected_records/grep_collected_records. Nothing about when to pick this tool is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
advanced_web_search1 field changedInput schema / properties / requests / items / properties / sources / descriptionPrevious value: -"Which sources to search — several can run at once; pick from where that kind of material actually is. Web and news: `google` (organic results plus related searches), `duckduckgo` (a second index whose first page mostly does not overlap Google's — run both), `web-mentions` (where a phrase turns up across the web, one page per site with the passage around it; reaches far past a first page, strong on subjects and terms, weak on bare brand names), `google-news` (news coverage: headline, publisher and date, no article text). Research and work: `google-scholar` (papers with citation counts; can also list what cites a given paper), `google-patents` (patents; at most 500 per search), `google-jobs` (job openings; nothing anywhere in the EEA). Social and video: `reddit` (posts; one community, an ordering or a period are settings, not terms), `tiktok` (one feed at a time — videos matched on the terms, accounts, or the videos under a single tag; which of the three is a setting, as are an ordering and a period on the video feed), `threads` (up to 10 public posts; takes a topic term of two or three words, not a sentence — an unrecognised term returns nothing), `youtube` (videos; one country's edition at a time, with no way to sort or filter what comes back). Places and travel: `google-maps` (places — the query names a place or a category of place, not a sentence; not a source of product reviews, and reviews of a place come from `advanced_web_fetch` on its link), `business-listings` (every business of a kind in one place — up to 1000 separate addresses with rating, review count, hours and attributes, selected by category, city and rating floor rather than ranked by relevance), `tripadvisor` (hotels, restaurants and things to do in one named place at a time), `google-hotels` (properties priced for the dates named in `searchOptions`, or for a sample stay the results state), `google-flights` (one route on one day, one-way prices, searched by airport). Shopping: `amazon`, `walmart` (US store only) and `google-shopping` (one country's storefront) — product listings, not product pages. Apps and reputation: `google-play`, `app-store` (one national store each), `trustpilot` (companies and their review scores, worldwide). Ad libraries: `facebook-ads`, `linkedin-ads`, `tiktok-ads` and `google-ads` — which ads carry given words, or everything one company advertises — naming the advertiser is a setting, and doing so replaces the word search rather than narrowing it (`google-ads` only lists by advertiser and cannot search wording at all); none of them publishes what an ad cost or who saw it. Most sources read one country or store at a time. A market, an ordering, a period, or narrowing to a single community, account or seller are settings: say them in `searchOptions` and they reach the source through its own controls where it has them, instead of being searched for as words. Four sources answer with something whatever they are given: `google-shopping` returns unrelated products, `google-hotels` an unrelated town and `google-maps` unrelated places rather than nothing, and `tripadvisor` matches a place named only in the query as text inside venue names."New value: +"Which sources to search — several can run at once; pick from where that kind of material actually is. Web and news: `google` (organic results plus related searches), `duckduckgo` (a second index whose first page mostly does not overlap Google's — run both), `web-mentions` (where a phrase turns up across the web, one page per site with the passage around it; reaches far past a first page, strong on subjects and terms, weak on bare brand names), `google-news` (news coverage: headline, publisher and date, no article text). Research and work: `google-scholar` (papers with citation counts; can also list what cites a given paper), `google-patents` (patents; at most 500 per search), `google-jobs` (job openings; the country is a setting, the city stays in the terms). Social and video: `reddit` (posts; one community, an ordering or a period are settings, not terms), `tiktok` (one feed at a time — videos matched on the terms, accounts, or the videos under a single tag; which of the three is a setting, as are an ordering and a period on the video feed), `threads` (up to 10 public posts; takes a topic term of two or three words, not a sentence — an unrecognised term returns nothing), `youtube` (videos; one country's edition at a time, with no way to sort or filter what comes back). Places and travel: `google-maps` (places — the query names a place or a category of place, not a sentence; not a source of product reviews, and reviews of a place come from `advanced_web_fetch` on its link), `business-listings` (every business of a kind in one place — up to 1000 separate addresses with rating, review count, hours and attributes, selected by category, city and rating floor rather than ranked by relevance), `tripadvisor` (hotels, restaurants and things to do in one named place at a time), `google-hotels` (properties priced for the dates named in `searchOptions`, or for a sample stay the results state), `google-flights` (one route on one day, one-way prices, searched by airport). Shopping: `amazon`, `walmart` (US store only) and `google-shopping` (one country's storefront) — product listings, not product pages. Apps and reputation: `google-play`, `app-store` (one national store each), `trustpilot` (companies and their review scores, worldwide). Ad libraries: `facebook-ads`, `linkedin-ads`, `tiktok-ads` and `google-ads` — which ads carry given words, or everything one company advertises — naming the advertiser is a setting, and doing so replaces the word search rather than narrowing it (`google-ads` only lists by advertiser and cannot search wording at all); none of them publishes what an ad cost or who saw it. Most sources read one country or store at a time. A market, an ordering, a period, or narrowing to a single community, account or seller are settings: say them in `searchOptions` and they reach the source through its own controls where it has them, instead of being searched for as words. Four sources answer with something whatever they are given: `google-shopping` returns unrelated products, `google-hotels` an unrelated town and `google-maps` unrelated places rather than nothing, and `tripadvisor` matches a place named only in the query as text inside venue names."advanced_web_fetch1 field changedInput schema / properties / requests / items / properties / urls / descriptionPrevious value: -"Public HTTP(S) URLs to ingest. Each URL is handled according to what it points at: YouTube (transcript, metadata and the comment section), social networks (Reddit, X/Twitter, Facebook, Instagram, TikTok, LinkedIn, Threads, Bluesky, Pinterest, Twitch, Snapchat, Truth Social), Google Maps places (the place card — address, category, rating breakdown, hours, popular times, price, services, attributes and photo categories — plus its customer reviews with owner responses, the themes recurring across them and, on request, the updates the business publishes on its own profile), Trustpilot company pages and Tripadvisor listings (the summary with its rating and, where the site keeps one, its star breakdown, plus the customer reviews and any replies), Google Play and App Store app pages (the store listing — publisher, category, price, current version, update date — plus its user reviews), product pages on Amazon and Walmart and the listings `google-shopping` returns (price, sellers, specifications and the reviews the page carries; a Google listing opens only while it is still on that storefront's first page), Google Hotels property cards and Google Finance instrument pages (a hotel card is priced for a sample stay the answer states; an instrument comes with its published financial statements), Zillow home listings (asking price or rent, rooms, floor area, the specification table, price and tax history, and the schools serving the address; for sale, for rent, sold and off-market are told apart), Google Patents documents (claims in full, with the legal status) and Google Scholar author profiles (citation metrics and the author's works), PDFs (text extraction), images (visual description by a vision model). Video posts on TikTok, Instagram, Facebook and X also yield transcripts. A link to one ad reads that ad in all four ad libraries — Facebook (`/ads/library/?id=…`), LinkedIn (`/ad-library/detail/<id>`), TikTok (`library.tiktok.com/ads/detail/?ad_id=<number>`), Google (`adstransparency.google.com/advertiser/<AR…>/creative/<CR…>`) — adding every wording, per-country dates and destination that library publishes; ask in `fetchOptions` to have its creatives described. An address covering many ads — an advertiser page, a library hub, a search over it — is refused free of charge. Anything else is read as a web page. Per-URL failures (auth walls, dead links, blocked pages) are reported in `failed[]` without aborting the batch. Each URL is retrieved in full; a handful of well-chosen ones goes further than a long list. Each URL becomes a citable `Data` record with a title, a summary and a line index. Read the parts you need with `read_collected_records` — pass a line range, or omit it for the whole document."New value: +"Public HTTP(S) URLs to ingest. Each URL is handled according to what it points at: YouTube (transcript, metadata and the comment section), social networks (Reddit, X/Twitter, Facebook, Instagram, TikTok, LinkedIn, Threads, Bluesky, Pinterest, Twitch, Snapchat, Truth Social), Google Maps places (the place card — address, category, rating breakdown, hours, popular times, price, services, attributes and photo categories — plus its customer reviews with owner responses (in Google's own ranking, or newest first on request), the themes recurring across them and, on request, the updates the business publishes on its own profile), Trustpilot company pages and Tripadvisor listings (the summary with its rating and, where the site keeps one, its star breakdown, plus the customer reviews and any replies, narrowed to chosen star ratings on request), Google Play and App Store app pages (the store listing — publisher, category, price, current version, update date — plus its user reviews), product pages on Amazon and Walmart and the listings `google-shopping` returns (price, sellers, specifications and the reviews the page carries; a Google listing opens only while it is still on that storefront's first page), Google Hotels property cards and Google Finance instrument pages (a hotel card is priced for the dates named in `fetchOptions`, or for a sample stay the answer states; an instrument comes with its published financial statements), Zillow home listings (asking price or rent, rooms, floor area, the specification table, price and tax history, and the schools serving the address; for sale, for rent, sold and off-market are told apart), Google Patents documents (claims in full, with the legal status) and Google Scholar author profiles (citation metrics and the author's works), PDFs (text extraction), images (visual description by a vision model), sitemaps and sitemap indexes (the pages or child sitemaps they list, grouped by section, with last-modified dates and language versions), RSS, Atom and RDF feeds (each entry with its link, dates, authors and text). Video posts on TikTok, Instagram, Facebook and X also yield transcripts. A link to one ad reads that ad in all four ad libraries — Facebook (`/ads/library/?id=…`), LinkedIn (`/ad-library/detail/<id>`), TikTok (`library.tiktok.com/ads/detail/?ad_id=<number>`), Google (`adstransparency.google.com/advertiser/<AR…>/creative/<CR…>`) — adding every wording, per-country dates and destination that library publishes; ask in `fetchOptions` to have its creatives described. An address covering many ads — an advertiser page, a library hub, a search over it — is refused free of charge. Anything else is read as a web page. Per-URL failures (auth walls, dead links, blocked pages) are reported in `failed[]` without aborting the batch. Each URL is retrieved in full; a handful of well-chosen ones goes further than a long list. Each URL becomes a citable `Data` record with a title, a summary and a line index. Read the parts you need with `read_collected_records` — pass a line range, or omit it for the whole document."advanced_web_search1 field changedInput schema / properties / requests / items / properties / sources / descriptionPrevious value: -"Which sources to search — several can run at once; pick from where that kind of material actually is. Web and news: `google` (organic results plus related searches), `duckduckgo` (a second index whose first page mostly does not overlap Google's — run both), `web-mentions` (where a phrase turns up across the web, one page per site with the passage around it; reaches far past a first page, strong on subjects and terms, weak on bare brand names), `google-news` (news coverage: headline, publisher and date, no article text). Research and work: `google-scholar` (papers with citation counts; can also list what cites a given paper), `google-patents` (patents; at most 500 per search), `google-jobs` (job openings; nothing anywhere in the EEA). Social and video: `reddit` (posts; one community, an ordering or a period are settings, not terms), `tiktok` (one feed at a time — videos matched on the terms, accounts, or the videos under a single tag; which of the three is a setting, as are an ordering and a period on the video feed), `threads` (up to 10 public posts; takes a topic term of two or three words, not a sentence — an unrecognised term returns nothing), `youtube` (videos; one country's edition at a time, with no way to sort or filter what comes back). Places and travel: `google-maps` (places — the query names a place or a category of place, not a sentence; not a source of product reviews, and reviews of a place come from `advanced_web_fetch` on its link), `business-listings` (every business of a kind in one place — up to 1000 separate addresses with rating, review count, hours and attributes, selected by category, city and rating floor rather than ranked by relevance), `tripadvisor` (hotels, restaurants and things to do in one named place at a time), `google-hotels` (properties priced for a sample stay the results state), `google-flights` (one route on one day, one-way prices, searched by airport). Shopping: `amazon`, `walmart` (US store only) and `google-shopping` (one country's storefront) — product listings, not product pages. Apps and reputation: `google-play`, `app-store` (one national store each), `trustpilot` (companies and their review scores, worldwide). Ad libraries: `facebook-ads`, `linkedin-ads`, `tiktok-ads` and `google-ads` — which ads carry given words, or everything one company advertises — naming the advertiser is a setting, and doing so replaces the word search rather than narrowing it (`google-ads` only lists by advertiser and cannot search wording at all); none of them publishes what an ad cost or who saw it. Most sources read one country or store at a time. A market, an ordering, a period, or narrowing to a single community, account or seller are settings: say them in `searchOptions` and they reach the source through its own controls where it has them, instead of being searched for as words. Four sources answer with something whatever they are given: `google-shopping` returns unrelated products, `google-hotels` an unrelated town and `google-maps` unrelated places rather than nothing, and `tripadvisor` matches a place named only in the query as text inside venue names."New value: +"Which sources to search — several can run at once; pick from where that kind of material actually is. Web and news: `google` (organic results plus related searches), `duckduckgo` (a second index whose first page mostly does not overlap Google's — run both), `web-mentions` (where a phrase turns up across the web, one page per site with the passage around it; reaches far past a first page, strong on subjects and terms, weak on bare brand names), `google-news` (news coverage: headline, publisher and date, no article text). Research and work: `google-scholar` (papers with citation counts; can also list what cites a given paper), `google-patents` (patents; at most 500 per search), `google-jobs` (job openings; nothing anywhere in the EEA). Social and video: `reddit` (posts; one community, an ordering or a period are settings, not terms), `tiktok` (one feed at a time — videos matched on the terms, accounts, or the videos under a single tag; which of the three is a setting, as are an ordering and a period on the video feed), `threads` (up to 10 public posts; takes a topic term of two or three words, not a sentence — an unrecognised term returns nothing), `youtube` (videos; one country's edition at a time, with no way to sort or filter what comes back). Places and travel: `google-maps` (places — the query names a place or a category of place, not a sentence; not a source of product reviews, and reviews of a place come from `advanced_web_fetch` on its link), `business-listings` (every business of a kind in one place — up to 1000 separate addresses with rating, review count, hours and attributes, selected by category, city and rating floor rather than ranked by relevance), `tripadvisor` (hotels, restaurants and things to do in one named place at a time), `google-hotels` (properties priced for the dates named in `searchOptions`, or for a sample stay the results state), `google-flights` (one route on one day, one-way prices, searched by airport). Shopping: `amazon`, `walmart` (US store only) and `google-shopping` (one country's storefront) — product listings, not product pages. Apps and reputation: `google-play`, `app-store` (one national store each), `trustpilot` (companies and their review scores, worldwide). Ad libraries: `facebook-ads`, `linkedin-ads`, `tiktok-ads` and `google-ads` — which ads carry given words, or everything one company advertises — naming the advertiser is a setting, and doing so replaces the word search rather than narrowing it (`google-ads` only lists by advertiser and cannot search wording at all); none of them publishes what an ad cost or who saw it. Most sources read one country or store at a time. A market, an ordering, a period, or narrowing to a single community, account or seller are settings: say them in `searchOptions` and they reach the source through its own controls where it has them, instead of being searched for as words. Four sources answer with something whatever they are given: `google-shopping` returns unrelated products, `google-hotels` an unrelated town and `google-maps` unrelated places rather than nothing, and `tripadvisor` matches a place named only in the query as text inside venue names."advanced_web_fetchadvanced_web_searchask_collected_recordsget_task_resultsgrep_collected_recordsread_collected_recordsseo_metrics
Add one secure layer between your agents and this server.