Skip to main content
Glama

Read web pages

writ_scrape

READ PAGES NOW, no browser session: one page (url), up to 20 pages in parallel (urls, on one site or several), or a listing plus its top N item pages (url + top_n). Returns clean markdown in 2-10 s, including pages a plain fetch cannot read: rendered by JavaScript (render_mode='browser'; a read that only got the page's shell says so and gives the retry), behind a bot wall or 403 (an automatic residential retry; render_mode='http' opens no browser, so it never passes a check), or behind the user's sign-in (persona_id). Discussion threads keep their comments. format='html' returns the raw HTML for selectors, for one page or a batch. A page that cannot be read says why (error.code, e.g. scrape_not_found: the URL does not exist on the site) and gives retry_with when another read can help. NOT FOR: a site-wide dataset (writ_crawl_site) or clicking and typing (writ_browser_use).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "writ_scrape"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNo
urlsNoUp to 20 known pages, read in parallel; they may be on different sites.
top_nNoWith url = a listing: also read its N top-ranked item pages (max 20).
deviceNo
formatNomarkdown (default) | html (raw HTML) | both; with url, urls or top_n.
persona_idNoRead signed in as this saved identity (writ_personas).
render_modeNoauto (default: HTTP, a browser when the page needs JS or meets a check) | http (no browser) | browser.
include_pathsNo
preview_charsNo
respect_robotsNo
use_residentialNoResidential network for a bot wall (automatic retry when refused).
residential_countryNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / device
      Added value: +{
      +  "type": "string"
      +}
    • changedInput schema / properties / format / description
      Previous value: -"markdown (default) | html (raw HTML) | both."New value: +"markdown (default) | html (raw HTML) | both; with url, urls or top_n."
    • addedInput schema / properties / include_paths
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / preview_chars
      Added value: +{
      +  "type": "integer"
      +}
    • changedInput schema / properties / render_mode / description
      Previous value: -"auto (default: HTTP, a browser when the page needs JS) | http | browser."New value: +"auto (default: HTTP, a browser when the page needs JS or meets a check) | http (no browser) | browser."
    • addedInput schema / properties / residential_country
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / respect_robots
      Added value: +{
      +  "type": "boolean"
      +}
    • changedInput schema / properties / urls / description
      Previous value: -"Up to 20 known pages, read in parallel."New value: +"Up to 20 known pages, read in parallel; they may be on different sites."
  2. Changed12 schema fields changed
    • removedInput schema / properties / device
      Removed value: -{
      -  "description": "A linked Writ desktop's agent_id (writ_devices) to act on. Omitted: the desktop this connection chose with writ_devices action='use', if any.",
      -  "type": "string"
      -}
    • changedInput schema / properties / format / description
      Previous value: -"markdown (default): the page's clean main content. html: the raw HTML as fetched (same egress/persona/render) — for selectors, embedded JSON, anything the cleaned text drops; clipped to preview_chars (default 40000, 0 = whole page). both: html plus the markdown derived from it, one fetch. Single `url` only."New value: +"markdown (default) | html (raw HTML) | both."
    • removedInput schema / properties / include_paths
      Removed value: -{
      -  "description": "With top_n: regex(es) the item links match (e.g. 'item\\\\?id=', '/products/'). Optional: the server detects detail links when omitted.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
    • changedInput schema / properties / persona_id / description
      Previous value: -"Saved identity to read as (writ_personas lists them), for pages behind a login. Forces the identity's own residential exit. A desktop persona ('device:…') reads on its own desktop, from that machine."New value: +"Read signed in as this saved identity (writ_personas)."
    • removedInput schema / properties / preview_chars
      Removed value: -{
      -  "description": "Cut each page's text to this many characters (default 12000; 0 = full pages).",
      -  "type": "integer"
      -}
    • changedInput schema / properties / render_mode / description
      Previous value: -"auto (default: plain HTTP, browser only if the page needs JS) | http | browser."New value: +"auto (default: HTTP, a browser when the page needs JS) | http | browser."
    • removedInput schema / properties / residential_country
      Removed value: -{
      -  "description": "Two-letter ISO country the residential exit should be in (e.g. 'us', 'fr'), also used by the automatic residential retry on a blocked page. Omitted = an automatic exit. Ignored unless the session egresses residential.",
      -  "type": "string"
      -}
    • removedInput schema / properties / respect_robots
      Removed value: -{
      -  "description": "Apply robots.txt to the explicitly requested page(s). Default false for scrape; writ_crawl_site defaults true for autonomous discovery.",
      -  "type": "boolean"
      -}
    • changedInput schema / properties / top_n / description
      Previous value: -"With `url` = a listing/front/search/category page: also read its N top-ranked item pages (the page's link order is the ranking). One call, parallel."New value: +"With url = a listing: also read its N top-ranked item pages (max 20)."
    • removedInput schema / properties / url / description
      Removed value: -"A page to read or, with `top_n`, the listing page whose top items are read."
    • changedInput schema / properties / urls / description
      Previous value: -"Known pages to read together (max 20), fetched in parallel in one call."New value: +"Up to 20 known pages, read in parallel."
    • changedInput schema / properties / use_residential / description
      Previous value: -"Fetch through the platform residential network (premium) for a site that blocks datacenter IPs or shows a bot wall. Default off."New value: +"Residential network for a bot wall (automatic retry when refused)."
  3. First observed

TDQS

A4.5/5.0
Behavior4/5

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

With annotations present but thin (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds substantial context: 2-10 s latency, the fact that a shell-only read reports itself and supplies a retry, an automatic residential retry on 403s, and structured error output (error.code, retry_with). It does not explain why the operation is marked non-read-only (e.g. cost, proxy use, or remote session state), which is the one behavior an agent might need to reason about.

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?

The lead clause is front-loaded ('READ PAGES NOW, no browser session') and each subsequent parenthetical earns its space by mapping a mode to a parameter. It is dense but justified for a 12-parameter tool; the single block paragraph makes the error-handling and exclusion clauses slightly harder to scan than necessary.

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

Completeness4/5

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

No output schema exists, yet the description volunteers return shape (clean markdown, raw HTML via format='html', thread comments retained) and failure shape (error.code examples, retry_with). Completeness is only slightly short of full because five parameters, notably device and preview_chars, remain unexplained anywhere.

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 only 50%, so the description carries real weight: it disambiguates url vs urls vs top_n, defines format='html' as raw HTML for selectors, ties persona_id to sign-in, and explains render_mode's auto/http/browser tradeoff including that http never passes a bot check. The remaining parameters (device, include_paths, preview_chars, respect_robots, residential_country) are undocumented in both places, keeping it below a 5.

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?

The description names a concrete verb and resource ('read pages') and enumerates its three invocation shapes (single url, parallel urls, listing + top_n), plus the format switch to raw HTML. It explicitly excludes writ_crawl_site and writ_browser_use by name, so an agent can separate it from siblings without opening any 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?

It states when each mode applies: render_mode='browser' when a page is JS-rendered, persona_id when the page is behind a sign-in, and render_mode='http' only when no bot wall needs passing. It also gives explicit when-not-to-use guidance by naming writ_crawl_site for site-wide datasets and writ_browser_use for clicking and typing.

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.