Skip to main content
Glama

Act on a kept page

pagesift_interact
Destructive

Continue a kept browser page from a PageSift scrape session by sending either a plain-language prompt or browser actions, then get the updated page and results; stop it to free the page.

Instructions

Continue on a browser page kept by pagesift_scrape with keepSession. Send either prompt (plain-language instruction; needs an LLM on the server) or actions (a list of browser actions), not both. Actions can permanently change the page or lose unsaved state. State carries over between calls. Returns the page afterwards in data; with a prompt also output (the answer) and steps. Finish with pagesift_interact_stop to free the page. No live view or CDP URL is offered.

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": {
      "scrapeId": "<scrapeId>"
    },
    "name": "pagesift_interact"
  }
}

Input Schema

NameRequiredDescriptionDefault
promptNoWhat to do on the page, in plain language (needs an LLM on the server). Send prompt or actions.
actionsNoBrowser actions to run on the page. Send prompt or actions.
timeoutNoSeconds, default 30.
scrapeIdYesmetadata.scrapeId of a pagesift_scrape call with keepSession.

Output Schema

NameRequiredDescriptionDefault
dataNo
errorNoFailure reason when the action did not complete.
stepsNoSteps executed for a prompt.
killedNoThe run was stopped at the time limit.
outputNoAnswer to a prompt (only with prompt).
resultNoLast browser action result, such as a JavaScript return value.
stderrNoAlways empty; pagesift does not execute shell commands.
stdoutNoAlways empty; pagesift does not execute shell commands.
actionsNoOutputs of the requested actions, keyed by action.
successYesThe action or prompt completed.
exitCodeNoExit code of the action run.
warningsNoWarnings from the interaction.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv1.2.2
    • addedInput schema / properties / actions / items / properties / all / description
      Added value: +"Act on every element matching the selector instead of the first one."
    • addedInput schema / properties / actions / items / properties / direction / description
      Added value: +"Scroll direction."
    • addedInput schema / properties / actions / items / properties / format / description
      Added value: +"Output format for screenshot or PDF actions."
    • addedInput schema / properties / actions / items / properties / fullPage / description
      Added value: +"Capture the full page instead of the viewport."
    • addedInput schema / properties / actions / items / properties / key / description
      Added value: +"Key to press, for example Enter or ArrowDown."
    • addedInput schema / properties / actions / items / properties / landscape / description
      Added value: +"Use landscape orientation for PDF output."
    • addedInput schema / properties / actions / items / properties / milliseconds / description
      Added value: +"Wait time for wait actions, in milliseconds."
    • addedInput schema / properties / actions / items / properties / quality / description
      Added value: +"JPEG quality from 1 to 100."
    • addedInput schema / properties / actions / items / properties / scale / description
      Added value: +"Scale factor for PDF output."
    • addedInput schema / properties / actions / items / properties / script / description
      Added value: +"JavaScript source for executeJavascript."
    • addedInput schema / properties / actions / items / properties / selector / description
      Added value: +"CSS selector of the element to act on."
    • addedInput schema / properties / actions / items / properties / text / description
      Added value: +"Text to type or to use as the JavaScript expression, depending on the action."
    • addedInput schema / properties / actions / items / properties / type / description
      Added value: +"Action to run."
    • addedInput schema / properties / actions / items / properties / viewport / description
      Added value: +"Viewport size for screenshot or PDF output."
    • addedInput schema / properties / actions / items / properties / viewport / properties / height / description
      Added value: +"Viewport height in CSS pixels."
    • addedInput schema / properties / actions / items / properties / viewport / properties / width / description
      Added value: +"Viewport width in CSS pixels."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "actions": {
      +      "description": "Outputs of the requested actions, keyed by action."
      +    },
      +    "data": {
      +      "properties": {
      +        "actions": {
      +          "description": "Results of browser actions: screenshots, PDFs, scraped pages and JavaScript return values."
      +        },
      +        "attachments": {
      +          "description": "Exported files when exportImages was requested.",
      +          "items": {
      +            "properties": {
      +              "bytes": {
      +                "description": "Size in bytes.",
      +                "type": "integer"
      +              },
      +              "format": {
      +                "description": "File format (extension).",
      +                "type": "string"
      +              },
      +              "hash": {
      +                "description": "SHA-256 of the content.",
      +                "type": "string"
      +              },
      +              "id": {
      +                "description": "Attachment id; read the file with resources/read.",
      +                "type": "string"
      +              },
      +              "source": {
      +                "description": "Original URL or document part, when known.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "id",
      +              "format",
      +              "bytes",
      +              "hash"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "changeTracking": {
      +          "properties": {
      +            "changeStatus": {
      +              "description": "How the page changed since the previous scrape.",
      +              "enum": [
      +                "new",
      +                "same",
      +                "changed",
      +                "removed"
      +              ],
      +              "type": "string"
      +            },
      +            "diff": {
      +              "description": "Structured diff when one was requested."
      +            },
      +            "previousScrapeAt": {
      +              "description": "Time of the previous scrape of this URL.",
      +              "type": "string"
      +            },
      +            "visibility": {
      +              "description": "Whether the change is visible on the page.",
      +              "enum": [
      +                "visible",
      +                "hidden"
      +              ],
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "changeStatus",
      +            "visibility"
      +          ],
      +          "type": "object"
      +        },
      +        "chunks": {
      +          "description": "Markdown chunks when chunking was requested.",
      +          "items": {
      +            "properties": {
      +              "end": {
      +                "description": "End byte offset in the Markdown.",
      +                "type": "integer"
      +              },
      +              "headingPath": {
      +                "description": "Headings above the chunk.",
      +                "items": {
      +                  "description": "Heading",
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "start": {
      +                "description": "Start byte offset in the Markdown.",
      +                "type": "integer"
      +              },
      +              "text": {
      +                "description": "Chunk text.",
      +                "type": "string"
      +              },
      +              "tokens": {
      +                "description": "Estimated token count.",
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "text",
      +              "headingPath",
      +              "start",
      +              "end",
      +              "tokens"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "extract": {
      +          "description": "Items extracted by an extract schema."
      +        },
      +        "html": {
      +          "description": "Cleaned HTML when the html format was requested.",
      +          "type": "string"
      +        },
      +        "images": {
      +          "description": "Image URLs found on the page.",
      +          "items": {
      +            "description": "Absolute image URL.",
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "json": {
      +          "description": "JSON extracted by the json format; its shape follows the requested schema."
      +        },
      +        "links": {
      +          "description": "Links found on the page when the links format was requested.",
      +          "items": {
      +            "description": "Absolute URL.",
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "markdown": {
      +          "description": "Page content as Markdown. Present when the markdown format was requested (the default).",
      +          "type": "string"
      +        },
      +        "metadata": {
      +          "properties": {
      +            "author": {
      +              "description": "Author declared by the page.",
      +              "type": "string"
      +            },
      +            "cacheState": {
      +              "description": "Whether the result came from the result cache.",
      +              "enum": [
      +                "hit",
      +                "miss"
      +              ],
      +              "type": "string"
      +            },
      +            "cachedAt": {
      +              "description": "Time the cached copy was stored.",
      +              "type": "string"
      +            },
      +            "contentType": {
      +              "description": "Response Content-Type.",
      +              "type": "string"
      +            },
      +            "description": {
      +              "description": "Meta description.",
      +              "type": "string"
      +            },
      +            "error": {
      +              "description": "Error note when the page was returned with an error status.",
      +              "type": "string"
      +            },
      +            "favicon": {
      +              "description": "Favicon URL.",
      +              "type": "string"
      +            },
      +            "keywords": {
      +              "description": "Meta keywords.",
      +              "type": "string"
      +            },
      +            "language": {
      +              "description": "Detected or declared language.",
      +              "type": "string"
      +            },
      +            "modifiedTime": {
      +              "description": "Modified time declared by the page.",
      +              "type": "string"
      +            },
      +            "pagesift": {
      +              "properties": {
      +                "browserEngine": {
      +                  "description": "Browser kernel used for a rendered page.",
      +                  "type": "string"
      +                },
      +                "browserFingerprint": {
      +                  "description": "TLS fingerprint profile used for the request.",
      +                  "type": "string"
      +                },
      +                "contentHash": {
      +                  "description": "Hash of the cleaned content.",
      +                  "type": "string"
      +                },
      +                "crawl": {
      +                  "description": "How this page was discovered during a crawl."
      +                },
      +                "duplicateOf": {
      +                  "description": "Canonical URL when this page duplicates another.",
      +                  "type": "string"
      +                },
      +                "engine": {
      +                  "description": "Engine that produced the result.",
      +                  "enum": [
      +                    "http",
      +                    "browser",
      +                    "upload"
      +                  ],
      +                  "type": "string"
      +                },
      +                "etag": {
      +                  "description": "ETag from the response.",
      +                  "type": "string"
      +                },
      +                "itna": {
      +                  "description": "Access-barrier recovery attempts and their outcomes, when itna is enabled."
      +                },
      +                "jsonLd": {
      +                  "description": "JSON-LD blocks found on the page.",
      +                  "items": {
      +                    "description": "Parsed JSON-LD object."
      +                  },
      +                  "type": "array"
      +                },
      +                "lastModified": {
      +                  "description": "Last-Modified from the response.",
      +                  "type": "string"
      +                },
      +                "notModified": {
      +                  "description": "The origin answered 304 to a conditional request.",
      +                  "type": "boolean"
      +                },
      +                "ocr": {
      +                  "description": "OCR engine, device and page counts for scanned PDFs."
      +                },
      +                "plan": {
      +                  "description": "Render and merge decisions recorded by explain."
      +                },
      +                "queryFilter": {
      +                  "description": "How many blocks the query filter kept and token counts."
      +                },
      +                "rawHash": {
      +                  "description": "Hash of the raw response.",
      +                  "type": "string"
      +                },
      +                "redirectChain": {
      +                  "description": "URLs visited before the final page.",
      +                  "items": {
      +                    "description": "URL",
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "relevance": {
      +                  "description": "Query relevance score from 0 to 1.",
      +                  "type": "number"
      +                },
      +                "textHash": {
      +                  "description": "Hash of the normalized text used for change tracking.",
      +                  "type": "string"
      +                },
      +                "timings": {
      +                  "description": "Time per phase in milliseconds.",
      +                  "type": "object"
      +                },
      +                "warnings": {
      +                  "description": "Warnings that may mean the content is incomplete.",
      +                  "items": {
      +                    "description": "Warning",
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                }
      +              },
      +              "type": "object"
      +            },
      +            "proxyUsed": {
      +              "description": "Egress or proxy used for the request.",
      +              "type": "string"
      +            },
      +            "publishedTime": {
      +              "description": "Published time declared by the page.",
      +              "type": "string"
      +            },
      +            "robots": {
      +              "description": "robots meta directive.",
      +              "type": "string"
      +            },
      +            "scrapeId": {
      +              "description": "Id of the kept browser page when keepSession was used; pass it to pagesift_interact.",
      +              "type": "string"
      +            },
      +            "sourceURL": {
      +              "description": "URL that was requested.",
      +              "type": "string"
      +            },
      +            "statusCode": {
      +              "description": "HTTP status code of the response.",
      +              "type": "integer"
      +            },
      +            "title": {
      +              "description": "Page title.",
      +              "type": "string"
      +            },
      +            "url": {
      +              "description": "Final URL after redirects.",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "statusCode",
      +            "proxyUsed"
      +          ],
      +          "type": "object"
      +        },
      +        "pages": {
      +          "description": "Per-page Markdown, only for PDF page mode.",
      +          "items": {
      +            "properties": {
      +              "markdown": {
      +                "description": "Markdown for this page.",
      +                "type": "string"
      +              },
      +              "pageNumber": {
      +                "description": "1-based PDF page number.",
      +                "type": "integer"
      +              }
      +            },
      +            "required": [
      +              "pageNumber",
      +              "markdown"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "rawHtml": {
      +          "description": "Unmodified response body when the rawHtml format was requested.",
      +          "type": "string"
      +        },
      +        "screenshot": {
      +          "description": "Screenshot URL or data URL when the screenshot format was requested.",
      +          "type": "string"
      +        },
      +        "summary": {
      +          "description": "Summary produced when the summary format was requested.",
      +          "type": "string"
      +        },
      +        "warning": {
      +          "description": "Compatibility or deprecation warning from the scrape.",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "metadata"
      +      ],
      +      "type": "object"
      +    },
      +    "error": {
      +      "description": "Failure reason when the action did not complete.",
      +      "type": "string"
      +    },
      +    "exitCode": {
      +      "description": "Exit code of the action run.",
      +      "type": "integer"
      +    },
      +    "killed": {
      +      "description": "The run was stopped at the time limit.",
      +      "type": "boolean"
      +    },
      +    "output": {
      +      "description": "Answer to a prompt (only with prompt).",
      +      "type": "string"
      +    },
      +    "result": {
      +      "description": "Last browser action result, such as a JavaScript return value.",
      +      "type": "string"
      +    },
      +    "stderr": {
      +      "description": "Always empty; pagesift does not execute shell commands.",
      +      "type": "string"
      +    },
      +    "stdout": {
      +      "description": "Always empty; pagesift does not execute shell commands.",
      +      "type": "string"
      +    },
      +    "steps": {
      +      "description": "Steps executed for a prompt.",
      +      "items": {
      +        "description": "One step the prompt executed.",
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "success": {
      +      "description": "The action or prompt completed.",
      +      "type": "boolean"
      +    },
      +    "warnings": {
      +      "description": "Warnings from the interaction.",
      +      "items": {
      +        "description": "Warning",
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "success"
      +  ],
      +  "type": "object"
      +}
  2. Addedv0.81.6

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (destructive, non-idempotent, open-world), it discloses that actions can permanently change the page or lose unsaved state, that state carries over between calls, what is returned (data, plus output and steps with a prompt), and the notable limitation that no live view or CDP URL is offered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Six short sentences, front-loaded with the precondition and the prompt/actions choice, then behavior, return shape, and cleanup. No filler; each sentence carries a distinct operational fact.

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 destructive, stateful interaction tool, the description covers preconditions, mode selection, side effects, state persistence, return contents, and the required cleanup call. With an output schema present, return-value detail is a bonus rather than a gap.

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

Parameters3/5

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

Schema coverage is 100%, so prompt, actions, timeout, and scrapeId are already documented in the schema, including the 'send prompt or actions' note. The description restates the mutual exclusivity and adds that prompt requires a server-side LLM, but contributes little else beyond the structured fields, so the baseline 3 applies.

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 and resource ('Continue on a browser page kept by pagesift_scrape with keepSession'), which both states the action and pins the exact precondition that distinguishes it from pagesift_scrape and pagesift_interact_stop.

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 gives explicit routing rules: use prompt OR actions but not both, and terminate with pagesift_interact_stop to free the page. The precondition (a page kept via keepSession) tells the agent when this tool is applicable versus starting a fresh scrape.

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