# Web (/docs/web)

Web is a CoreSpeed-hosted capability for grounding: it hands an agent current
source material and leaves the reading to the agent. It needs no third-party
account and runs behind the same `/mcp` seam as every other tool, so identity,
organization holds, API-key caps, and activity recording apply unchanged.

## Tools \[#tools]

| Tool                       | Use it for                                                                                                                  |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `web__search`              | Ranked results with source URLs for a query, each with a short text snippet.                                                |
| `web__scrape`              | The readable text of one `https` page, freshly crawled.                                                                     |
| `web__google_search`       | Google's own results page for a query — organic ranking, People Also Ask, related searches, and optionally the AI Overview. |
| `web__google_maps_search`  | Places on Google Maps — name, category, address, coordinates, phone, website, rating, review count, place ID.               |
| `web__google_maps_reviews` | Reviews of one place — rating, text, date, likes, owner response.                                                           |
| `web__airbnb_listings`     | Airbnb stays in a location — price, rating, guests, bedrooms, amenities, host, listing URL.                                 |
| `web__tripadvisor_search`  | TripAdvisor hotels, restaurants, and things to do in a place — rating, ranking, price level, address.                       |
| `web__tripadvisor_reviews` | Reviews of one TripAdvisor place — rating, text, travel date, trip type, owner response.                                    |
| `web__amazon_products`     | Amazon search results, or one product or category page — price, rating, reviews, availability, ASIN.                        |
| `web__zillow_listings`     | Zillow homes in US ZIP codes, for sale, for rent, or sold — price, beds, baths, area, Zestimate.                            |
| `web__zillow_property`     | One US home's full Zillow record by address or URL — price and tax history, Zestimate, facts, schools.                      |

## Search returns sources, not an answer \[#search-returns-sources-not-an-answer]

`web__search` does not synthesize. It returns ranked results — title, URL,
published date, author, and by default a text snippet capped at 2,000 characters
per result — and expects the agent to read them.

| Parameter            | Effect                                                                                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`              | What to search for. Required.                                                                                                                                    |
| `num_results`        | 1–25, default 8.                                                                                                                                                 |
| `category`           | Bias results toward one content type: `company`, `research paper`, `news`, `pdf`, `github`, `tweet`, `personal site`, `linkedin profile`, or `financial report`. |
| `include_text`       | Inline a capped snippet per result. Default `true`.                                                                                                              |
| `include_highlights` | Add query-relevant highlight sentences per result. Default `false`.                                                                                              |
| `livecrawl`          | Force a fresh crawl of the results instead of the index cache — slower, fresher. Default `false`.                                                                |

```json title="structuredContent"
{
  "query": "MCP authorization spec RFC 9728",
  "resultCount": 2,
  "results": [
    {
      "title": "Authorization — Model Context Protocol",
      "url": "https://modelcontextprotocol.io/specification/…/authorization",
      "publishedDate": "2025-06-18",
      "author": null,
      "text": "…",
      "textTruncated": true
    }
  ]
}
```

`textTruncated` marks a snippet that hit the cap. To read a source in full, hand
its URL to `web__scrape`.

## Scrape reads one page \[#scrape-reads-one-page]

`web__scrape` fetches a single page and returns its clean text.

* `url` must be `https`. IP literals, loopback, and internal hostnames are
  refused with `invalid_input` before any request leaves CoreSpeed.
* `max_characters` defaults to 50,000 and is capped at 200,000. A clipped page
  sets `textTruncated: true`.
* `include_highlights` adds query-agnostic highlight sentences from the page.

Every scrape prefers a live fetch: a cached copy is returned only while the
site's own `Cache-Control` still marks it fresh, or for a few domains kept
cached long-term. There is no multi-page crawl and no queue: for discovery
across many pages, search first, then scrape the pages that matter.

## Google, Maps, and listing sites \[#google-maps-and-listing-sites]

`web__search` finds sources; `web__google_search` answers a different question
— what Google itself shows for a query, in what order. Use it for rankings,
SERP features, and AI Overviews. The Maps, Airbnb, TripAdvisor, Amazon, and
Zillow tools read those sites' own listings as structured records.

| Tool                       | Parameters                                                                                                                                                                                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web__google_search`       | `query` (Google operators work), `pages` 1–5 (\~10 results each, default 1), `country` (ISO code), `language`, `site`, `time_range` (`hour` … `year`), `mobile`, `include_ai_overview`.                                                                                         |
| `web__google_maps_search`  | `query` (what you would type into Maps), `location` (free text, city + country works best), `limit` 1–100 (default 20), `language`, `min_rating`, `skip_closed`, `include_details` (opening hours, popular times, review distribution).                                         |
| `web__google_maps_reviews` | Exactly one of `place_url` or `place_id` (both in `web__google_maps_search` results), `limit` 1–100 (default 20), `sort` (`newest`, `most_relevant`, `highest`, `lowest`), `since` (with `sort` `newest`, the default), `keyword`, `language`. Reviewer identities are omitted. |
| `web__airbnb_listings`     | `location`, `check_in` / `check_out` (YYYY-MM-DD), `adults`, `children`, `infants`, `pets`, `price_min` / `price_max`, `min_bedrooms`, `min_beds`, `min_bathrooms`, `currency`, `limit` 1–100 (default 20).                                                                     |
| `web__tripadvisor_search`  | `query` (a place, or a keyword), `kind` (`all`, `hotels`, `restaurants`, `attractions`), `language`, `currency`, `limit` 1–100 (default 20).                                                                                                                                    |
| `web__tripadvisor_reviews` | `place_url` (from `web__tripadvisor_search`: `webUrl`), `rating`, `since`, `language`, `limit` 1–100 (default 20). Reviewer identities are omitted.                                                                                                                             |
| `web__amazon_products`     | Exactly one of `query` (with `marketplace`, default `amazon.com`) or an Amazon `url` (product, search, or category), `limit` 1–100 (default 20).                                                                                                                                |
| `web__zillow_listings`     | `zip_codes` (1–5 US ZIPs), `status` (`for_sale`, `for_rent`, `sold`), `price_min` / `price_max`, `days_on_zillow`, `limit` per ZIP code 1–40 (default 20; up to `limit` × ZIP codes in total).                                                                                  |
| `web__zillow_property`     | Exactly one of `address` or a Zillow home `url` (from `web__zillow_listings`: `detailUrl`), plus `status` with a URL.                                                                                                                                                           |

These tools gather their results live, which typically takes 10–60 seconds.
They answer `{ "complete": true, "count": …, "results": [ … ] }` and accept
`timeout_seconds` (default 50, max 240) and `max_characters`. At the deadline
the results gathered so far come back with `"complete": false`, and only those
are billed; a collection that found nothing in time answers `timeout`, and one
that fails upstream answers `collection_failed` — neither is charged.

## Pricing and holds \[#pricing-and-holds]

| Call                       | Charge                                                                                                                                                                                         |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web__search`              | 14 credits per request, covering up to 10 results with their snippets and highlights; 2 more per result above 10, counted on the `num_results` you ask for.                                    |
| `web__scrape`              | 5 credits per page; 5 more with `include_highlights`.                                                                                                                                          |
| `web__google_search`       | 6.75 credits per results page, plus the start fee (about 0.075 per run); 4.5 more per AI Overview captured.                                                                                    |
| `web__google_maps_search`  | 6 credits per place, plus a start fee of 0.075 per GB of run memory (about 0.3 per run); 1.5 more per place per filter (`min_rating`, `skip_closed`); 3 more per place with `include_details`. |
| `web__google_maps_reviews` | 0.9 credits per review, plus the same start fee (about 0.075 per run).                                                                                                                         |
| `web__airbnb_listings`     | 6 credits per listing, plus 0.15 per run.                                                                                                                                                      |
| `web__tripadvisor_search`  | 7.5 credits per place, plus the start fee (about 0.15 per run).                                                                                                                                |
| `web__tripadvisor_reviews` | 7.5 credits per review, plus the start fee (about 0.15 per run).                                                                                                                               |
| `web__amazon_products`     | 7.5 credits per product.                                                                                                                                                                       |
| `web__zillow_listings`     | 3.6 credits per listing.                                                                                                                                                                       |
| `web__zillow_property`     | 5.4 credits per property.                                                                                                                                                                      |

A failed request is never charged. The live figures are repeated in the tool
descriptions your client shows from `tools/list`, and every charge lands
itemized in the organization ledger — see [Billing & credits](/docs/billing).
An organization billing hold or suspension stops a web call before it runs, as
an `isError` result carrying `payment_required` or `org_suspended`; API-key
spend caps apply the same way.

## Controls \[#controls]

Web appears as **Web search & scrape** in
[Dashboard → Tools](https://app.corespeed.io/tools). Turning it
off hides every `web__*` tool from `tools/list` for that member; see
[Capability controls](/docs/capability-controls).