doc-scraper

Overview Schema Source Related Servers Discussions Admin

diff_crawl

Read-onlyIdempotent

Compare the latest documentation crawl against a previous or since-defined baseline to return added, removed, and changed pages using hash-based history verdicts.

Instructions

Return added/removed/changed pages between the latest crawl and a baseline crawl: the crawl before it by default, or with since, the most recent crawl whose crawl_ended_at <= since. Hash-based verdicts from the SQLite history index. To see what a crawl changed, run crawl_site, wait for it to finish, then call diff_crawl without since.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site_key": "<site_key>"
    },
    "name": "diff_crawl"
  }
}

Input Schema

Name	Required	Description
`since`	No	RFC3339 timestamp; the most recent crawl whose crawl_ended_at <= since, compared to the second, is the baseline (e.g. 2026-05-23T22:00:00Z). Omit to compare with the previous crawl.
`offset`	No	Pagination offset, 0-based
`site_key`	Yes	Site key from config
`max_results`	No	Maximum diff entries to return (default: 100, max: 1000; larger values are capped, 0 means the default)

Output Schema

Name	Required	Description
`note`	No	Why the diff is empty or partial, when it is
`added`	Yes
`since`	No	Present when since was given
`total`	Yes
`offset`	Yes
`changed`	Yes
`removed`	Yes
`returned`	Yes
`site_key`	Yes
`max_results`	Yes
`current_crawl`	No
`baseline_crawl`	No
`unchanged_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.26.0Nov 10, 2026

changedInput schema / properties / max_results / description

Previous value: -"Maximum diff entries to return (default: 100, max: 1000; larger values are capped, 0 or less means the default)"New value: +"Maximum diff entries to return (default: 100, max: 1000; larger values are capped, 0 means the default)"

addedInput schema / properties / max_results / minimum
```
Added value: +0
```
addedInput schema / properties / offset / minimum
```
Added value: +0
```

Changed7 schema fields changedv2.21.0Oct 21, 2026

changedInput schema / properties / max_results / description

Previous value: -"Maximum diff entries to return (default 100, max 1000)"New value: +"Maximum diff entries to return (default: 100, max: 1000; larger values are capped, 0 or less means the default)"

changedInput schema / properties / max_results / type
```
Previous value: -"number"New value: +"integer"
```

changedInput schema / properties / offset / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / since / description

Previous value: -"RFC3339 timestamp; the most recent crawl whose crawl_ended_at <= since, compared to the second, is the baseline (e.g. 2026-05-23T22:00:00Z)"New value: +"RFC3339 timestamp; the most recent crawl whose crawl_ended_at <= since, compared to the second, is the baseline (e.g. 2026-05-23T22:00:00Z). Omit to compare with the previous crawl."

changedInput schema / required

Previous value: -[
-  "site_key",
-  "since"
-]New value: +[
+  "site_key"
+]

addedOutput schema / properties / since / description
```
Added value: +"Present when since was given"
```

changedOutput schema / required

Previous value: -[
-  "site_key",
-  "since",
-  "added",
-  "removed",
-  "changed",
-  "unchanged_count",
-  "total",
-  "returned",
-  "offset",
-  "max_results"
-]New value: +[
+  "site_key",
+  "added",
+  "removed",
+  "changed",
+  "unchanged_count",
+  "total",
+  "returned",
+  "offset",
+  "max_results"
+]

Changed1 schema field changedv2.15.0Oct 17, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "added": {
+      "items": {
+        "properties": {
+          "content_hash": {
+            "type": "string"
+          },
+          "depth": {
+            "type": "integer"
+          },
+          "prior_hash": {
+            "description": "Baseline hash; changed entries only",
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "url",
+          "title",
+          "content_hash",
+          "depth"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "baseline_crawl": {
+      "properties": {
+        "crawl_ended_at": {
+          "type": "string"
+        },
+        "crawl_id": {
+          "type": "integer"
+        },
+        "crawl_started_at": {
+          "type": "string"
+        },
+        "mode": {
+          "description": "full or incremental",
+          "type": "string"
+        },
+        "total_pages": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "crawl_id",
+        "crawl_started_at",
+        "crawl_ended_at",
+        "total_pages",
+        "mode"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "changed": {
+      "items": {
+        "properties": {
+          "content_hash": {
+            "type": "string"
+          },
+          "depth": {
+            "type": "integer"
+          },
+          "prior_hash": {
+            "description": "Baseline hash; changed entries only",
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "url",
+          "title",
+          "content_hash",
+          "depth"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "current_crawl": {
+      "properties": {
+        "crawl_ended_at": {
+          "type": "string"
+        },
+        "crawl_id": {
+          "type": "integer"
+        },
+        "crawl_started_at": {
+          "type": "string"
+        },
+        "mode": {
+          "description": "full or incremental",
+          "type": "string"
+        },
+        "total_pages": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "crawl_id",
+        "crawl_started_at",
+        "crawl_ended_at",
+        "total_pages",
+        "mode"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "max_results": {
+      "type": "integer"
+    },
+    "note": {
+      "description": "Why the diff is empty or partial, when it is",
+      "type": "string"
+    },
+    "offset": {
+      "type": "integer"
+    },
+    "removed": {
+      "items": {
+        "properties": {
+          "content_hash": {
+            "type": "string"
+          },
+          "depth": {
+            "type": "integer"
+          },
+          "prior_hash": {
+            "description": "Baseline hash; changed entries only",
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "url",
+          "title",
+          "content_hash",
+          "depth"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "returned": {
+      "type": "integer"
+    },
+    "since": {
+      "type": "string"
+    },
+    "site_key": {
+      "type": "string"
+    },
+    "total": {
+      "type": "integer"
+    },
+    "unchanged_count": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "site_key",
+    "since",
+    "added",
+    "removed",
+    "changed",
+    "unchanged_count",
+    "total",
+    "returned",
+    "offset",
+    "max_results"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv2.12.0Oct 15, 2026

changedInput schema / properties / since / description

Previous value: -"RFC3339 timestamp; the most recent crawl whose crawl_ended_at <= since is the baseline (e.g. 2026-05-23T22:00:00Z)"New value: +"RFC3339 timestamp; the most recent crawl whose crawl_ended_at <= since, compared to the second, is the baseline (e.g. 2026-05-23T22:00:00Z)"

First observedSep 6, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: verdicts are hash-based and drawn from the SQLite history index, and the latest crawl must have finished before a diff is meaningful. It does not discuss pagination or cost on large diffs, but the output schema covers return shape, so this is a strong addition rather than a gap.

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?

Three sentences, purpose first, no filler. The opening sentence is dense with an embedded baseline clause that takes a second read, but nothing is redundant enough to cut.

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, full parameter descriptions, and rich annotations, the remaining burden on the description is the baseline-selection model and the sequencing with crawl_site, both of which are covered. Nothing an agent needs to call this correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, including the RFC3339 example for since, the default/max behavior for max_results, and 0-based offset, so the schema does the heavy lifting. The description restates the since semantics and the omitted-since default without adding syntax or edge-case detail beyond them, which is the baseline case.

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 plus scope: returns added/removed/changed pages between the latest crawl and a baseline. That verb-and-resource pairing is distinct from siblings like crawl_site (trigger a crawl) or get_page (read one page), so an agent can select it without opening the schema.

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

Usage Guidelines5/5

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

Gives explicit default behavior (baseline = the crawl immediately before), the override condition (pass since for an arbitrary baseline), and a concrete workflow: run crawl_site, wait for completion, then call diff_crawl without since. Both when-to-use and the ordering constraint relative to crawl_site are stated rather than inferred.

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

Deploy Server