Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PageIndex MCP summarize the key findings from the quarterly report PDF I uploaded"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
If you find this repo useful, please also star our main PageIndex repo ⭐
📘 PageIndex is a vectorless, reasoning-based RAG system that represents documents as hierarchical tree structures. It enables LLMs to navigate and retrieve information through structure and reasoning, not vector similarity — much like a human would retrieve information using a book's index.
🔌 PageIndex MCP exposes this LLM-native, in-context tree index directly to LLMs via MCP, allowing platforms like Claude, Cursor, and other MCP-compatible agents or LLMs to reason over document structure and retrieve the right information — without vector databases.
Want to chat with long PDFs but hit context limit reached errors? Add your file to PageIndex to seamlessly chat with long PDFs on any agent/LLM platforms.
✨ Chat to long PDFs the human-like, reasoning-based way ✨
Support local and online PDFs
Free 1000 pages
Unlimited conversations
For more information, visit the PageIndex MCP page.
💡 Looking for a fully hosted experience? Try PageIndex App 🤖: a human-like document analyst that lets you chat with long PDFs using the same agentic, reasoning-based workflow as PageIndex MCP.
PageIndex is a vectorless, reasoning-based RAG system that generates hierarchical tree structures of documents and uses multi-step reasoning and tree search to retrieve information like a human expert would. It has the following key properties:
Higher Accuracy: Relevance beyond similarity
Better Transparency: Clear reasoning trajectory with traceable search paths
Like A Human: Retrieve information like a human expert navigates documents
No Vector DB: No extra infrastructure overhead
No Chunking: Preserve full document context and structure
No Top-K: Retrieve all relevant passages automatically
Connect PageIndex to your agent framework or AI SDK via MCP. Works with Claude Agent SDK, Vercel AI SDK, OpenAI Agents SDK, LangChain, and any MCP-compatible client. Simple API Key authentication — no OAuth flow required.
Go to PageIndex Dashboard to create an API Key
Copy the generated key
Add to your MCP configuration:
{
"mcpServers": {
"pageindex": {
"type": "http",
"url": "https://api.pageindex.ai/mcp",
"headers": {
"Authorization": "Bearer your_api_key"
}
}
}
}For more details, visit the PageIndex API Dashboard.
If you already have a PageIndex App account, you can connect your MCP client directly via OAuth.
Claude Desktop — One-Click Install:
Download the .mcpb file from Releases and double-click to install. OAuth authentication is handled automatically.
Other MCP Clients:
{
"mcpServers": {
"pageindex": {
"type": "http",
"url": "https://app.pageindex.ai/mcp"
}
}
}Local MCP Server (with local PDF upload):
If you need to upload local PDF files, you can run the local MCP server (requires Node.js ≥18.0.0):
{
"mcpServers": {
"pageindex": {
"command": "npx",
"args": ["-y", "@pageindex/mcp"]
}
}
}For more details, visit PageIndex App.
This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.
Primary document retrieval tool. After orienting with get_folder_structure() (when available), 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 — it is an escalation path, only after browse_documents(sort="relevance") has failed.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order. "time" (default) sorts by upload date (newest first); "relevance" orders documents by semantic relevance to `query`. Relevance also works inside the read-only shared folders — pass their folder_id — but at the library root it ranks only your own documents. | |
| limit | No | Number of documents to return per page (1-50, default 10) | |
| query | No | Search query for relevance ranking. Required when sort="relevance"; must be omitted when sort="time". | |
| offset | No | Zero-based pagination offset. Pass the value of `next_offset` from the previous response to fetch the next page. | |
| folder_id | No | Folder scope (default "root"). Pass a specific folder ID to scope into that folder, or "root" to reference the library root. The read-only "shared-with-me" and "following" folders live at the library root — pass one of those ids to browse them. Copy any folder_id verbatim from a browse/tree response, never construct one. Combine with `recursive` to control breadth. | |
| recursive | No | Whether to include documents from descendant folders. When false (default), returns the direct contents of folder_id along with its sub-folders — prefer this for level-by-level exploration so you retain folder hierarchy context. When true, flattens all descendant documents into one list and omits sub-folders — use only when a non-recursive browse of the target folder returned no relevant results and you need to widen the scope, or the user explicitly requests a flat listing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure_RESPONSIBILITY. It discloses meaningful behaviors: the default bare-call result, folder-by-folder drilling, relevance ranking behavior inside read-only shared folders, and the root-level ranking limitation ('at the library root it ranks only your own documents'). It does not discuss permissions or errors, but for a retrieval tool the disclosed navigation and ranking semantics are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense: first sentence establishes primacy, second explains the core browsing workflow, third covers relevance sorting, and the last gives an explicit anti-guideline. Every sentence contributes a distinct piece of guidance and the most important routing rule is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no annotations, and no output schema, the description plus parameter schemas fully cover what an agent needs to select and invoke the tool: how to start, how to drill down, when to use relevance, when to use recursive, and how to avoid prematurely escalating to search_documents. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter's meaning, defaults, and allowed values, including the 'next_offset' pagination contract)Skip. The tool description adds strategic usage context around parameters, but does not materially add semantics beyond the schema's own parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the tool as the 'Primary document retrieval tool' and explicitly distinguishes it from search_documents(), telling the agent to use browse_documents for 'all document-related questions' and treating search as an escalation path. It states a concrete behavior: 'bare call returns root-level sub-folders and documents; pass folder_id to drill into a sub-folder level by level.' This clearly separates it from siblings like get_folder_structure and search_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'After orienting with get_folder_structure()... use this for all document-related questions.' It also gives an explicit exclusion: 'Do NOT jump to search_documents() first — it is an escalation path, only after browse_documents(sort="relevance") has failed.' It further explains when to use recursive browsing and when the relevance sort is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a document's processing status and metadata. status is one of "pending", "queued", "processing", "completed", or "failed" — call this before get_document_structure() or get_page_content() to confirm the document is ready.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_name | Yes | Copy the `name` field verbatim from a browse_documents() or search_documents() response (case-sensitive, include extension). Example: "Q3 Report.pdf". If the response shows two documents with the same name, pass `folder_id` alongside to disambiguate. | |
| folder_id | No | ||
| wait_for_completion | No | If true and document is processing, automatically wait up to 3 minutes until completed. Reduces repeated tool calls. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It communicates a read-only 'check' actionainer, lists the full set of possible statuses, and clarifies that it is not the tool for retrieving structure or page content. Minor gap: it does not explicitly state that the operation has no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence: purpose first, followed by the status enumeration and contextual usage guidance. No filler words; code formatting improves readability and scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of description and schema gives the agent enough to call the tool correctly: parameters, status values, and sequencing relative to sibling tools. With no output schema, the main omission is what specific fields 'metadata' includes and how to react to 'failed', but those are secondary for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: doc_name and wait_for_completion have detailed schema descriptions, and folder_id is partially explained within doc_name's description. The tool description itself adds no parameter-level detail, so it does not compensate beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Check a document's processing status and metadata.' It also enumerates the possible status values, and distinguishes itself from siblings by positioning itself as the gate before get_document_structure or get_page_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this tool before get_document_structure() or get_page_content() to confirm the document is ready. It names the alternatives and the condition that selects this tool, leaving no ambiguity about when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | No | ||
| image_path | Yes | An image_path from a get_page_content() response, passed back exactly as returned — never constructed or modified. Two sources: an embedded image_path (or img_path) on a content block, or a full-page image_path from the page_images array (format "<doc_name>/_page_images/page-<N>.jpg"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the return format (MCP image content block with base64 + MIME) and warns not to repeat the raw base64 in text, but it does not mention absence of side effects, error behavior, or the role of folder_id. These are notable gaps but not severe for a read-style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence adds value: what the tool does, where the input comes from, what the output is, and an important agent-behavior instruction. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool, the description covers the source of the input, the two use cases, the return format, and a critical interaction caveat. The main omission is the folder_id parameter, whose purpose is left undocumented, but the required path is complete enough for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The image_path parameter is very well described in the schema, and the tool description adds useful context about when each source type is applicable. However, folder_id has an empty schema description and is never mentioned in the description, leaving half of the parameters unexplained. The critical required parameter is covered, but the optional one is not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Retrieve an image from a document.' It further clarifies that image_path comes from get_page_content() and distinguishes embedded images from rendered page images, making the tool's function and relationship to siblings clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use the tool: pass an image_path from a get_page_content() response, and even guides which image_path to choose for scanned or layout-dependent pages. It does not explicitly name alternative tools or when-not-to-use scenarios, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| part | No | Part number for pagination (1-based, default 1). For large outlines, increment until the response's `pagination.has_more` becomes false. | |
| doc_name | Yes | Copy the `name` field verbatim from a browse_documents() or search_documents() response (case-sensitive, include extension). Example: "Q3 Report.pdf". If the response shows two documents with the same name, pass `folder_id` alongside to disambiguate. | |
| folder_id | No | ||
| wait_for_completion | No | If true and document is processing, automatically wait up to 3 minutes until completed. Reduces repeated tool calls. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals the output includes headers, sections, and page references, and exposes pagination behavior through 'pagination.has_more'. It also communicates the intended call sequence and the wait_for_completion behavior, though it does not discuss error handling or processing states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, conditional usage, the follow-up action, and pagination behavior without wasted words. The most decision-relevant information is front-loaded: the extraction purpose and when it is required.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough for an agent to decide when to call this tool, what it returns at a high level, and how to paginate. It connects the tool to get_page_content and references pagination.has_more, but without an output schema it does not fully specify the outline's exact return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (75%), so the baseline is 3. The doc_name and part parameters are well described in the schema, and the description adds workflow context around part's pagination role. However, the folder_id parameter has no schema description and is not explained in the description, leaving a small coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Extract a document's hierarchical outline (headers, sections, page references).' It clearly differentiates from siblings like get_document, get_page_content, and get_folder_structure by describing the outline extraction purpose and the follow-up workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'REQUIRED for documents over 20 pages — call this first to locate relevant sections.' It also names the follow-up tool, get_page_content(), and explains the pagination loop. It lacks an explicit when-not-to-use statement for smaller documents, but the conditional guidance strongly implies the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Human-readable folder path (e.g. "Research/Papers/2024"). Alternative to folder_id — copy a `path` value from any browse_documents() or search_documents() response. When provided, folder_id is ignored. | |
| depth | No | Maximum depth to traverse (1-10, default 10). Use a smaller value for very large folder trees. | |
| folder_id | No | Subtree root (default "root" = entire library). Pass a specific folder ID to get only that subtree, or "shared-with-me"/"following" for the read-only folders at the library root. Copy any folder_id verbatim from a browse/tree response, never construct one. Ignored when `path` is provided. | |
| include_counts | No | Include file_count and children_count per folder (default true). Set false to reduce response size; the root node of the tree always carries its counts regardless of this flag. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the tool is read-only in nature (orientation), explains the tree output, and notes that the root node always carries counts. It does not explicitly state error behavior or permission requirements, but these are minor given the non-destructive nature implied and the detail provided about response composition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and front-loaded with its purpose, then moves to usage sequencing, then parameter nuances. It is slightly long but each sentence contributes operational value; nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, the description covers all essential aspects: what it returns (tree, IDs), how to invoke it canonically (before browse_documents), parameter interactions, and special cases (root subtree, read-only folders). No crucial information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description goes far beyond the schema by explaining the path/folder_id interplay (path overrides folder_id), special folder_id values ('shared-with-me'/'following'), the rule to never construct folder IDs, and when to reduce depth. This adds critical operational meaning that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('show the folder hierarchy as a tree') and frames it as an 'Orientation step' distinct from retrieval tools like browse_documents or search_documents. It clearly positions itself as the prerequisite for targeted retrieval, distinguishing it from sibling tools with a specific call pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this before browse_documents() and wait for the result before issuing browse_documents() or search_documents(). It also gives conditional guidance on path vs folder_id and on reducing depth for large trees, making the usage rules unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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().
| Name | Required | Description | Default |
|---|---|---|---|
| pages | Yes | Page specification: "5", "3,7,10", "5-10", or "1-3,7,9-12" | |
| doc_name | Yes | Copy the `name` field verbatim from a browse_documents() or search_documents() response (case-sensitive, include extension). Example: "Q3 Report.pdf". If the response shows two documents with the same name, pass `folder_id` alongside to disambiguate. | |
| folder_id | No | ||
| wait_for_completion | No | If true and document is processing, automatically wait up to 3 minutes until completed. Reduces repeated tool calls. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden, and it does so well: it discloses the processed-document prerequisite, the requirement to avoid whole-document requests, and a return-value behavior (embedded image paths feed into get_document_image()). It does not specify error behavior or the exact content format returned, but the key operational traits are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all valuable, with the most important guidance ('tight, targeted page ranges', 'never the whole document') front-loaded. There is no filler, repetition of schema, or unnecessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, no annotations, and no output schema, the description plus schema gives an agent enough to select and invoke it correctly: purpose, page-range constraints, workflow for large documents, and image-path integration are all present. Minor gaps such as exact response format and failure behavior keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so most parameters are already documented. The description reinforces the meaning of 'pages' with the targeted-range guidance, but it adds little about folder_id or wait_for_completion beyond what the schema already states. The undocumented folder_id field is not compensated for in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Extract'), a resource ('page content'), and an important qualifier ('from a processed document'). It also distinguishes itself from siblings by explicitly routing embedded image paths to get_document_image() and advising get_document_structure() for large documents, so an agent can tell it apart from get_document, get_document_structure, and get_document_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit, actionable usage direction: use tight, targeted page ranges, never the whole document, and call get_document_structure() first for documents over 20 pages. It names the recommended sibling and the condition that triggers it, leaving no ambiguity about when or how to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload and process PDF documents from URLs or local files. Supports OCR processing, hierarchical content extraction, and intelligent document analysis. Returns a unique doc_id for subsequent operations. Processing typically takes 0-3 minutes depending on document size (estimate: 2 seconds per page). Supports files up to 100MB.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to a PDF document or local file path | |
| folder_id | No | Target folder ID. Use "root" for the root folder, or omit to use the user's default folder (configured in settings). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context: typical processing time (0-3 minutes, 2 sec/page), file size limit (100MB), and that a unique doc_id is returned for subsequent operations. However, it does not disclose whether the operation is synchronous or asynchronous, error handling, or if there are any destructive side effects. The provided temporal and size details provide some transparency, but not exhaustive behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the main action and capabilities. It covers essential operational details (time, size limit, return value) without redundancy or filler. Every sentence contributes meaningful information, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description covers the key operational concerns: what the tool does, how long it takes, size limits, and the returned doc_id. It is adequate for an agent to call it correctly. However, it could be more complete by mentioning whether processing is async or if there are any error conditions, but these are minor gaps given the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (url and folder_id), and schema coverage is 100%. The description does not add any additional parameter semantics beyond what's in the schema, such as format constraints, default behaviors, or examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool uploads and processes PDF documents, with specific capabilities like OCR and extraction. It uses a specific verb ('upload and process') and resource ('PDF documents'), which distinguishes it from sibling tools like remove_document or search_documents. However, it does not explicitly name an alternative when another tool should be used, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It only states what it does, not when it is appropriate or inappropriate, nor does it mention any prerequisites or exclusions. The purpose is implied (use this to start processing), but there is no direct 'when to use' or 'when not to use' guidance relative to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_names | Yes | Array of document names to delete. Each name must be copied verbatim from the `name` field of a browse_documents() or search_documents() response (case-sensitive, include extension). Example: ["Q3 Report.pdf", "draft.pdf"]. Max 10 per call. | |
| folder_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that deletion is permanent and irreversible, and it even documents the exact return format with per-document statuses (deleted/not_found/failed) and error field, instructing to inspect each entry. This goes beyond a basic 'deletes documents' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, using only three sentences. It front-loads the critical action and condition, then provides return details. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool, the description covers the essential aspects: action, when to use, irreversibility, and expected result structure. The only gap is the `folder_id` parameter, which is not explained. Since it is optional and the description already supplies thorough return semantics, the missing param explanation is a minor shortfall in an otherwise complete definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides detailed semantics for `doc_names` (verbatim copying, case-sensitivity, extension, example, max 10). The description adds nothing about parameters; it focuses on return values. The `folder_id` parameter has no description in the schema and is not mentioned in the tool description, so its semantics remain unclear. With 50% coverage, the description doesn't compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: permanently deleting documents and all associated data. It uses specific language ('Permanently delete'), names the resource (documents), and distinguishes from siblings (browse, search, process, get) by highlighting the destructive nature and irreversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to invoke: only when the user explicitly names the documents AND confirms deletion. It also notes the action is irreversible, which is a critical usage condition. No alternative tool is needed since no other sibling deletes documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ESCALATION tool — never the first step. Use only after browse_documents(sort="relevance", query=...) missed a document you strongly believe exists by precise term, acronym, or file-name fragment. Query must be keywords only — see the query schema describe. Each result has a score (6-10, higher is more relevant). On result: single best match → read it; several equally good → ask user; none → fall back to browse_documents(sort="relevance").
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of documents to return (1-50, default 10) | |
| query | Yes | Keyword query. Pass keyword(s) only — NOT a natural-language sentence. Multiple keywords are AND-matched: every token must appear in the file name or description. Examples: "machine learning safety" ✓; "documents about machine learning safety" ✗ (stop words "documents"/"about" will block matches). | |
| folder_id | No | Folder scope (default "root"). Pass a specific folder ID to scope into that folder, or "root" to reference the library root. Combine with `recursive` to control breadth. Mirrors browse_documents — copy any folder_id from a browse/tree response verbatim, never construct one. The default root search ALREADY covers the read-only "shared-with-me" and "following" folders; pass one of those ids (or one of their sub-folder ids) only to narrow the search to shared content. | |
| recursive | No | Whether to include documents from descendant folders. When true (default), searches the entire subtree of folder_id — for "root" that means the whole library, including the read-only "shared-with-me" and "following" folders. Set false to restrict to the direct contents of folder_id: root-level documents for "root", directly-shared documents for the read-only folders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and it delivers: keyword-only constraint, a score range of 6-10, and a prescribed action for single, multiple, and no matches. It stops short of describing error behavior or full return shape, but the core runtime behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the most important operational fact (escalation tool), and every subsequent sentence adds either a constraint, a result expectation, or an action rule. Despite being dense, it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations or output schema, the description covers the selection decision, the query format, the result scoring, and the follow-up protocol. The only gap is a fully specified return shape and error/edge-case behavior, but the schema covers parameters and the description covers operational flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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's 'keywords only' instruction restates the query schema and adds the escalation context, but does not materially enrich the parameter meanings beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line frames the tool as the escalation search path for finding a document that browse_documents missed, and the query/result description makes the verb and resource explicit. It is sharply differentiated from browse_documents by naming that sibling directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it ('only after browse_documents(sort="relevance", query=...) missed a document'), when not to use it ('never the first step'), and the fallback if no result is found. This leaves no ambiguity about placement in the search workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.8.2browse_documentsget_documentget_document_imageget_document_structureget_folder_structureget_page_contentprocess_documentremove_documentsearch_documentsScored across 9 tools
Each tool has a distinct role in the document lifecycle, and overlapping discovery tools (browse vs. search) are explicitly differentiated. However, get_folder_structure vs. get_document_structure could momentarily confuse an agent despite their different targets.
All tools follow a consistent snake_case verb_noun pattern, with get_* used uniformly for retrieval-oriented operations and clear action verbs like process, remove, browse, and search. There are no mixed conventions or vague generic names.
Nine tools is well within the ideal range and each tool earns its place, covering ingestion, deletion, navigation, search, status checking, structure extraction, page content, and image retrieval without redundancy.
The tool surface covers the full document workflow: add/remove documents, browse/search the corpus, check processing status, navigate structure, extract page content, and retrieve images. There are no obvious dead ends or missing operations for the stated domain.
Parse, extract, split, and ask over digital PDFs (text layer, no OCR) from Cursor and Claude.
High-fidelity PDF to structured Markdown conversion and document field extraction.
Extract PDFs to Markdown, RAG chunks and cited tables; publish tracked Doc Links with read stats.
Ingest, manage, and retrieve documents for RAG-powered AI applications