Skip to main content
Glama
sandraschi

pdf-mcp

by sandraschi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

pdf_rag

Read-only

Build and query a RAG index over PDF content to chunk documents, semantically search passages, and synthesize findings across multiple PDFs.

Instructions

Build and query a RAG index over PDF content.

Chunks, indexes, and semantically searches PDF text via LanceDB. Tables are indexed as structured chunks (section='table'). Supports query-by-example and cross-document synthesis.

Return Format

A dict with keys:

  • success: bool - whether the operation succeeded

  • message: str - human-readable summary

  • operation-specific keys:

    • chunk: {chunks, doc_id}

    • index: {chunks_indexed, doc_id}

    • search: {results: [{doc_id, chunk_id, page_num, section, source_file, text, _distance}]}

    • similar: same shape as search (seeded by a text snippet)

    • synthesize: {groups: [{doc_id, source_file, hits, snippet}], summary?}

    • list_documents: {documents: [{doc_id, chunk_count}]}

    • delete_index: {} On failure: {success: False, error, error_type}.

Examples

await pdf_rag(operation="chunk", path="book.pdf", strategy="recursive", chunk_size=1000) {"success": true, "chunks": 42, "doc_id": "a1b2c3d4e5f6", "message": "Chunked book.pdf (300 pages) into 42 chunks with recursive strategy."}

await pdf_rag(operation="search", query="quarterly revenue") {"success": true, "results": [{...}], "message": "Found 3 results for 'quarterly revenue'."}

await pdf_rag(operation="similar", text="The sky was unusually clear that night.") {"success": true, "results": [{...}], "message": "Found 2 similar passages."}

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathNoPath to the PDF file. Required for chunk, index operations.
textNoSource text snippet for similar (query-by-example) operation.
limitNoMax search results. Default 10.
queryNoSearch query for search / synthesize operations.
doc_idNoDocument ID for delete_index operation.
overlapNoChunk overlap in characters. Default 200.
strategyNoChunking strategy: recursive, fixed. Default recursive.recursive
operationYes
chunk_sizeNoTarget chunk size in characters. Default 1000.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
messageNoHuman-readable summary
successNoWhether the operation succeeded

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

C2.9/5.0
Behavior1/5

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

The annotation declares readOnlyHint=true, yet the tool's own operation list includes write/mutating operations: chunk and index create LanceDB tables and delete_index destroys a stored index. The description directly contradicts the read-only annotation, leaving the agent misinformed about 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then return format, then concrete examples with headers. Well organized, though the explicit return-format block is partly redundant given an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-operation, 9-parameter tool the operation coverage and return shapes are reasonably complete, and an output schema exists. The main gap is the unresolved read-only vs. mutating/destructive confusion introduced by the annotation.

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 89%, so the schema already documents path, text, limit, query, doc_id, overlap, strategy, and chunk_size. The description adds operational context (which operation seeds from a snippet) but little syntax or format detail beyond the schema, so the baseline 3 applies.

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

Purpose4/5

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

The opening sentence gives a specific verb+resource: 'Build and query a RAG index over PDF content.' It clearly conveys the dual build/query nature. It does not, however, differentiate itself from the many sibling PDF tools (pdf_analyze, pdf_extract) that an agent might otherwise choose.

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

Usage Guidelines2/5

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

The description enumerates operations but never states when to use pdf_rag versus the 15 sibling tools, nor any prerequisite like 'you must chunk/index before searching.' Usage must be inferred from operation names alone.

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

Deploy Server

Other Tools