CrawlForge MCP Server

read_result

Read-onlyIdempotent

Use this to read a result that came back with truncated: true and a result_handle - the tool kept the whole result for 1 hour and returned a preview.

Instructions

Use this to read a result that came back with truncated: true and a result_handle - the tool kept the whole result for 1 hour and returned a preview. operation:"search" finds a literal query with offsets and context, "slice" returns characters from an offset, "lines" pages by line, "json_path" reads one subtree of a JSON result (crawl_deep pages, batch results, a fetch_url JSON body). Not a fetching tool: never call the original tool again while the handle is valid, and not for a result that arrived whole. Cost: 1 credit. Example: read_result({handle: "res_…", operation: "search", query: "pricing"})

Input Schema

Name	Required	Description
`path`	No	json_path: dotted keys and array indexes from the root of the stored result, e.g. "results[3].content"; a key holding a "." in brackets, e.g. files["llms.txt"]; a JSON string field is read into, e.g. "body.items[0]" for a fetch_url JSON body — not JSONPath
`query`	No	search: the text to find, matched literally, case-insensitive
`handle`	Yes	The result_handle a truncated result returned (res_… or a batch id)
`length`	No	slice: characters to return (default 10,000); lines: lines to return (default 200, max 5,000)
`offset`	No	slice: first character (default 0); lines: first line index (default 0)
`operation`	Yes	slice: characters from offset; search: case-insensitive literal query with context and offsets; lines: a page of lines; json_path: one subtree of a JSON result
`max_matches`	No	search: matches to return (default 20)
`max_inline_chars`	No	Largest result to return inline, in characters of its JSON. Over it, the call returns a preview plus a result_handle for read_result instead of the whole result (default 40,000; env CRAWLFORGE_MAX_INLINE_CHARS)

Output Schema

Name	Required	Description
`path`	No
`text`	No	slice: verbatim view.slice(offset, offset + length)
`tool`	No	The tool that produced the stored result
`view`	No
`_cost`	No	Cost-transparency metadata (D3.5): what this call was projected to cost and what it was charged
`cache`	No	Page cache: whether this call reused a copy of the page fetched earlier in the session
`lines`	No
`query`	No
`value`	No	json_path: the subtree; null with a preview when it is over max_inline_chars
`handle`	No
`length`	No	slice: characters returned
`offset`	No	slice: first character returned
`matches`	No	search: matches with 200 chars of context each side
`preview`	No
`has_more`	No	slice/lines: more follows the returned range
`warnings`	No
`next_step`	No	Failed calls only: the tool or fix to try next
`operation`	No
`truncated`	No	search: more matches than returned; json_path: value replaced by a preview
`view_path`	No
`expires_at`	No
`first_line`	No
`line_count`	No
`char_offset`	No	lines: view offset of the first returned line
`total_chars`	No	Length of the full view
`total_lines`	No
`value_chars`	No
`total_matches`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv6.24.0Oct 23, 2026

changedInput schema / properties / path / description

Previous value: -"json_path: dotted keys and array indexes, e.g. \"results[3].content\" — not JSONPath"New value: +"json_path: dotted keys and array indexes from the root of the stored result, e.g. \"results[3].content\"; a key holding a \".\" in brackets, e.g. files[\"llms.txt\"]; a JSON string field is read into, e.g. \"body.items[0]\" for a fetch_url JSON body — not JSONPath"

changedOutput schema / properties / _cost / description

Previous value: -"Cost-transparency metadata (D3.5), present when injected into the text copy of the result"New value: +"Cost-transparency metadata (D3.5): what this call was projected to cost and what it was charged"

changedOutput schema / properties / _cost / properties / actual / description

Previous value: -"Credits actually charged (0 in creator mode, half-rate on error)"New value: +"Credits actually charged (0 in creator mode, and 0 for a failed call)"

addedOutput schema / properties / cache

Added value: +{
+  "additionalProperties": {},
+  "description": "Page cache: whether this call reused a copy of the page fetched earlier in the session",
+  "properties": {
+    "ageMs": {
+      "description": "Age of that copy in ms",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "fetchedAt": {
+      "description": "When the oldest page used was fetched (ISO 8601)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "note": {
+      "description": "Hits only: how old the copy is and how to force a fresh fetch",
+      "type": "string"
+    },
+    "state": {
+      "description": "hit: every page came from this session's copy; bypass: fetched fresh on request (maxAge 0) or not cacheable; miss: fetched",
+      "enum": [
+        "hit",
+        "miss",
+        "bypass"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / next_step

Added value: +{
+  "description": "Failed calls only: the tool or fix to try next",
+  "type": "string"
+}

Addedv6.0.0Sep 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds the facts annotations cannot: a 1-hour retention window, preview-plus-handle behavior, and a cost of 1 credit. That is exactly the extra context an agent needs before deciding to spend a call.

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

Conciseness4/5

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

Front-loaded with the trigger condition (truncated: true + result_handle) followed by usage constraints, operations, cost, and an example. Dense but nearly every clause carries information; the operation list partially restates the enum descriptions in the schema.

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

Completeness5/5

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

For an 8-param tool with an output schema and full annotations, the description covers the trigger, the alternatives, retention, cost, and per-operation routing. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what each operation does in practice and supplying a concrete call example. It does not touch max_inline_chars or the offset/length defaults, but those are fully documented in the schema.

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+resource (read a result that returned truncated: true with a result_handle) and immediately scopes it against the obvious mistake — it is explicitly 'Not a fetching tool'. No sibling does this job, and the description makes that separation obvious.

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?

Gives explicit when-not-to-use rules: never re-call the original tool while the handle is valid, and do not use it for a result that arrived whole. It also routes among the four operations by naming the situation each fits (search, slice, lines, json_path for crawl_deep pages, batch results, fetch_url JSON bodies).

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