Skip to main content
Glama

List, search or read a run's pages

list_pages
Read-onlyIdempotent

List the pages a project run stored; with q, find the pages whose text or markup matches; with url, read one page in full, with its versions across runs. Use it for what a project's runs stored: what a run covered, which pages say something, one page's text. search_web searches the live web instead, get_job reads a crawl_site crawl, scrape_urls fetches a live copy, and get_changes lists only what changed. Inputs: project_id from list_projects. q='free trial' needs both words, q='"free trial"' the phrase; mode='selector' takes CSS such as 'form#signup' and needs a run that kept html (the rawHtml format); a selector search names the pages it could not search. url is an address, not a search term: scheme and trailing slash may differ or be left out, and a path alone is the project's own site; the rest must match, query string included. Give q or url, not both. run_id from list_runs picks the run; empty is the latest full run, and a newer re-crawl of listed pages is named as newerPartialRun. Limits: a listing has up to 500 rows, shallowest first, so use q to reach pages past them. A page read in full has each body capped at 12,000 characters, and a URL the runs did not store answers 404. Read-only and free: it reads stored data and never fetches.

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": {
      "project_id": "<project_id>"
    },
    "name": "list_pages"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoText to find, 1 to 200 characters: words or a "quoted phrase", or with mode='selector' a CSS selector or an XPath starting with / or (. Omit to list every page.
urlNoOne page's full URL, as a listing shows it, to read that page in full; omit to list.
modeNoWith q: 'content' (default) searches the markdown, 'selector' the stored html.content
run_idNoA run's id, from list_runs; empty means the latest finished run, or with url the newest copy across the project's last 50 runs.
project_idYesThe project's 32-character hex id, from list_projects.

Output Schema

NameRequiredDescriptionDefault
urlNoWith url: the page's URL as stored.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
headNoWith url: {title, description, canonical, h1, ...}.
hitsNoWith q: up to 500 matches, each {url, count (matches on the page), snippet}.
htmlNoWith url: the raw html, when the run kept it.
textNoWith url: plain text, when kept.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
pagesNoListing: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}.
runIdNoThe run these pages are from (with url, the run this copy is from); null when the project has no finished run.
wordsNoWith url: words in its markdown.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
fieldsNoWith url: fields the project's json_schema extracted, or null.
noBodyNoWith q: pages skipped because the body the mode needs was not kept (rawHtml for selector).
statusNoWith url: the HTTP status the site answered. On an error, the API's status code.
scannedNoWith q: pages searched.
markdownNoWith url: its main content as markdown, capped at 12,000 characters.
versionsNoWith url: every stored copy across runs, newest first, each {runId, crawledAt, contentHash, words, status}; a changed contentHash is a changed page.
cleanHtmlNoWith url: simplified html, when kept.
crawledAtNoWith url: when this copy was read (ISO 8601).
linkGraphNoListing: the run's link-graph summary (orphans, unlisted pages, dead ends), or null.
truncatedNoWith q: true when more pages matched than are listed.
pageStatusNoWith url: ok, blocked, captcha, missing (404/410), unreachable (no such site), timeout, redirect, robots or skipped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / pageStatus / description
      Previous value: -"With url: ok, blocked, captcha, missing (404/410), timeout, redirect, robots or skipped."New value: +"With url: ok, blocked, captcha, missing (404/410), unreachable (no such site), timeout, redirect, robots or skipped."
  2. Changed18 schema fields changed
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from list_runs; empty means the project's latest finished run."New value: +"A run's id, from list_runs; empty means the latest finished run, or with url the newest copy across the project's last 50 runs."
    • addedInput schema / properties / url
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "One page's full URL, as a listing shows it, to read that page in full; omit to list.",
      +  "title": "Url"
      +}
    • changedOutput schema / description
      Previous value: -"A run's pages, or with q the pages that match."New value: +"A run's pages; with q the pages that match; with url one page in full."
    • addedOutput schema / properties / cleanHtml
      Added value: +{
      +  "description": "With url: simplified html, when kept.",
      +  "title": "Cleanhtml"
      +}
    • addedOutput schema / properties / crawledAt
      Added value: +{
      +  "description": "With url: when this copy was read (ISO 8601).",
      +  "title": "Crawledat"
      +}
    • addedOutput schema / properties / fields
      Added value: +{
      +  "description": "With url: fields the project's json_schema extracted, or null.",
      +  "title": "Fields"
      +}
    • addedOutput schema / properties / head
      Added value: +{
      +  "description": "With url: {title, description, canonical, h1, ...}.",
      +  "title": "Head"
      +}
    • addedOutput schema / properties / html
      Added value: +{
      +  "description": "With url: the raw html, when the run kept it.",
      +  "title": "Html"
      +}
    • changedOutput schema / properties / linkGraph / description
      Previous value: -"Without q: the run's link-graph summary (orphans, unlisted pages, dead ends), or null."New value: +"Listing: the run's link-graph summary (orphans, unlisted pages, dead ends), or null."
    • addedOutput schema / properties / markdown
      Added value: +{
      +  "description": "With url: its main content as markdown, capped at 12,000 characters.",
      +  "title": "Markdown"
      +}
    • addedOutput schema / properties / pageStatus
      Added value: +{
      +  "description": "With url: ok, blocked, captcha, missing (404/410), timeout, redirect, robots or skipped.",
      +  "title": "Pagestatus"
      +}
    • changedOutput schema / properties / pages / description
      Previous value: -"Without q: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}."New value: +"Listing: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}."
    • changedOutput schema / properties / runId / description
      Previous value: -"The run these pages are from; null when the project has no finished run."New value: +"The run these pages are from (with url, the run this copy is from); null when the project has no finished run."
    • changedOutput schema / properties / status / description
      Previous value: -"Only on a failure: the HTTP status code."New value: +"With url: the HTTP status the site answered. On an error, the API's status code."
    • addedOutput schema / properties / text
      Added value: +{
      +  "description": "With url: plain text, when kept.",
      +  "title": "Text"
      +}
    • addedOutput schema / properties / url
      Added value: +{
      +  "description": "With url: the page's URL as stored.",
      +  "title": "Url"
      +}
    • addedOutput schema / properties / versions
      Added value: +{
      +  "description": "With url: every stored copy across runs, newest first, each {runId, crawledAt, contentHash, words, status}; a changed contentHash is a changed page.",
      +  "title": "Versions"
      +}
    • addedOutput schema / properties / words
      Added value: +{
      +  "description": "With url: words in its markdown.",
      +  "title": "Words"
      +}
  3. Changed5 schema fields changed
    • addedInput schema / properties / mode
      Added value: +{
      +  "default": "content",
      +  "description": "With q: 'content' (default) searches the markdown, 'selector' the stored html.",
      +  "enum": [
      +    "content",
      +    "selector"
      +  ],
      +  "title": "Mode",
      +  "type": "string"
      +}
    • changedInput schema / properties / project_id / description
      Previous value: -"The project's id, as list_projects or create_project returns it."New value: +"The project's 32-character hex id, from list_projects."
    • addedInput schema / properties / q
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Text to find, 1 to 200 characters: words or a \"quoted phrase\", or with mode='selector' a CSS selector or an XPath starting with / or (. Omit to list every page.",
      +  "title": "Q"
      +}
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from list_runs, start_run or the runId a list_pages answer carries; leave empty for the last finished run."New value: +"A run's id, from list_runs; empty means the project's latest finished run."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A run's pages, or with q the pages that match.",
      +  "properties": {
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "hits": {
      +      "description": "With q: up to 500 matches, each {url, count (matches on the page), snippet}.",
      +      "title": "Hits"
      +    },
      +    "linkGraph": {
      +      "description": "Without q: the run's link-graph summary (orphans, unlisted pages, dead ends), or null.",
      +      "title": "Linkgraph"
      +    },
      +    "noBody": {
      +      "description": "With q: pages skipped because the body the mode needs was not kept (rawHtml for selector).",
      +      "title": "Nobody"
      +    },
      +    "pages": {
      +      "description": "Without q: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}.",
      +      "title": "Pages"
      +    },
      +    "runId": {
      +      "description": "The run these pages are from; null when the project has no finished run.",
      +      "title": "Runid"
      +    },
      +    "scanned": {
      +      "description": "With q: pages searched.",
      +      "title": "Scanned"
      +    },
      +    "status": {
      +      "description": "Only on a failure: the HTTP status code.",
      +      "title": "Status"
      +    },
      +    "truncated": {
      +      "description": "With q: true when more pages matched than are listed.",
      +      "title": "Truncated"
      +    }
      +  },
      +  "title": "PagesOut",
      +  "type": "object"
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from start_run or the runId a list_pages answer carries; leave empty for the last finished run."New value: +"A run's id, from list_runs, start_run or the runId a list_pages answer carries; leave empty for the last finished run."
  5. Changed2 schema fields changed
    • addedInput schema / properties / project_id / description
      Added value: +"The project's id, as list_projects or create_project returns it."
    • addedInput schema / properties / run_id / description
      Added value: +"A run's id, from start_run or the runId a list_pages answer carries; leave empty for the last finished run."
  6. First observed

TDQS

A4.5/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered by structured data; the description mostly restates it ('Read-only and free'). It does add genuinely new behavior: the 500-row shallowest-first cap, the 12,000-character body cap, 404 for URLs the runs never stored, and the newerPartialRun signal. Those operating limits are useful, but much of the sentence space goes to facts already implied by annotations rather than deeper 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.

Conciseness4/5

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

Front-loaded with purpose and mode selection before the input details and limits, which is the right order. It is dense but largely earned; the main cost is duplication of parameter defaults that also appear in the schema descriptions (q, run_id, mode), which lengthens the block without adding new information.

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 a five-parameter, three-mode tool, the description covers mode selection, cross-parameter constraints, result-size limits, error behavior (404), and a partial-result signal (newerPartialRun). Return-value structure is carried by the output schema, so nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds real meaning beyond it: quote semantics for q, the requirement that selector mode needs a run that kept html (rawHtml), naming of pages a selector could not search, URL normalization rules (scheme and trailing slash optional, path alone means the project's own site, query string must match), and run_id empty meaning latest full run vs. newest copy across the last 50 runs when used with url.

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 opens with a specific verb+resource framing ('List the pages a project run stored') and immediately enumerates the three distinct modes (list, search via q, read via url). It also names each sibling tool it is not (search_web, get_job, scrape_urls, get_changes) with the condition that selects them, so an agent can route correctly 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?

Explicit when-to-use ('what a run covered, which pages say something, one page's text') plus an explicit when-not block naming four alternatives and their distinct roles. It also gives a mutual-exclusion rule ('Give q or url, not both') and a routing rule for run_id ('empty is the latest full run').

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.