Primary document retrieval tool. After orienting with get_folder_structure() (when available) — and, for queries that may involve typed attributes, pairing it with get_metadata_schema() so you know which fields metadata mode could filter on — use this for all document-related questions. The bare call returns root-level sub-folders and documents; pass folder_id to drill into a sub-folder level by level. Use sort="relevance" + query for semantic ranking. Do NOT jump to search_documents() first — keyword search and metadata mode are escalation paths, only after browse_documents(sort="relevance") + the persistence retries have failed. browse_documents does not filter by attribute — for typed-attribute queries, escalate to search_documents(mode="metadata").

Check a document's processing status and metadata. Call this before get_document_structure() or get_page_content() to confirm the document is ready (status === "completed").

Retrieve an image from a document — pass an image_path from a get_page_content() response: either an embedded image (from a content block) or a full rendered page (from the page_images array, useful when a page is scanned or its meaning depends on visual layout). Returns the image as an MCP image content block (base64 data + MIME type). Do NOT repeat the raw base64 value in your text response.

Extract a document's hierarchical outline (headers, sections, page references). REQUIRED for documents over 20 pages — call this first to locate relevant sections, then pass their page numbers to get_page_content(). Use the part parameter to iterate large outlines until pagination.has_more is false.

Orientation step: show the folder hierarchy as a tree (like tree -d). Call this before browse_documents() to plan targeted retrieval — folder names reveal content domains (e.g. "Research", "Finance") and return folder IDs you pass to browse_documents(folder_id=…). Wait for this result before issuing browse_documents() or search_documents(). For folder_id="root" (default), returns the entire folder tree; for a specific folder_id, returns that subtree only.

List declared metadata fields (names, types, descriptions) so you can build metadata_filter / sort / aggregates / group_by for search_documents(mode="metadata"), or a metadata_filter that narrows mode="query". Call it only when the question filters by a typed attribute (year, status, category, …) or asks for counts / averages / extremes / distributions — not as a routine first step; ordinary discovery goes through browse_documents(). Call it WITHOUT folder_id first: one call returns the account-level fields plus every folder that declares its own, with folder ids — no need for get_folder_structure() beforehand. Pass a folder_id only to read one folder's effective schema (it falls back to the account-level one). Reuse the result for the rest of the conversation.

Extract page content from a processed document. Use tight, targeted page ranges — never the whole document at once. For documents over 20 pages, call get_document_structure() first to pick relevant sections. Embedded image paths in the response feed into get_document_image().

Upload and process a PDF from a URL or a local file path (≤100MB). Processing typically takes 0-3 minutes depending on document size (estimate: 2 seconds per page). Returns the new document and its processing status; call get_document() to confirm it has finished before reading its content.

Permanently delete documents and all associated data. Only invoke when the user explicitly names the documents AND confirms deletion. Returns results — one entry per requested document: { doc_name, status: "deleted" | "not_found" | "failed", error? }. Inspect each entry for per-document failures. This action is irreversible.

Escalation tool — never the first discovery step. Always start with browse_documents() (after get_folder_structure() when visible). Pick a mode: • mode="query" — keyword precision when browse missed a known doc by precise term, acronym, or file-name fragment. AND match with graded OR fallback. When results carry relevance (0–1, the chance the document helps answer the query) they are ranked by it, and in a small library a term found only in a document's text still finds it; otherwise they are sorted by upload date — judge relevance yourself. • mode="metadata" — structured filter / sort / aggregates over the declared schema. Use after browse missed a typed-attribute query, OR for counts / averages / extremes browse cannot answer. Call get_metadata_schema() FIRST to confirm field names and types — guessing risks silent zero-match.