Document Extract Tool

document_extract converts documents you upload to GoClaw into clean markdown that your LLM can actually read. It handles formats that most LLMs can’t open natively: PDFs (including scanned ones), Microsoft Office files, EPUB / MOBI e-books, HTML, and plain text.

Under the hood it uses the go-markitdown library; embedded images and OCR route through your configured agent model chain.

When the agent uses it

Whenever you upload a supported document to GoClaw (over Telegram, Discord, the TUI, HTTP, etc.), the gateway annotates the attachment with a hint telling the agent it can call document_extract to actually read the contents. The agent decides whether to call it — you don’t have to ask.

You can also explicitly ask things like:

“Read this PDF and summarise it.”

and the agent will call document_extract on whatever file you attached.

Supported formats

Images are not supported here — use the regular image tools (read with an image path) or send the image directly; vision models handle those natively.

Parameters

Response

A successful call returns structured JSON:

{
  "ok": true,
  "format": "pdf",
  "output_path": "./media/extracted/abcdef...-5f9c.md",
  "bytes": 148210,
  "lines": 1842,
  "title": "Q3 Report",
  "toc": ["Introduction", "Revenue", "Outlook"],
  "preview": "# Q3 Report\n\nRevenue increased...",
  "image_count": 7,
  "truncated_images": 0,
  "warnings": [],
  "cached": false
}

• preview is a fixed-size head of the markdown (~1500 characters). For more, the agent uses the read tool against output_path:

  {"path": "./media/extracted/abcdef...-5f9c.md", "start_line": 120, "end_line": 200}
  

• cached: true means this extraction was served from disk with no re-processing. Cache keys include a hash of the document contents and a hash of the flags (ocr, include_images, metadata), so two calls with different flags don’t collide.

Errors

Errors include a short hint where a retry strategy is obvious (for example, no_text suggests enabling OCR).

Storage & retention

Extracted markdown is cached under the extracted media category at media/extracted/<contentHash>-<flagsHash>.md (plus a small .json sidecar). Defaults:

• TTL: 30 days
• Quota: 2 GB

Adjust both in the setup wizard or TUI config editor under Media Storage → Extracted Documents. The category is ephemeral — cleanup is automatic, and anything you delete will simply be regenerated on the next call.

Vision chain notes

• OCR and image descriptions use the agent model chain. If that chain has no vision-capable model, the tool degrades gracefully: images become references, OCR reports no_text, and a warning is surfaced in the response.
• Every vision call goes through normal failover + cooldown, so a single bad provider won’t break an extraction.
• The max_vision_calls cap protects against pathological documents (e.g. a 200-image PDF) running up an unbounded bill. Remaining images are reported in truncated_images; raise the cap or set it to 0 to disable.

Disable the tool

Under Tools → Document Extract in the setup wizard or TUI editor, toggle documentExtract.enabled off. The config key is tools.documentExtract.enabled (default true).