Skip to main content
Glama
dmytrome

Groundhog

by dmytrome
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Read a URL

read_url
Read-only

Fetch one web page through a stealth browser to return clean, provenance-tracked content with hidden text stripped, grounding answers in live sites that block plain fetchers.

Instructions

Fetch one web page through the stealth browser and return clean, grounded content with provenance.

Hidden text injected for models but invisible to humans is stripped by default and reported in threats. Use this to ground answers in live web content, including sites that block plain fetchers.

Reads a URL you already have: use search to find URLs, or research to search and read in one call. Fetches are rate limited per domain (5s apart by default), so several pages from one site are not instant.

Input Schema

NameRequiredDescriptionDefault
urlYesAbsolute http(s) URL. Private and loopback addresses are refused.
queryNoWhen set, the content is built from the passages most relevant to it, and `matches` lists each one's heading, offset and score for citation; it carries no text. If nothing matches, `matches` is empty and the whole page is returned; if something matches but none of it fits `max_tokens` (a large code block), `markdown` is empty and `truncated` is true, so raise `max_tokens`. On a long page the relevant passages can still be most of it, so set `max_tokens` to bound the read.
formatNo'markdown' extracts the article; 'text' returns the page's rendered text.markdown
max_tokensNoToken budget for the content. Omit it, or pass a value below 1, to use the server's GROUNDHOG_MAX_TOKENS (20000 by default).
include_hiddenNoKeep text that is invisible to a human reader. It is reported in `threats` either way; this only controls whether it stays in the content.

Output Schema

NameRequiredDescriptionDefault
urlYes
titleYes
statusYes
matchesYes
threatsYes
markdownYes
final_urlYes
set_asideYes
truncatedYes
fetched_atYes
provenanceYes
http_statusYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.22.0
    • changedOutput schema / $defs / Threat / properties / type / enum
      Previous value: -[
-  "hidden_css",
-  "hidden_attribute",
-  "hidden_template",
-  "report_truncated",
-  "final_url_suppressed",
-  "detection_degraded",
-  "strip_incomplete",
-  "zero_width",
-  "bidi",
-  "tag"
-]New value: +[
+  "hidden_css",
+  "hidden_attribute",
+  "hidden_template",
+  "hidden_pdf",
+  "report_truncated",
+  "final_url_suppressed",
+  "detection_degraded",
+  "strip_incomplete",
+  "zero_width",
+  "bidi",
+  "tag"
+]
  2. Changed5 schema fields changedv0.20.1
    • changedInput schema / properties / max_tokens / description
      Previous value: -"Token budget for the content. Omit to use the server's GROUNDHOG_MAX_TOKENS (20000 by default). Must be positive."New value: +"Token budget for the content. Omit it, or pass a value below 1, to use the server's GROUNDHOG_MAX_TOKENS (20000 by default)."
    • changedInput schema / properties / query / description
      Previous value: -"When set, the content is built from the passages most relevant to it, and `matches` lists each one's heading, offset and score for citation; it carries no text. If nothing matches, `matches` is empty and the whole page is returned. On a long page the relevant passages can still be most of it, so set `max_tokens` to bound the read."New value: +"When set, the content is built from the passages most relevant to it, and `matches` lists each one's heading, offset and score for citation; it carries no text. If nothing matches, `matches` is empty and the whole page is returned; if something matches but none of it fits `max_tokens` (a large code block), `markdown` is empty and `truncated` is true, so raise `max_tokens`. On a long page the relevant passages can still be most of it, so set `max_tokens` to bound the read."
    • addedOutput schema / $defs / Match / properties / clamped
      Added value: +{
+  "title": "Clamped",
+  "type": "boolean"
+}
    • changedOutput schema / $defs / Match / required
      Previous value: -[
-  "id",
-  "heading",
-  "offset",
-  "end",
-  "score"
-]New value: +[
+  "id",
+  "heading",
+  "offset",
+  "end",
+  "score",
+  "clamped"
+]
    • changedOutput schema / properties / status / enum
      Previous value: -[
-  "ok",
-  "challenge",
-  "blocked",
-  "rate_limited",
-  "not_found",
-  "server_error",
-  "unsupported_content",
-  "empty",
-  "unknown"
-]New value: +[
+  "ok",
+  "challenge",
+  "blocked",
+  "rate_limited",
+  "not_found",
+  "server_error",
+  "unsupported_content",
+  "empty",
+  "too_large",
+  "unknown"
+]
  3. Changed1 schema field changedv0.19.1
    • changedOutput schema / properties / status / enum
      Previous value: -[
-  "ok",
-  "challenge",
-  "blocked",
-  "rate_limited",
-  "not_found",
-  "server_error",
-  "unsupported_content",
-  "unknown"
-]New value: +[
+  "ok",
+  "challenge",
+  "blocked",
+  "rate_limited",
+  "not_found",
+  "server_error",
+  "unsupported_content",
+  "empty",
+  "unknown"
+]
  4. Changed4 schema fields changedv0.18.0
    • changedInput schema / properties / query / description
      Previous value: -"When set, `matches` carries the passages most relevant to it, each with its heading and offset for citation."New value: +"When set, the content is built from the passages most relevant to it, and `matches` lists each one's heading, offset and score for citation; it carries no text. If nothing matches, `matches` is empty and the whole page is returned. On a long page the relevant passages can still be most of it, so set `max_tokens` to bound the read."
    • addedOutput schema / $defs / Match / properties / end
      Added value: +{
+  "title": "End",
+  "type": "integer"
+}
    • addedOutput schema / $defs / Match / properties / id
      Added value: +{
+  "title": "Id",
+  "type": "string"
+}
    • changedOutput schema / $defs / Match / required
      Previous value: -[
-  "heading",
-  "offset",
-  "score"
-]New value: +[
+  "id",
+  "heading",
+  "offset",
+  "end",
+  "score"
+]
  5. Changed2 schema fields changedv0.16.1
    • addedOutput schema / properties / set_aside
      Added value: +{
+  "title": "Set Aside",
+  "type": "integer"
+}
    • changedOutput schema / required
      Previous value: -[
-  "markdown",
-  "title",
-  "url",
-  "final_url",
-  "fetched_at",
-  "status",
-  "http_status",
-  "truncated",
-  "threats",
-  "matches",
-  "provenance"
-]New value: +[
+  "markdown",
+  "title",
+  "url",
+  "final_url",
+  "fetched_at",
+  "status",
+  "http_status",
+  "truncated",
+  "threats",
+  "matches",
+  "set_aside",
+  "provenance"
+]
  6. Changed1 schema field changedv0.15.0
    • addedOutput schema / $defs / Threat / properties / seen
      Added value: +{
+  "title": "Seen",
+  "type": "integer"
+}
  7. Changed1 schema field changedv0.13.0
    • changedOutput schema / $defs / Threat / properties / type / enum
      Previous value: -[
-  "hidden_css",
-  "report_truncated",
-  "final_url_suppressed",
-  "detection_degraded",
-  "strip_incomplete",
-  "zero_width",
-  "bidi",
-  "tag"
-]New value: +[
+  "hidden_css",
+  "hidden_attribute",
+  "hidden_template",
+  "report_truncated",
+  "final_url_suppressed",
+  "detection_degraded",
+  "strip_incomplete",
+  "zero_width",
+  "bidi",
+  "tag"
+]
  8. Changed3 schema fields changedv0.10.0
    • addedOutput schema / properties / http_status
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "title": "Http Status"
+}
    • addedOutput schema / properties / status
      Added value: +{
+  "enum": [
+    "ok",
+    "challenge",
+    "blocked",
+    "rate_limited",
+    "not_found",
+    "server_error",
+    "unsupported_content",
+    "unknown"
+  ],
+  "title": "Status",
+  "type": "string"
+}
    • changedOutput schema / required
      Previous value: -[
-  "markdown",
-  "title",
-  "url",
-  "final_url",
-  "fetched_at",
-  "truncated",
-  "threats",
-  "matches",
-  "provenance"
-]New value: +[
+  "markdown",
+  "title",
+  "url",
+  "final_url",
+  "fetched_at",
+  "status",
+  "http_status",
+  "truncated",
+  "threats",
+  "matches",
+  "provenance"
+]
  9. Changed5 schema fields changedv1.0.0
    • addedInput schema / properties / format / description
      Added value: +"'markdown' extracts the article; 'text' returns the page's rendered text."
    • addedInput schema / properties / include_hidden / description
      Added value: +"Keep text that is invisible to a human reader. It is reported in `threats` either way; this only controls whether it stays in the content."
    • addedInput schema / properties / max_tokens / description
      Added value: +"Token budget for the content. Omit to use the server's GROUNDHOG_MAX_TOKENS (20000 by default). Must be positive."
    • addedInput schema / properties / query / description
      Added value: +"When set, `matches` carries the passages most relevant to it, each with its heading and offset for citation."
    • addedInput schema / properties / url / description
      Added value: +"Absolute http(s) URL. Private and loopback addresses are refused."
  10. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Goes beyond the readOnlyHint/openWorldHint annotations by disclosing two real behaviors: injected hidden text is stripped by default and reported in `threats`, and fetches are rate limited per domain (5s apart). It does not describe failure modes such as blocked, paywalled, or timed-out fetches, so the behavioral picture is strong but not complete.

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

Conciseness5/5

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

The capability sentence is front-loaded, followed by the security behavior, the alternative-tool routing, and the rate-limit caveat. Four short paragraphs, each carrying distinct information an agent needs before calling.

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

Completeness5/5

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

With an output schema covering return values and annotations covering safety, the description supplies the remaining context an agent needs: what the browser is, how hidden text is handled, how it differs from `search`/`research`, and latency expectations. Nothing essential to a correct call is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the `query`, `format`, `max_tokens`, and `include_hidden` docs are already detailed. The description's 'stripped by default and reported in `threats`' largely restates the `include_hidden` schema text, so it adds little parameter meaning beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch one web page') plus the distinguishing mechanism ('stealth browser') and output quality ('clean, grounded content with provenance'). It also names the two siblings it is not: 'use `search` to find URLs, or `research` to search and read in one call.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('ground answers in live web content, including sites that block plain fetchers') and an explicit precondition ('Reads a URL you already have') that routes URL discovery to `search`/`research`. The per-domain rate-limit note sets expectations for multi-page reads.

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

Deploy Server

Other Tools