doc-scraper

Overview Schema Source Related Servers Discussions Admin

describe_server

Read-onlyIdempotent

Returns server identity, configured sites, and recent crawl jobs in one call to orient you before using other tools.

Instructions

Returns server identity, configured sites, and recent crawl jobs in one call. Call this first to orient yourself: it consolidates what would otherwise require list_sites plus several get_job_status calls. The MCP tool list is already advertised by the protocol so it is not duplicated here.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "describe_server"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description
`sites`	Yes
`server`	Yes
`total_jobs`	Yes
`jobs_capped`	Yes
`recent_jobs`	Yes	Newest first, at most 20
`total_sites`	Yes
`next_actions`	Yes
`config_writes`	Yes	enabled or disabled; save_site needs enabled (mcp-server -allow-config-writes)

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv2.24.1Oct 29, 2026

addedOutput schema / properties / recent_jobs / items / properties / failures

Added value: +{
+  "description": "Failed pages by class (temporary, gone, selector, policy, other), each with a count and one sample",
+  "items": {
+    "properties": {
+      "class": {
+        "type": "string"
+      },
+      "count": {
+        "type": "integer"
+      },
+      "sample_error": {
+        "type": "string"
+      },
+      "sample_url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "class",
+      "count",
+      "sample_url",
+      "sample_error"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / recent_jobs / items / properties / pages_carried_forward

Added value: +{
+  "description": "Pages that failed temporarily and kept their copy from the previous crawl",
+  "type": "integer"
+}

addedOutput schema / properties / recent_jobs / items / properties / pages_failed

Added value: +{
+  "description": "Pages that failed; noindex pages are neither saved nor failed",
+  "type": "integer"
+}

addedOutput schema / properties / recent_jobs / items / properties / pages_saved

Added value: +{
+  "description": "Pages written by this crawl",
+  "type": "integer"
+}

addedOutput schema / properties / recent_jobs / items / properties / refused

Added value: +{
+  "description": "Set when a finished crawl was kept back instead of published: empty, temporary_failures or shrink",
+  "type": "string"
+}

changedOutput schema / properties / recent_jobs / items / required

Previous value: -[
-  "job_id",
-  "site_key",
-  "status",
-  "started_at",
-  "pages_processed",
-  "pages_queued",
-  "pages_unchanged",
-  "incremental"
-]New value: +[
+  "job_id",
+  "site_key",
+  "status",
+  "started_at",
+  "pages_processed",
+  "pages_queued",
+  "pages_unchanged",
+  "pages_saved",
+  "pages_failed",
+  "pages_carried_forward",
+  "incremental"
+]

Changed2 schema fields changedv2.24.0Oct 25, 2026

addedOutput schema / properties / config_writes

Added value: +{
+  "description": "enabled or disabled; save_site needs enabled (mcp-server -allow-config-writes)",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "server",
-  "sites",
-  "recent_jobs",
-  "total_sites",
-  "total_jobs",
-  "jobs_capped",
-  "next_actions"
-]New value: +[
+  "server",
+  "sites",
+  "recent_jobs",
+  "total_sites",
+  "total_jobs",
+  "jobs_capped",
+  "config_writes",
+  "next_actions"
+]

Changed1 schema field changedv2.21.0Oct 21, 2026
- addedOutput schema / properties / recent_jobs / items / properties / pages_queued / description
```
Added value: +"Pages waiting to be crawled; for a cancelled job, the pages left uncrawled"
```

Changed1 schema field changedv2.15.0Oct 17, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "jobs_capped": {
+      "type": "boolean"
+    },
+    "next_actions": {
+      "type": "string"
+    },
+    "recent_jobs": {
+      "description": "Newest first, at most 20",
+      "items": {
+        "properties": {
+          "completed_at": {
+            "type": "string"
+          },
+          "duration_seconds": {
+            "description": "Present once completed_at is",
+            "type": [
+              "null",
+              "number"
+            ]
+          },
+          "error_message": {
+            "type": "string"
+          },
+          "incremental": {
+            "type": "boolean"
+          },
+          "job_id": {
+            "type": "string"
+          },
+          "pages_processed": {
+            "type": "integer"
+          },
+          "pages_queued": {
+            "type": "integer"
+          },
+          "pages_unchanged": {
+            "description": "Incremental re-checks whose content had not changed; not counted in pages_processed",
+            "type": "integer"
+          },
+          "site_key": {
+            "type": "string"
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "status": {
+            "description": "pending, running, completed, failed or cancelled",
+            "type": "string"
+          }
+        },
+        "required": [
+          "job_id",
+          "site_key",
+          "status",
+          "started_at",
+          "pages_processed",
+          "pages_queued",
+          "pages_unchanged",
+          "incremental"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "server": {
+      "properties": {
+        "config_path": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "version",
+        "config_path"
+      ],
+      "type": "object"
+    },
+    "sites": {
+      "items": {
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "key": {
+            "type": "string"
+          },
+          "last_crawled": {
+            "type": "string"
+          },
+          "status": {
+            "description": "\"running\" while a crawl is active; absent otherwise",
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "domain"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "total_jobs": {
+      "type": "integer"
+    },
+    "total_sites": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "server",
+    "sites",
+    "recent_jobs",
+    "total_sites",
+    "total_jobs",
+    "jobs_capped",
+    "next_actions"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv2.10.1Oct 13, 2026
- addedInput schema / properties
```
Added value: +{}
```
- addedInput schema / required
```
Added value: +[]
```
First observedSep 6, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful context that the call returns consolidated identity, sites, and recent job data in one call, though it does not discuss pagination, caching, or response limits.

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 description is front-loaded with what the tool returns, followed by when to call it and why. All three sentences contribute directly to selecting and understanding the tool, with no wasted wording.

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?

Given the rich annotations, no parameters, and an output schema, the description is sufficiently complete. It explains the tool's purpose, usage, consolidation value, and even clarifies why the MCP tool list is not included.

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?

There are zero parameters, so parameter semantics are inherently simple. The description does not need to explain parameters, and the baseline for a no-parameter tool applies.

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

Purpose5/5

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

The description states a specific verb and resources: returns server identity, configured sites, and recent crawl jobs. It clearly distinguishes itself from siblings by explaining that it consolidates what would otherwise require list_sites plus several get_job_status calls.

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

Usage Guidelines5/5

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

It gives explicit usage guidance: 'Call this first to orient yourself.' It also names the alternatives it replaces (list_sites and several get_job_status calls), leaving little ambiguity about when to use this tool versus its siblings.

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

Deploy Server