Skip to main content
Glama

Search the web

search_web

Search the web for a query and return the ranked results, each with its title, url and snippet. The results are read from Google's results page; when Google refuses or reads short, from DuckDuckGo's and then Bing's, and the answer with most results about the query is given, topped up from the others. Use it to find pages whose URLs you do not know. It searches the web, unlike list_pages with q, which searches inside a project's stored run. For URLs you already have use scrape_urls; scrape_urls with full=true reads one result in full. Inputs: query as typed into a search engine, e.g. 'python http client'. scrape=true also fetches each result's page as markdown in the same call. include_domains=['python.org'] keeps the search to those sites; exclude_domains drops sites, and an exclude wins. Cost: at most 4 credits a search, whatever read it: Google's results page, and DuckDuckGo's or Bing's at 1 each when their results are used, within those 4. A results page an engine refused, or one about something else, is free. An equal search (same query, country, lang, freshness and domains) within an hour of a finished one comes from cache with no charge for the results page. Scraped pages are charged, cached or not. Timing: it waits for the results. A search aims to answer within about 35 seconds; a retry on the residential browser after Google's wall can take longer. If a search outlasts the connection's time limit, a job comes back for get_job; a scraping search whose pages are still landing returns its results with a job for the pages. Needs write access; a read-only connection is refused with code 'read_only'.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_web"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoA language code for the results, e.g. 'en'; omit for the default.
limitNoHow many results to return, 1 to 10 (default 10).
queryYesWhat to search the web for, 1 to 400 characters, as it would be typed into a search engine.
scrapeNotrue also fetches each result's page as markdown; each page costs credits. false (default) returns the results only.
countryNoA 2-letter country code to search from, e.g. 'us' or 'de'; omit for the default.
freshnessNoOnly results from the last hour, day, week, month or year; omit for any time.
exclude_domainsNoUp to 20 sites to leave out of the results, e.g. ['pinterest.com']; an exclude wins over an include.
include_domainsNoUp to 20 sites to search within, e.g. ['python.org']; omit for the whole web.

Output Schema

NameRequiredDescriptionDefault
idNoThe search's id: for get_job with kind 'search'.
jobNoWhile it is still going: {kind: 'search', id} for get_job. A scraping search can carry its results and a job for the pages still landing.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
noteNoThe cache rule, and what to do next when it is still going.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
queryNoThe query as searched.
cachedNotrue when an equal search within the hour answered it, with no charge for the results page.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
engineNoThe engine whose results page answered: 'google', 'duckduckgo' or 'bing'.
noticeNoOnly when a limit, not the site, held pages back: one line saying what they needed and why (the plan, the stealth trial or the credits left). Tell the person; it comes first in the answer.
statusNo'done'; 'blocked' when no engine answered (see `outcome`); 'running' with a `job` while it goes on. On an error, the HTTP status code.
noticesNoWith `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, `engine` on a search's and `outlook` {tier, likely, why} on a page's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself.
outcomeNoWith status 'blocked': 'no_results' when every engine refused the results page or had nothing about the query (nothing charged); null when the search did not run because the credits left could not pay for a results page -- tell the person, as a top-up or a plan change fixes it.
resultsNoUp to 10, as ranked, each {position, title, url, snippet, source, engine}; when scraped also `page`, {url, title, words, status, links (a count), markdown excerpt}, the excerpts sharing 60,000 characters.
attemptsNoBlocked only: each engine tried, and why it was refused.
waitedMsNoWith status 'running': how long, in milliseconds, this call waited for the search before handing back its job.
creditsUsedNoCredits this search spent, scraped pages included.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / limit / maximum
      Added value: +10
    • addedInput schema / properties / limit / minimum
      Added value: +1
  2. Changed2 schema fields changed
    • changedOutput schema / properties / engine / description
      Previous value: -"The engine whose results page answered, e.g. 'google' or 'bing'."New value: +"The engine whose results page answered: 'google', 'duckduckgo' or 'bing'."
    • changedOutput schema / properties / notices / description
      Previous value: -"With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, and `engine` on a search's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself."New value: +"With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, `engine` on a search's and `outlook` {tier, likely, why} on a page's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself."
  3. Changed3 schema fields changed
    • addedOutput schema / properties / outcome
      Added value: +{
      +  "description": "With status 'blocked': 'no_results' when every engine refused the results page or had nothing about the query (nothing charged); null when the search did not run because the credits left could not pay for a results page -- tell the person, as a top-up or a plan change fixes it.",
      +  "title": "Outcome"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"'done'; 'no_results' when every engine refused the results page or had nothing about the query (nothing charged; an older API says 'blocked'); 'running' with a `job` while it goes on. On an error, the HTTP status code."New value: +"'done'; 'blocked' when no engine answered (see `outcome`); 'running' with a `job` while it goes on. On an error, the HTTP status code."
    • addedOutput schema / properties / waitedMs
      Added value: +{
      +  "description": "With status 'running': how long, in milliseconds, this call waited for the search before handing back its job.",
      +  "title": "Waitedms"
      +}
  4. Changed3 schema fields changed
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Only when a limit, not the site, held pages back: one line saying what they needed and why (the plan, the stealth trial or the credits left). Tell the person; it comes first in the answer.",
      +  "title": "Notice"
      +}
    • addedOutput schema / properties / notices
      Added value: +{
      +  "description": "With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, and `engine` on a search's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself.",
      +  "title": "Notices"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"'done'; 'blocked' when every engine refused the results page (nothing charged); 'running' with a `job` while it goes on. On an error, the HTTP status code."New value: +"'done'; 'no_results' when every engine refused the results page or had nothing about the query (nothing charged; an older API says 'blocked'); 'running' with a `job` while it goes on. On an error, the HTTP status code."
  5. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations only declare openWorld/readOnly=false; the description adds substantial context beyond them: the Google→DuckDuckGo→Bing fallback and merge rule, the credit cost model with caching, the ~35s timing and job-return behavior, and the write-access requirement with the 'read_only' error code. It stops short of describing result ordering or failure modes beyond the refusal case, so not a 5.

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?

Front-loaded with purpose and alternatives, then inputs, cost, timing, and access in labeled blocks. Dense but every block is useful; the cost paragraph is slightly long-winded for what it conveys.

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 8-parameter, open-world, credit-charging tool with an output schema, the description covers routing, cost, latency, async job fallback, and auth prerequisites. 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 coverage is 100%, so the baseline is 3; the description still adds meaning by explaining query phrasing ('as typed into a search engine'), what scrape=true actually returns (markdown per page, charged), and the include/exclude precedence with an example.

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?

States a specific verb and resource ('Search the web for a query and return the ranked results') and immediately distinguishes itself from list_pages with q and scrape_urls, so an agent can route without opening a 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?

Gives explicit when-to-use ('find pages whose URLs you do not know'), names the alternatives and their conditions (list_pages for stored runs, scrape_urls for known URLs, scrape_urls full=true to read one result in full), and covers the scrape=true variant.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.