The unbrowser server provides a lightweight, agent-friendly web browser interface for LLMs — fetching, parsing, and interacting with web pages without full Chrome overhead, returning structured outputs optimized for agent consumption.
Navigation & Page Reading
Fetch URLs with Chrome-fingerprinted HTTP, parse HTML, and return a structured BlockMap summary (~500 tokens) with auto-extracted embedded JSON and tool recommendations
Retrieve raw HTML, main content text (stripped of nav/header/footer), or clean whitespace-collapsed text from selectors
DOM Querying & Search
Query elements via CSS selectors (with stable refs for interaction), find elements by visible text, diagnose selector misses, and retrieve surrounding context
Structured Data Extraction
Auto-strategy extraction: JSON-LD → __NEXT_DATA__ → Nuxt → JSON-in-script → OpenGraph → microdata → text fallback
Extract HTML tables into {headers, rows}, pull repeated card/listing patterns into structured arrays, and parse captured network/API responses into semantic objects
Page Modeling & Discovery
Model a page into semantic task-discoverable JSON (search forms, nav links, article/product cards, tables) with goal-based scoring
Discover navigation/search routes and merge DOM routes, inferred URLs, and network JSON into a ranked discovery graph
Interaction
Click elements (auto-follows <a href> links), type into inputs, submit forms (GET or POST), and classify interaction effects (navigated, dom_changed, no_effect, etc.)
JavaScript Execution
Run arbitrary JS in an embedded QuickJS runtime and drain the event loop (microtasks, setTimeout/setInterval)
Cookie & Session Management
Set, get, and clear cookies for persistent sessions or replaying clearance cookies to bypass bot detection
Network Capture
Capture and inspect fetch/XHR responses (JSON, GraphQL, NDJSON) from navigations, ranked by content value
Observability & Diagnostics
Challenge detection for bot-walled pages, SPA detection heuristics, tool_recommendations to guide agent next steps, and report_outcome for binding task success/failure to prior navigations for policy learning
Allows accessing Cloudflare-protected websites by handling bot challenges and cookie handoff, with automatic detection of challenge provider.
Enables scraping and interacting with GitHub repository browsing pages with full selector support.
Provides limited rendering support for Next.js SSR pages and light hydration, allowing navigation and query of static content.
Offers excellent navigation and query capabilities on Wikipedia pages, producing a compact BlockMap summary.
Supports navigating Zillow pages with cookie handoff to bypass bot walls.
The cheap browser pass for agents. One native binary. No Chrome.
Official MCP Registry identity: mcp-name: io.github.protostatis/unbrowser
unbrowser is a stateful, non-visual web runtime for agents. It sits between curl/WebFetch and a real browser: it retains cookies and DOM state, returns queryable element refs, handles links and HTML forms, detects challenge and SPA signals, and can run bounded QuickJS page scripts when static HTML is not enough.
Default
navigateis a fast static/SSR pass. Setexec_scripts: trueonly when you need bounded QuickJS execution. Heavy SPAs, pixels, V8 fidelity, extensions, and interactive anti-bot challenges belong in a real Chrome tier.
Try the live public-web demo before installing. It accepts only the fixed public source sets shown on the page; do not send private data, cookies, or authenticated tasks through it. A shared Streamable HTTP MCP endpoint is available at https://unchainedsky.com/unbrowser-mcp for public smoke tests; production sessions should use a local install.
Use unbrowser only on sites, accounts, and data you are permitted to access.
Challenge detection and cookie import do not grant permission to bypass access
controls or site terms. Treat session cookies as credentials: keep them local,
scope them to the authorized task, and never send them to the public demo.
Need | curl / WebFetch | unbrowser | Real Chrome |
Static / SSR HTML | raw response | structured BlockMap + DOM queries | full browser |
Cookies, links, HTML forms | DIY | built in | built in |
Client-side page scripts | ❌ | bounded QuickJS, opt-in | V8 |
Pixels, Canvas, WebGL, Workers, extensions | ❌ | ❌ | ✅ |
Agent-oriented output | DIY parsing | element refs, page signals, structured extraction | DIY CDP / DOM parsing |
Interactive access challenge | ❌ | detect + stop or escalate | authorized browser / human confirmation |
Use unbrowser when HTTP alone is too dumb and a full browser is too expensive. When the page needs Chrome, the output tells the agent to escalate rather than pretending compatibility it does not have.
Related MCP server: Browserbase MCP Server
docker pull ghcr.io/protostatis/unbrowser:latest
# One-shot navigation
docker run --rm ghcr.io/protostatis/unbrowser:latest \
navigate https://example.com --json
# Default mode: MCP over stdio
docker run --rm -i ghcr.io/protostatis/unbrowser:latestThe image is distroless and runs as non-root: no shell, package manager, or persistent state. Pin :vX.Y.Z or an image digest in production.
pipx install pyunbrowser # recommended on macOS / modern Linux
# or, inside a Python 3.10+ virtual environment:
pip install pyunbrowserfrom unbrowser import Client
with Client() as ub:
ub.navigate("https://news.ycombinator.com")
for link in ub.query(".titleline > a")[:3]:
print(link["text"], link["attrs"]["href"])On macOS, /usr/bin/python3 is 3.9 and cannot install the wheel; use pipx or a Homebrew Python. The PyPI distribution is pyunbrowser, while the import and executable remain unbrowser.
{
"mcpServers": {
"unbrowser": {
"command": "unbrowser",
"args": ["--mcp"]
}
}
}Minimal surface: add "--mcp-profile", "minimal" to expose only navigate/query/extract/help and let the agent discover the rest via help(topic). The Python wrapper ships a 3-tool smart server (search/open/help) as the unbrowser-smart console script.
{
"mcpServers": {
"unbrowser": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"ghcr.io/protostatis/unbrowser:latest"
]
}
}
}See installation and interface reference for Cargo, release archives, source builds, persistent shell sessions, raw JSON-RPC, and all MCP options.
navigate returns a BlockMap: page title, landmarks, headings, interactives, density signals, and an ASCII outline. Its size is page-dependent; it is structured for planning rather than a fixed-token promise.
Stable element refs (e:142): query an element once, then click, type, or submit it without re-parsing HTML.
Stateful cookies and forms: cookie jar, GET and URL-encoded POST form submission, links, and redirects persist within a session.
Page and challenge signals: density.likely_js_filled, thin_shell, and challenge.provider tell an agent whether to run scripts, inspect embedded data, stop, or escalate to an authorized browser session.
Routing aids on every result: micro_hint (the single next concrete step), next_tools (ranked candidates), avoid (tools with nothing to act on), and a stable escalation taxonomy (challenge, thin_shell, partial_result, …) with retryable/severity/evidence — recommendations never contradict avoid.
Structured helpers: route discovery, card extraction, table normalization, text_main, and selector debugging cover common extraction workflows.
{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}With exec_scripts: true, inline and external scripts run in QuickJS under a bounded watchdog. This can materialize light hydration and fetch-visible data; it is not V8 or a rendering engine. Heavy React/Vue/Ember apps may still leave an empty shell.
Escalate to unchainedsky-cli or Unchained when a permitted task needs real pixels, Canvas/WebGL, Workers, browser extensions, V8 compatibility, an authenticated profile, or human confirmation. When the user has already established an authorized session in Chrome, cookies_set can import the required session cookie locally until it expires; it is not a license to circumvent a site's controls.
Need | Read |
Install paths, session CLI, one-shot CLI, raw RPC, MCP, shims, full RPC table | |
Script compatibility, SPA signals, challenge handling, authorized cookie handoff, escalation | |
Distribution and supported directory listings | |
Build the native binary |
Apache-2.0 — see LICENSE.
Higher-level action probe. Clicks an element by ref or visible action text, settles, and returns before/after URL, BlockMap/page_model summaries, network counts, hashes, and classification: navigated, dom_changed, network_changed, no_effect, or unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Optional element ref like e:142. | |
| text | No | Optional visible action text to locate when ref is omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes behavior: clicking, settling, and returning before/after URLs, summaries, network counts, hashes, and classification of effects. It covers all essential behavioral aspects for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, efficiently packing all key information: action, input, steps (click + settle), and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists all return components (URLs, summaries, etc.) and classification. The input schema is well-covered. The tool is distinct from its many siblings, and the description ensures an agent knows when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions. The description adds context by explaining that 'ref' or 'text' identifies the element to click, confirming their roles and usage. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies that 'activate' clicks an element (by ref or text), settles, and returns detailed output with classification. It distinguishes itself from simpler actions like 'click' or 'type' by being a higher-level probe with comprehensive return data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is a 'higher-level action probe', implying a comprehensive action. It does not explicitly state when to use versus alternatives, but the detailed output and classification hint at scenarios requiring full analysis. Slightly lacking in explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recompute the BlockMap for the current page. Use after eval'd JS or click/type modifies the DOM. Same shape as the inline blockmap from navigate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose behavioral traits such as whether it is read-only, costly, or requires auth. The term 'recompute' suggests computation but no further details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous words. Front-loaded with the core action and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacking an output schema, the description references the shape from navigate, which provides useful context. However, more detail about the BlockMap structure could be helpful, but it is reasonably complete for a simple recompute tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Baseline score of 4 is appropriate as description adds no parameter info beyond schema (which is empty).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool recomputes the BlockMap for the current page after DOM modifications. It specifies the exact usage context and distinguishes from navigate by noting the same output shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (after eval'd JS or click/type modifies the DOM) and implies when not needed. No alternative tools named, but context from sibling list makes navigate an obvious alternative for initial blockmap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the raw HTML body of the last navigation. Use as a fallback when the BlockMap or selectors aren't enough — but the response can be large (often 100KB+).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Notes response size (100KB+), but lacks details on performance or blocking nature. With no annotations, description adequately covers safety (read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, then usage guidance and caveat. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully addresses tool's purpose, usage, and a key caveat (size). Sufficient given no parameters or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline score of 4 is appropriate as description adds no param info but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states returning raw HTML body of last navigation. Mentions fallback use case, distinguishing from BlockMap and selectors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use as a fallback when the BlockMap or selectors aren't enough', providing clear when-to-use and alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dispatch a click event on the element at ref (e.g. e:142, returned from query). If the element is and the click was not preventDefault'd, auto-follows the href via navigate (returns the full navigation result with new BlockMap). Otherwise returns {ok, ref, tag, follow: null}.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Element ref like e:142 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses the two behavioral paths (click only vs click+follow navigation) and the return values in each case. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the action and parameter, the second explains the two outcomes. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of two scenarios and a side-effect (navigation), the description is complete. It covers both return cases without needing an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'ref' is described in the schema as 'Element ref like e:142'. The description adds context ('returned from query') and clarifies its origin. Since schema coverage is 100%, baseline is 3, and the addition justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it dispatches a click event on an element referenced by ref, and distinguishes between <a href> navigation and other elements. It is specific and differentiates from sibling tools like activate or submit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when auto-navigation occurs (for <a href> without preventDefault) and implies general usage for clickable elements. It doesn't explicitly exclude non-clickable elements or mention alternative tools, but provides good context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drop all cookies from the jar.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description states 'Drop all cookies' implying a destructive action, but lacks details on scope (e.g., all cookies in jar, session vs persistent), reversibility, or side effects. Baseline transparency is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence with no filler. Extremely concise and front-loaded. Every word is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is minimal but sufficient for a simple one-action tool. However, for a destructive operation, more context on behavior and consequences would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema (schema coverage 100%). With zero parameters, the description does not need to add parameter semantics. Baseline of 4 is appropriate as the condition is trivially satisfied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Drop all cookies from the jar.' uses a specific verb (Drop) and resource (cookies), clearly indicating the action of clearing all cookies. It distinguishes well from siblings like cookies_get and cookies_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. While the purpose is implied (clear all cookies), there is no mention of when not to use it or comparison to related tools like cookies_get or cookies_set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all cookies currently in the jar as [{name, value, domain, path, secure, http_only}]. Use this to export cookies to disk for a later session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It explicitly states the operation is a retrieval and specifies the return format, implying no side effects. However, it does not explicitly state it is read-only or idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences, 24 words. Front-loaded with the primary action and return structure. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter tool with no parameters and no output schema, the description covers the key aspects: what is returned and a primary use case. It does not address edge cases like empty state, but that is acceptable for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns all cookies as a list of objects with specific fields. The phrase 'currently in the jar' adds context. Sibling tools like cookies_clear and cookies_set are distinct, so it effectively differentiates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using this tool to export cookies to disk for a later session. While it does not mention when not to use or alternatives, it provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add cookies to the session jar. Each item is an object {name, value, domain, path?, secure?, http_only?, url?} or a raw Set-Cookie string. Used to replay clearance cookies (e.g. PerimeterX _px3) lifted from a real Chrome session, bypassing bot detection without running the challenge JS.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Default URL for cookies that don't specify domain | |
| cookies | Yes | Array of cookie objects or Set-Cookie strings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the input format and purpose but does not disclose whether cookies replace or append to existing ones, persistence across navigations, or error handling. The mention of bypassing bot detection adds context, but more behavioral detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states action and format, second provides a key use-case. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and minimal annotations, the description provides sufficient context for an agent to understand the tool's purpose and when to invoke it. It could be enhanced with details on cookie persistence or side effects, but overall it is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds detailed structure for cookie objects (e.g., name, value, domain, etc.) and notes that each item can also be a raw Set-Cookie string, providing meaning beyond the schema's generic 'array' type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states that the tool adds cookies to the session jar, specifies input formats (object or Set-Cookie string), and provides a concrete use case (replaying clearance cookies). It distinguishes itself from sibling tools like cookies_get and cookies_clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states when to use (to replay clearance cookies from a real Chrome session to bypass bot detection). While it doesn't mention when not to use or list alternatives, the given scenario is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-level cheap-first information discovery. Optionally navigates to a URL, runs light JS, merges DOM routes, inferred form/query URLs, and network JSON routes into one ranked graph with provenance plus route-level escalation hints. Use this when the task is to find where information lives before extracting it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional absolute http(s) URL to navigate before discovery. If omitted, discovers on the current page. | |
| goal | No | Optional goal/query used to rank routes and build query URLs. | |
| debug | No | If true, include full nested navigate, route_discover, and network_extract payloads. Default false returns compact summaries. | |
| limit | No | Max routes to return after dedupe/ranking, 1-200 (default 50). | |
| same_origin | No | If true, only return page-owned routes. | |
| exec_scripts | No | Run page scripts during navigation when url is provided. Default false; enable when static discovery is insufficient. | |
| include_network | No | Include captured network JSON objects and API-like captures. Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It discloses that it is 'cheap-first' and may navigate to a URL, but does not clarify whether it modifies state, has side effects, or requires specific permissions. It mentions merging and ranking but lacks details on behavioral traits like cost or safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences: the first explains functionality concisely, the second provides usage guidance. It is front-loaded with key information, no redundant words, and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no required params, and no output schema, the description adequately explains the tool's role and output as a 'ranked graph with provenance plus route-level escalation hints.' It is complete enough for a discovery tool, though more detail on output structure could help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add additional parameter meaning beyond the schema; it only mentions optional URL navigation. No new semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'High-level cheap-first information discovery' and details specific actions: navigating to URL, running light JS, merging DOM routes, inferred form/query URLs, and network JSON routes into a ranked graph. This distinguishes it from siblings like route_discover or navigate by emphasizing a combined, cheap-first approach.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the task is to find where information lives before extracting it,' providing clear context for use. It implies a precursor to extraction but does not list specific when-not-to-use cases or alternatives, though the sibling context suggests alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run arbitrary JavaScript in the embedded QuickJS runtime against the current page's parsed DOM. Returns the JSON-stringified result. Power tool — prefer query/text/blockmap when the CSS selector engine can express what you need. Canonical param is code; raw JSON-RPC also accepts script or expression aliases and errors if no code-like param is present.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JS code; the value of the last expression is returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes execution context (embedded QuickJS, parsed DOM), return format (JSON-stringified), and error condition (no code-like param). Lacks mention of sandboxing or side effects, but adequate given nature of tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler. Front-loaded with primary purpose, then guidance and param details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete given lack of output schema: states return format and context. No gaps for a power tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers param fully (100% coverage). Description adds value: explains aliases (script, expression) and explicit error behavior if no code-like param is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'run arbitrary JavaScript' with specific target 'current page's parsed DOM'. Distinguishes from sibling tools like query/text/blockmap by explicitly stating preference for those when possible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer query/text/blockmap when CSS selector engine suffices, and documents canonical param vs. alternative aliases with error behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-strategy structured-data extraction. Tries JSON-LD (schema.org) → NEXT_DATA → Nuxt → JSON-in-script (Magento, Shopify, BigCommerce custom-typed scripts) → OpenGraph/meta → microdata → text_main fallback, returns the highest-confidence hit as {strategy, confidence, data, tried}. Use this as the one-shot 'give me the data, you figure out how' call when you don't want to plan the strategy yourself. Pass strategy='json_ld' (or any of the names above) to force a specific extractor.
| Name | Required | Description | Default |
|---|---|---|---|
| strategy | No | Optional: force a specific extractor (json_ld, next_data, nuxt_data, json_in_script, og_meta, microdata, text_main) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly describes the fallback order: JSON-LD → __NEXT_DATA__ → Nuxt → JSON-in-script → OpenGraph/meta → microdata → text_main. It also explains the return format and the behavior when a specific strategy is forced. This provides full transparency about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph, but it is well-structured: it opens with the purpose, details the fallback order, then provides usage guidance. It is front-loaded with the core purpose. However, it is somewhat dense and could be broken into more digestible sentences. The information content is efficient, but slight readability improvements would earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description covers the return format ({strategy, confidence, data, tried}) and explains behavior for both auto-strategy and forced strategy. It does not mention error cases or edge conditions, but for a single-parameter tool with 100% schema coverage, the description provides sufficient context for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'strategy' is already described with allowed values in the schema. The description goes beyond by explaining that passing a value forces a specific extractor, and it lists the possible values again. This adds context but does not introduce new semantic meaning beyond what the schema offers. The baseline is 3, and the added usage context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Auto-strategy structured-data extraction' which clearly states the tool's purpose. It lists the specific extraction methods and returns the highest-confidence hit as {strategy, confidence, data, tried}. It distinguishes from siblings by positioning it as a one-shot 'give me the data, you figure out how' call, contrasting it with tools like extract_cards or extract_list that target specific data formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'when you don't want to plan the strategy yourself'. It also provides an alternative: 'Pass strategy='json_ld' (or any of the names above) to force a specific extractor'. It does not explicitly state when not to use it or compare it to sibling tools, but it implies that if a specific strategy is desired, you should force it. The lack of explicit exclusions prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Auto-detect repeated article/card/product/course/listing blocks and return normalized items [{title, price, condition, url, availability, snippet, meta, image_alt, score}]. Prefer this over extract_list when the page has semantically ambiguous recipe, course, product, or model cards and you do not already know field selectors. Optional selector scopes detection to known card nodes; kind can bias scoring (recipe, course, product, listing).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional hint: recipe, course, product, listing, article | |
| limit | No | Max items to extract (default 50) | |
| selector | No | Optional CSS selector matching each card/listing block |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses auto-detection behavior, normalization, and optional parameter effects. However, it does not mention side effects (e.g., whether it modifies page state), performance characteristics, or error handling. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste. First sentence states action and output structure; second provides usage guidance and parameter hints. Front-loaded with core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists returned fields. Sibling tools (especially extract_list) are addressed. Parameters are explained both in schema and description. The tool's behavior is sufficiently characterized for an auto-detection tool with zero required parameters and 3 optional ones.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 3 parameters described). The description adds context beyond schema: explains the 'kind' enum values (recipe, course, product, listing), that 'selector' scopes detection, and 'limit' default 50. This adds meaningful value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool auto-detects repeated blocks (article/card/product/course/listing) and returns normalized items with a specific schema. It also distinguishes from sibling 'extract_list' by explicitly noting when to prefer this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Prefer this over extract_list when the page has semantically ambiguous...cards and you do not already know field selectors.' Also explains optional selector and kind biasing. Missing explicit when-not-to-use scenarios, but is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull a repeated card pattern into [{...}, {...}]. Right tool for HN-style lists, search results, product grids — collapses per-site eval boilerplate. Field spec shapes: 'css selector' (text content), 'css selector @attr' (attribute), or ['css selector', '@attr'] (tuple form). If a sub-selector returns null, the field value is null.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max items to extract (default 1000) | |
| fields | Yes | {field_name: 'sub-selector' | 'sub-selector @attr' | ['sub-selector', '@attr']} | |
| item_selector | Yes | CSS selector matching each card/row |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses null handling for sub-selectors but does not state if the tool is read-only or any other behavioral traits like rate limits or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences front-loaded with purpose, then usage, parameter details, and edge case. No wasted words, though slightly more detail on usage vs alternatives could be added.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers output format (array of objects), field spec syntax, null behavior. Lacks mention of error conditions or limit default, but overall sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining field spec shapes (text, attribute, tuple) and null behavior, which is not fully captured in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it extracts repeated card patterns into an array of objects, and lists example use cases (HN-style lists, search results, product grids). Implicitly distinguishes from siblings like extract_cards by focusing on 'per-site eval boilerplate' collapse, but lacks explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Right tool for...' and lists specific patterns, providing clear context for when to use. Does not mention when not to use or alternatives, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull a into {headers, rows, row_count}. Headers come from ... if present, else the first 's cells. Each subsequent 's cells become a row dict keyed by header (or 'col_N' if no header for that column). Right tool for pricing tables, specs, finance/listings tables — saves writing the per-cell mapping eval.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector matching the <table> element |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and thoroughly explains the extraction logic: how headers are sourced (from thead or first th cells), how rows are mapped (keyed by header or col_N), and the return shape. This goes beyond a simple 'extract table' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the output structure, then explain header logic, and conclude with use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, no annotations), the description fully explains the return structure, extraction behavior, and appropriate use cases. It covers all necessary aspects for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the selector parameter described as 'CSS selector matching the <table> element'. The tool description itself adds no additional meaning or constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Pull' and resource 'table', details the output structure {headers, rows, row_count}, and distinguishes from generic extraction by mentioning 'saves writing per-cell mapping eval' and listing specific table types (pricing, specs, finance/listings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use context ('Right tool for pricing tables, specs, finance/listings tables') and implies it's simpler than eval, but does not explicitly exclude alternative tools like table_to_json or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find localized text matches and return [{ref, tag, attrs, before, match, after, text}]. Ranks article/main/content matches above nav/header/footer boilerplate.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Substring to match (or exact string if exact=true) | |
| exact | No | If true, exact cleaned-text match instead of substring (default false) | |
| limit | No | Max matches to return (default 20) | |
| selector | No | Optional CSS selector to limit search scope | |
| context_chars | No | Characters before/after each match (default 80) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It reveals the ranking of content matches over boilerplate and the return structure. This is sufficient for a read-only search tool, though it lacks details like authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The result structure is front-loaded, making the purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description specifies the return shape and ranking behavior. It covers the essential behavior for a search tool, though it could benefit from mentioning the default context width (already in schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add extra parameter meaning. It adds no new information about parameters beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool finds localized text matches and returns a specific result structure. Mentions ranking behavior that distinguishes it from sibling tools like text, text_around, or text_main, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for finding text matches with context and ranking, but does not explicitly state when not to use it or compare to alternatives. No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse captured JSON/API/network responses into semantic objects with fields, scores, matched query terms, and capture/path provenance. Use after navigate or activate when network_stores shows JSON/GraphQL/NDJSON captures and raw body_preview is too noisy.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Optional substring filter on response host. | |
| limit | No | Max objects to return (default 50). | |
| query | No | Optional task query/goal used to rank objects. | |
| types | No | Optional object kinds to keep, e.g. product_card, article_card, model_card, network_object, card. | |
| nav_id | No | Defaults to the most recent navigation_id. Pass 'all' to inspect all captures. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the output structure (fields, scores, etc.) but does not detail error handling, performance, or side effects. The behavioral disclosure is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence front-loads the main purpose, and the second provides usage guidance. No extra words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and many sibling tools, the description covers the main purpose and usage context well. It includes specifics like the types parameter examples. Minor missing: handling of empty captures or invalid inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The tool description adds context about when to use parameters (e.g., 'query' for ranking) but does not provide significant additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Parse captured JSON/API/network responses into semantic objects with fields, scores, matched query terms, and capture/path provenance.' It uses specific verbs and resource, and distinguishes from siblings like network_stores and body by providing usage context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use: 'Use after navigate or activate when network_stores shows JSON/GraphQL/NDJSON captures and raw body_preview is too noisy.' This provides clear context, though it doesn't explicitly state when not to use or list alternative tools beyond body_preview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return content-bearing fetch/XHR responses captured during navigate, ranked by likely content value. SPAs often keep their data in API responses (JSON, GraphQL, NDJSON, Next/Nuxt route data) that are cleaner than the rendered DOM — this tool surfaces them directly. Each entry has capture_id, URL, status, content-type, body_preview (truncated to 256 KB), body_bytes (full size), body_truncated flag, navigation_id, and a heuristic score. Bodies for trackers/ads/CSS/HTML/media are NOT captured. The navigate result already contains a top-5 summary scoped to that navigation; use this tool to get more entries, filter by host, or pull captures from a different navigation.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Optional substring filter on response host. | |
| limit | No | Max entries to return (default 20). | |
| nav_id | No | Defaults to the most recent navigation_id (page B never sees page A captures). Pass an explicit navigation_id from a prior navigate result to query that navigation specifically. Pass 'all' to disable nav filtering and return captures from every navigation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description is thorough: discloses bodies not captured for trackers/ads/CSS/HTML/media, truncation at 256 KB, body_bytes and truncation flag, nav_id default and 'all' option, heuristic ranking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then explains SPA context, lists return fields, exclusions, and comparison to navigate. No wasted words, well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists all return fields (capture_id, URL, status, content-type, body_preview, etc.) and explains ranking and filtering. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds value for nav_id with detailed explanation of default and 'all' behavior. host and limit descriptions are similar to schema but clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns content-bearing fetch/XHR responses captured during navigate, ranked by content value. Distinguishes from navigate result summary and specifies SPA use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use (more entries, filter by host, different navigation) and when not to (top-5 summary already in navigate). No explicit alternatives but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drop all captured network responses from the session's network store. Use this between unrelated navigations if you don't want earlier captures showing up in later network_stores calls.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly describes a destructive action (drop all) and its effect on future calls. Does not mention irreversibility or side effects, but sufficient for a clear operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first describes action, second provides usage guidance. Front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description fully covers what it does and when to use it. Complete and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (0 params), so baseline 4 applies. Description adds no parameter information, which is acceptable as there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Drop all captured network responses from the session's network store.' Verb and resource are clear, and it distinguishes from sibling 'network_stores' which retrieves responses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use this between unrelated navigations if you don't want earlier captures showing up in later network_stores calls.' Does not mention when not to use, but the intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the current page into semantic, task-discoverable JSON objects. Reconstructs page structure as search_form, nav_link, article_card, course_card, model_card, product_card, table, answer_block, and limitation objects with actions, normalized fields, goal-based scoring, and provenance. Prefer this as the first planning tool after navigate when raw links/text are too wide.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | Optional task goal/query used to rank objects by relevance. | |
| limit | No | Max objects to return (default 50). | |
| types | No | Optional object kinds to return, e.g. search_form, article_card, model_card, course_card, card, table, answer_block. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes reconstruction of page structure into typed objects with actions and scoring. Lacks details on side effects or permissions, but for a read-only tool it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and object types, no wasted words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Three parameters described, no output schema, no annotations. Covers purpose, usage, and parameter semantics. Could explicitly state return format, but 'JSON objects' and listed types suffice. Fairly complete for a structured extraction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds context: goal is for relevance ranking, limit max objects, types list possible values. Overlap exists with schema, but description explains how goal affects scoring, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders the current page into semantic JSON objects, listing specific object types (search_form, nav_link, etc.) and mentions actions, normalized fields, scoring, and provenance. It distinguishes from siblings by recommending it as the first planning tool after navigate when raw links/text are too wide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Prefer this as the first planning tool after navigate when raw links/text are too wide,' providing clear when-to-use context and implying alternatives like raw extraction tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a CSS selector against the current page's parsed DOM. Returns matching elements as [{ref, tag, attrs, text, text_chars, text_truncated}]. Element refs (e:NN) are stable handles for use with click/type/submit. Selector engine supports tag, id, class, attribute matchers (=, ^=, $=, *=, ~=), all four combinators (descendant, >, +, ~), pseudo-classes (:first/last/nth-child including An+B formulas, :first/last/nth-of-type, :only-child/of-type), :not(), and :has().
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It details the return format, the stability of refs, and the comprehensive selector engine support, providing excellent transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet well-structured, front-loading purpose and return format before elaborating on selectors. It is a bit lengthy but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, no output schema, and clear sibling context, the description covers all essential aspects: purpose, return shape, usage with other tools, and selector capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the parameter description is minimal ('CSS selector'). The description adds significant value by detailing supported selectors and the purpose of the selector, but could include an example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a CSS selector against the DOM and returns matching elements with stable refs. It distinguishes itself from sibling tools like query_text (text search) and click/type (action tools).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for obtaining element handles for interaction, but does not explicitly state when not to use or compare to alternatives. However, the context of sibling tools makes usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose why a CSS selector did or did not match. Returns matched_count, sample matches, DOM summary counts, selector hints (top tags/classes/data attrs/ids), and actionable hints for selector_miss, thin_shell, or embedded_json. Use this when query() returns [] and you need to distinguish a bad selector from an empty/browser-rendered DOM.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max sample matches to return (default 10, max 50) | |
| selector | Yes | CSS selector to test |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the types of diagnostic hints returned, but does not mention potential side effects (none expected). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose and outputs, second gives usage guidance. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters fully covered by schema and no output schema, the description covers purpose, usage, and key outputs adequately. Missing explicit return format but lists fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (selector required, limit optional with defaults). Description adds minimal value beyond schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it diagnoses why a CSS selector did or did not match, listing specific outputs (matched_count, sample matches, DOM summary counts, selector hints, actionable hints). It distinguishes itself from siblings by mentioning usage when query() returns [].
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use this when query() returns [] and you need to distinguish a bad selector from an empty/browser-rendered DOM. Does not provide explicit when-not-to-use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find elements by visible text content. Returns the smallest/deepest element whose textContent matches the needle, with chrome (header/nav/footer/aside) skipped. Anchor-promotion: a span/strong/etc. inside an resolves to the anchor (so click() targets the actionable element). Right tool when CSS selectors are unstable (React-rendered pages with hashed class names) but the visible label is reliable — e.g. find a 'Sign in' button without knowing its class.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Substring to match (or exact string if exact=true) | |
| exact | No | If true, exact match instead of substring (default false) | |
| limit | No | Max matches to return (default 20) | |
| selector | No | Optional CSS selector to limit search scope (default: whole document body) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that chrome elements (header, nav, footer, aside) are skipped, anchor-promotion is performed, and it returns the deepest match. It also mentions default parameter values. Missing are potential side effects (none expected) and response format, but overall is quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet comprehensive. Every sentence adds value, starting with the core purpose, followed by behavioral details, and ending with a use case. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description covers purpose, behavior, defaults, and typical usage. It does not explain the return value structure, but for a simple tool the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is described in schema. The description adds default values (exact=false, limit=20, selector=document body) and clarifies behavior (e.g., text is substring by default). This goes beyond the schema, providing valuable context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds elements by visible text content, specifies it returns the smallest/deepest element, skips chrome elements, and promotes anchor elements. This specific verb+resource description distinguishes it from sibling tools like find_text and query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it's the right tool when CSS selectors are unstable but visible labels are reliable, with an example (find 'Sign in' button). It lacks explicit when-not-to-use or alternative tool names but provides clear context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bind a task outcome (success/failure/quality) to a previous navigation_id from a navigate() call. Used by the policy framework's outcome protocol — see docs/probabilistic-policy.md §4.5. v0 emits an outcome_reported NDJSON event for the navigation; no posterior updates yet. Drivers should call this once per agent task so future Bayesian phases (B/D-2) can attribute extraction success/failure to specific policy decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Optional human-readable error/explanation when success=false. | |
| quality | No | Optional 0..1 quality score (e.g. fraction of expected fields extracted). | |
| success | Yes | Did the agent's task succeed? | |
| task_id | No | Optional opaque id chosen by the driver for cross-system correlation. | |
| task_class | No | What kind of task succeeded/failed. Lets future posteriors condition on task class. | |
| navigation_id | Yes | The id returned by navigate() — joins this outcome to the policy_trace event. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does so by stating: 'v0 emits an outcome_reported NDJSON event for the navigation; no posterior updates yet.' This reveals side effects (emitting event) and limitations (no updates), providing adequate transparency for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each sentence earning its place: first states purpose, second ties to policy framework, third gives behavioral details and usage guidance. It is front-loaded with the core action and efficiently structured without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no annotations, and no output schema, the description covers purpose, usage, side effect (NDJSON event), and links to documentation. It does not explain return value format, but the mention of the emitted event suffices for an agent. The description is complete enough for an agent to understand the tool's role in the policy framework.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds value by contextualizing the purpose: it explains that navigation_id joins to policy_trace, task_class enums are listed, and error/quality are optional. This goes beyond the schema, giving the agent a better understanding of how parameters relate to the tool's goal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bind a task outcome (success/failure/quality) to a previous navigation_id from a navigate() call.' It specifies the verb (bind/report), resource (task outcome), and relation to navigation_id, distinguishing it from siblings like navigate or extract which are about navigation or extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Drivers should call this once per agent task so future Bayesian phases can attribute extraction success/failure to specific policy decisions.' It tells when to call and why, but does not explicitly state when not to use it or mention alternatives, which is acceptable given no sibling tool has similar function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find page-owned navigation/search routes for a goal. Returns ranked visible links, forms with controls/query_url previews, and inferred URLs derived from page-owned routes plus goal terms. Use before guessing URLs manually.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | Optional task goal/query used to rank routes and build GET query previews. | |
| limit | No | Max routes/forms/inferred URLs per section (default 30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns ranked links, forms with previews, and inferred URLs based on page routes and goal terms. However, it omits side effects, prerequisites (e.g., page loaded), or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the tool's purpose, output, and usage hint without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple output types, ranking, derivation), the description is thorough. It explains what is returned and how the goal parameter works. Lacks mention of required page state but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning: 'goal' ranks routes and builds GET query previews, 'limit' defaults to 30 per section. This helps the agent understand parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds navigation/search routes for a goal and lists the output types. However, it does not explicitly differentiate from sibling tools like 'discover' or 'navigate', which could confuse an AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using the tool before guessing URLs manually, providing a usage context. But it does not specify when not to use it or compare it to alternatives like 'navigate' or 'discover'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drain the JS event loop: alternately runs queued microtasks (Promise resolutions) and fires expired setTimeout/setInterval callbacks, sleeping to the next deadline when only timers remain. Returns when the queue is empty OR max_ms elapses OR max_iters iterations complete. Defaults: max_ms=2000, max_iters=50. Use after seeding the DOM (or after eval'd code that schedules timers) to let pending callbacks run.
| Name | Required | Description | Default |
|---|---|---|---|
| max_ms | No | Max wall-clock ms to spend (default 2000) | |
| max_iters | No | Max iterations of the drain loop (default 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It thoroughly explains the internal process: alternating microtasks and timers, sleeping to deadlines, and three stopping conditions (empty queue, max_ms, max_iters). Defaults are also specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences only, each serving a distinct purpose: process explanation, stopping conditions, usage guidance. No unnecessary words. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers behavior and parameters thoroughly. However, it does not describe the return value or expected output. Since there is no output schema, the description should ideally mention what the tool returns (e.g., boolean or void) for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by stating defaults (max_ms=2000, max_iters=50) and explaining the meaning of 'iterations' in the context of the drain loop. This supplements the schema effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Drain the JS event loop' and clearly identifies the resource and action. Unambiguously states what the tool does and distinguishes from sibling tools like 'eval' or 'click' which deal with other aspects of page interaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use after seeding the DOM (or after eval'd code that schedules timers) to let pending callbacks run.' This provides clear context and proper usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a form by gathering input/textarea/select values and navigating to the resolved action URL. Supports GET and application/x-www-form-urlencoded POST. Checked checkbox/radio values are serialized; multipart upload forms are not supported.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Form element ref like e:142 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: gathering values from elements, navigating to action URL, serializing checked checkboxes/radios, and lack of multipart support. It does not cover error handling or response behavior, but these are not critical given the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) with no wasted words. It front-loads the primary action and method support, then adds edge-case details (serialization, restriction) efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter tool without output schema, the description covers essential behavior, limitations, and supported cases. It does not explicitly state navigation behavior after submission, but the tool's role in a broader automation context (e.g., subsequent settle) makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'ref', and its schema description ('Form element ref like e:142') already explains its meaning. The tool description adds no additional details about the ref format or how to obtain it, so it provides no added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits a form by gathering input/textarea/select values and navigating to the action URL. It specifies supported methods (GET, POST) and explicitly excludes multipart forms, making the purpose distinct from sibling tools like click or navigate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use (form submission) and explicitly mentions unsupported multipart forms, but does not contrast with alternative tools for similar tasks (e.g., click on submit button). Still, it provides sufficient guidance for a typical form submission scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Alias for extract_table with a first-table default. Pulls a table into {headers, rows, row_count}; selector defaults to 'table'. Use this when an agent expects a table-to-JSON convenience tool.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | Optional CSS selector matching the <table> element (default: table) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are given, so the description carries full burden. It discloses the default selector, the output structure (headers, rows, row_count), and that it's an alias. It does not mention error handling or behavior when no table is found, but for a simple extraction, it's sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with key information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional param, no output schema), the description covers the purpose, default behavior, and output format completely. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the selector parameter well-described. The description adds little beyond stating the default, which is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's an alias for extract_table with a default selector, and specifies the output format {headers, rows, row_count}. It distinguishes itself from the sibling extract_table by positioning as a convenience tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool when an agent expects a table-to-JSON convenience tool, implying that for more control or different defaults, one should use extract_table. This provides clear context, though it lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the textContent of the FIRST element matching the selector (default: body). Note: on Wikipedia/MDN/news sites, the first is often a hatnote or image caption, not the lead paragraph — prefer text_main for reading the page's primary content.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | CSS selector (default: body) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it returns textContent of the FIRST matching element. With no annotations, it could further specify behavior on no match or hidden elements, but the description is still informative and accurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose, followed by a concise, valuable note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description provides sufficient context: what it does, a key caveat, and a sibling recommendation. Covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal new meaning beyond restating the default and that it's a CSS selector. The note about first element is already implied by the tool's function.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool gets the textContent of the first element matching a CSS selector, defaulting to body. Distinguishes from sibling text_main by noting scenarios where text_main is preferred.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises against using on Wikipedia/MDN/news sites and recommends the alternative tool text_main for reading primary content. Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return cleaned surrounding text around an element ref or the best ranked text match. Returns {ref, before, match, after, text}.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Optional element ref like e:142 | |
| text | No | Optional text to locate when ref is omitted | |
| selector | No | Optional CSS selector to scope context | |
| context_chars | No | Characters before/after the target (default 400) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not explain what 'cleaned' means, behavior on multiple matches, or side effects. Minimal disclosure of behavior beyond the basic output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of one sentence plus the return shape. It is front-loaded with purpose. However, it could benefit from slightly more detail on usage without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return value adequately given no output schema. However, it lacks context on error scenarios, performance, or how it interacts with other tools. Complex enough to warrant a bit more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add significant additional meaning beyond the parameter descriptions. It gives a helpful example for 'ref' and default for 'context_chars', but overall baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns cleaned surrounding text based on an element ref or text match, and lists the return shape. It is specific but does not explicitly differentiate from sibling tools like 'find_text' or 'text_clean'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention when it is appropriate to use ref vs text, or what to do when both are omitted. No context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return chrome-stripped, JSON-stripped, whitespace-collapsed text from a selector or the best content root. Drops script/style/noscript/svg and page chrome (nav/header/footer/aside) plus obvious hidden widgets and repeated boilerplate.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | Optional CSS selector to scope extraction. Default: best content root. | |
| max_chars | No | Optional max characters to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description transparently discloses stripping behavior: dropping scripts, styles, chrome elements, and hidden widgets. It also mentions whitespace collapsing. Missing details on rate limits or auth, but for a read tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Every word adds value, clearly stating input options and stripping behavior. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the stripping behavior well but does not specify the return format (e.g., plain text with line breaks), error handling, or how the 'best content root' is determined. With no output schema, the agent lacks details on what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for max_chars and selector. The tool description adds no extra information beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns chrome-stripped, JSON-stripped, whitespace-collapsed text from a selector or best content root. It lists specific elements dropped (script, nav, header, etc.), making the purpose distinct from sibling tools like text_main or body.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies usage for cleaned text, but does not compare directly to sibling tools like text_main, body, or extract, leaving the agent to infer the best choice without clear differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the textContent of the page's main content area, excluding chrome (header/nav/footer/aside). Tries , then [role=main], then a single , then falls back to the longest non-chrome subtree. Use this for reading article body / docs page / blog post content.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It discloses fallback strategy (<main>, [role=main], single <article>, longest non-chrome subtree), which is good transparency. No mention of failure behavior or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then fallback, then usage hint. Every sentence is earned, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description fully covers purpose, behavior, and usage context. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, baseline 4. Description adds value beyond schema by explaining fallback logic and usage intention.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('Get'), resource ('textContent of the main content area'), and distinguishes from siblings by excluding chrome and detailing fallback logic. It is specific and helpful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context ('reading article body / docs page / blog post content') but does not mention when not to use or compare to alternatives like 'body' or 'text'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the value of an input/textarea (referenced by ref) and dispatch input + change events. Use before submit on form fields.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Input element ref like e:142 | |
| text | Yes | Value to set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it dispatches input and change events, which is key behavioral info. Without annotations, this is valuable. Could mention error handling or if it triggers other listeners, but sufficient for a simple input tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences: first explains the action, second gives usage context. No fluff, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 required string params and no output schema, the description covers purpose and usage. Could mention what happens on invalid ref, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Set value), the target (input/textarea), and the side effects (dispatches input + change events). It distinguishes itself from siblings like 'click' or 'submit' by specifying it's for form field input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use before submit on form fields.', providing clear context for when to use this tool vs. alternatives like 'submit' or 'click'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.3navigate1 field changedInput schema / properties / include_ascii{
"description": "Include human-readable ASCII blockmap grid (redundant with JSON fields). Default false.",
"type": "boolean"
}v0.1.0activateblockmapbodyclickcookies_clearcookies_getcookies_setdiscoverevalextractextract_cardsextract_listextract_tablefind_textnavigatenetwork_extractnetwork_storesnetwork_stores_clearpage_modelqueryquery_debugquery_textreport_outcomeroute_discoversettlesubmittable_to_jsontexttext_aroundtext_cleantext_maintypeEach tool has a clearly distinct purpose with specific use cases. For example, text, text_main, text_around, and text_clean all deal with text extraction but target different contexts. Similarly, extract, extract_cards, extract_list, and extract_table are different strategies. No two tools appear to do exactly the same thing.
Most tool names follow a predictable pattern: verbs (navigate, click, type) or noun phrases (blockmap, page_model). Some tools use verb_noun (cookies_set, network_stores) or compound names (extract_cards, route_discover). A minor inconsistency is 'text' vs 'text_main' etc., and 'table_to_json' as an alias, but overall clear and readable.
With 32 tools, the server covers a wide range of browser automation tasks. Each tool seems justified, but the count is on the high side. While the domain is complex, some tools like text variants could potentially be merged, making the surface heavier than necessary.
The tool set covers navigation, element interaction, data extraction, network inspection, cookie management, and more. It includes both high-level (discover, extract) and low-level (query, click) tools. Minor gaps might include handling iframes or file downloads, but for typical web scraping tasks, it is comprehensive.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Headless browser primitives for AI agents when sites need real JS rendering.
One MCP for the Web. Easily search, crawl, navigate, and extract websites without getting blocked.…
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/protostatis/unbrowser'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
