Skip to main content
Glama
gabrielmrojas

PDF Processor Server

by gabrielmrojas
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

FastMCP PDF Processing Server

An MCP server built with FastMCP (STDIO transport) offering PDF utilities: text extraction, metadata, merge/split/rotate, and PDF↔image conversion.

SPANISH VERSION [README.es.md]

Quick Start (Windows PowerShell)

python -m venv .venv
\.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
python -m fastmcp_pdf_server

If installed as a package, you may also run:

fastmcp-pdf-server

Related MCP server: PDF Reader MCP Server

Quick Start (Linux/macOS)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m fastmcp_pdf_server

MCP Integration

  • Transport: STDIO. Do not print to stdout/stderr; logs go to file.

  • Server name/version: from config (server_name, server_version).

  • Tools are registered using @app.tool() and return structured outputs with a meta block containing operation_id and execution_ms.

Claude Desktop config example

Add to claude_desktop_config.json (Update with your own File System Path):

{
  "mcpServers": {
     "pdf-processor-server": {
      "command": "D:\\Github Projects\\mcp_pdf_server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "fastmcp_pdf_server"
      ],
      "env": {
        "MAX_FILE_SIZE_MB": "50",
        "TEMP_DIR": "D:\\Github Projects\\mcp_pdf_server\\temp_files",
        "LOG_LEVEL": "DEBUG",
        "LOG_FILE_PATH": "D:\\Github Projects\\mcp_pdf_server\\logs\\fastmcp_pdf_server.log",
        "SERVER_NAME": "pdf-processor-server",
        "SERVER_VERSION": "1.0.0",
        "PATH": "%PATH%;C:\\poppler-25.07.0\\Library\\bin"
      }
    }
}

Note: If you update dependencies (e.g., we added requests for URL uploads), reinstall with:

pip install -r requirements.txt

Claude Desktop config example (Linux)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-processor-server": {
      "command": "python3",
      "args": [
        "-m",
        "fastmcp_pdf_server"
      ],
      "env": {
        "MAX_FILE_SIZE_MB": "50",
        "TEMP_DIR": "/home/you/dev/mcp_pdf_server/temp_files",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Claude Desktop config example (macOS)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-processor-server": {
      "command": "python3",
      "args": [
        "-m",
        "fastmcp_pdf_server"
      ],
      "env": {
        "MAX_FILE_SIZE_MB": "50",
        "TEMP_DIR": "/Users/you/dev/mcp_pdf_server/temp_files",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Programmatic usage (Python)

import asyncio
from fastmcp import Client

async def main():
    client = Client(command="python", args=["-m", "fastmcp_pdf_server"])
    await client.start()
    try:
        info = await client.call_tool("server_info")
        print(info)
    finally:
        await client.close()

asyncio.run(main())

Exposed Tools (API)

All tools return structured data; many responses include meta.operation_id and meta.execution_ms. Some tools return lists (arrays). These are marked with FastMCP's x-fastmcp-wrap-result, so clients receive { "result": [...] } at the RPC layer.

MCP Tools Reference

Each tool lists: purpose, inputs, outputs, behavior, examples, and notes about errors and usage.

Utilities / Server

  • server_info()

    • Purpose: Return basic server info and configuration snapshot (non-secret).

    • Inputs: None

    • Returns: dict with keys:

      • name (str): server name from settings

      • version (str): server version from settings

      • max_file_size_mb (int): maximum configured file size in megabytes

      • temp_dir (str): absolute path to temporary files directory

      • log_file (str): absolute path to the log file

      • meta (dict): operation metadata: operation_id (hex), execution_ms (int)

    • Errors: none expected; if configuration missing, underlying access may raise exceptions.

    • Example:

      • Call: { "name": "server_info" }

      • Response: { "name": "mcp-pdf", "version": "1.0.0", "meta": { ... } }

  • list_temp_resources(content_type: Optional[str] = None, max_items: Optional[int] = 100) -> list[dict]

    • Purpose: List files currently in the server temp directory with optional filtering by content type.

    • Inputs:

      • content_type (optional str): MIME filter; supported examples: application/pdf, image/png, image/jpeg.

      • max_items (optional int): maximum number of entries to return (default 100). If set to null or 0, defaults to 100.

    • Returns: list of resource dicts (each):

      • path (str): absolute path to the temp file

      • size (int): size in bytes

      • created (str): creation timestamp (ISO or file-manager-specific format)

      • content_type (str): MIME type of resource

      • filename (str): filename only

      • extension (str): lowercased file extension (e.g. .pdf)

      • directory (str): parent directory of the file

    • Behavior: Cleans up expired temp files before listing. Result list is sliced to max_items.

    • Errors: Raises ValueError if internal listing fails.

    • Example call:

      • { "name": "list_temp_resources", "arguments": { "content_type": "application/pdf" } }

  • get_pdf_info(file_path: str) -> dict

    • Purpose: Read a PDF headers and basic info without extracting pages/text.

    • Inputs:

      • file_path (str): path to an existing file on disk (absolute or relative). Must be accessible to the server.

    • Returns: dict:

      • pages (int): number of pages

      • size (int): file size in bytes

      • version (str|None): PDF header/version info (if available)

      • encrypted (bool): whether the PDF is encrypted

      • meta (dict): operation_id, execution_ms

    • Errors:

      • Raises ValueError if file not found.

      • May raise other errors if the file is not a PDF or is corrupted.

  • get_resource_base64(file_path: str) -> dict

    • Purpose: Return base64-encoded contents of a file inside the server temp directory.

    • Inputs:

      • file_path (str): path; must be inside the configured temp directory. The function enforces this.

    • Returns: dict:

      • path (str): resolved path inside temp

      • base64 (str): Base64-encoded content of the file

      • meta (dict): operation metadata

    • Errors:

      • Raises ValueError if the path is outside temp or file missing.

    • Notes: Use this to fetch content for download via MCP where direct file transfers aren't available.

Uploads

  • upload_file(file: Any, filename: Optional[str] = None) -> dict

    • Purpose: Persist an uploaded file into the server temp directory.

    • Inputs:

      • file (Any): Accepts:

        • a full path string to a local file

        • a short filename that refers to a file already stored in temp

        • bytes or file-like object

        • dicts containing base64 and filename (will be saved to temp)

      • filename (Optional[str]): optional filename hint used when saving raw bytes.

    • Returns: dict:

      • path (str): absolute path to the saved file

      • filename (str): saved filename

      • directory (str): directory containing the file

      • meta (dict): operation metadata

    • Errors:

      • Raises ValueError with a descriptive message on failure (network, decoding, IO).

    • Example:

      • To upload base64: call upload_file with file = { "base64": "<...>", "filename": "my.pdf" }.

  • upload_file_base64(base64: str, filename: str) -> dict

    • Purpose: Upload raw Base64 content and persist to temp storage.

    • Inputs:

      • base64 (str): Base64 string

      • filename (str): filename to use when saving

    • Returns: dict:

      • path, filename, directory, size (int), meta

    • Errors: Raises ValueError on decoding or write errors.

  • upload_file_url(url: str, filename: Optional[str] = None) -> dict

    • Purpose: Download a remote file (HTTP/HTTPS) and save to temp storage.

    • Inputs:

      • url (str): direct URL to file

      • filename (Optional[str]): optional override filename

    • Returns: dict with path, filename, directory, meta.

    • Notes: Requires requests package to be available in the environment.

Text Extraction

  • extract_text(file: Any, encoding: Optional[str] = "utf-8") -> dict

    • Purpose: Extract all text from a PDF and return summary metrics.

    • Inputs:

      • file (Any): same resolver rules as upload_file (path, temp filename, bytes, base64 dict).

      • encoding (str|None): encoding used when returning text (default utf-8).

    • Returns: dict:

      • text (str): full extracted text

      • page_count (int): number of pages processed

      • char_count (int): number of characters in text

      • meta (dict): includes resolved_path pointing to saved temp file

    • Errors:

      • Raises ValueError with helpful hint explaining how to provide the file if extraction fails.

    • Example usage:

      • Upload a file with upload_file, then call extract_text with the returned path.

  • extract_text_by_page(file: Any, pages: Optional[List[int]] = None, page_range: Optional[str] = None, encoding: Optional[str] = "utf-8") -> list[dict]

    • Purpose: Extract text from specific pages or a page range.

    • Inputs:

      • file (Any): resolver rules as above

      • pages (Optional[List[int]]): list of 1-based page indices to extract (e.g., [1,3,5]).

      • page_range (Optional[str]): range expression like "1-3,5" (parser in utils.parsers will be used).

      • encoding (Optional[str]): text encoding

    • Returns: list of page result dicts; each dict typically contains:

      • page_number (int)

      • text (str)

      • char_count (int)

    • Behavior: If both pages and page_range are provided, pages takes precedence. The tool returns a list directly (framework wraps list results).

    • Errors: Raises ValueError on invalid pages or extraction failures.

  • extract_metadata(file: Any) -> dict

    • Purpose: Extract detailed PDF metadata (author, title, producer, creation/mod dates, custom metadata, etc.).

    • Inputs: file same as above.

    • Returns: dict containing metadata keys found in the PDF plus meta operation info.

Conversion

  • pdf_to_images(file_path: str, output_dir: str, format: str = "png", dpi: int = 150, pages: Optional[List[int]] = None) -> list[dict]

    • Purpose: Convert one or more PDF pages to image files.

    • Inputs:

      • file_path (str): path to the PDF on disk (absolute or temp path).

      • output_dir (str): directory where generated images will be written.

      • format (str): image format, e.g., png, jpeg.

      • dpi (int): resolution for conversion (default 150).

      • pages (Optional[List[int]]): list of 1-based pages to render; None for all pages.

    • Returns: list of dicts for each generated image:

      • path (str), page_number (int), size (int), format (str)

    • Notes: Implementation uses pdf2image and PIL; ensure dependencies and poppler are installed on the host.

  • images_to_pdf(image_paths: List[str], output_path: str, page_size: str = "A4", orientation: str = "portrait") -> dict

    • Purpose: Create a PDF document from multiple images.

    • Inputs:

      • image_paths (List[str]): list of image file paths in order

      • output_path (str): path for the generated PDF

      • page_size (str): e.g., A4, Letter (processor maps to physical sizes)

      • orientation (str): portrait or landscape

    • Returns: dict with success info and meta including operation timing.

PDF Manipulation

  • merge_pdfs(input_files: List[str], output_path: str) -> dict

    • Purpose: Merge multiple PDF files into a single PDF.

    • Inputs:

      • input_files (List[str]): file paths

      • output_path (str): destination path

    • Returns: dict with details (e.g., path) and meta.

  • split_pdf(file_path: str, split_ranges: List[Dict[str, Any]]) -> list[dict]

    • Purpose: Split a PDF into multiple files by page ranges.

    • Inputs:

      • file_path (str): source PDF

      • split_ranges (List[Dict]): each dict should describe start and end pages and optional filename.

    • Returns: list of generated files info dicts.

  • rotate_pages(file_path: str, rotations: List[Dict[str, int]], output_path: str) -> dict

    • Purpose: Rotate specific pages in a PDF and write to output_path.

    • Inputs:

      • file_path (str): source PDF

      • rotations (List[Dict]): each dict should include page (1-based) and degrees (e.g., 90, 180, 270).

      • output_path (str): target PDF path

    • Returns: dict with path and meta.

Notes:

  • All tools log an operation_id and execution time in ms in the returned meta object.

  • Tools that return lists set x-fastmcp-wrap-result=true for the framework so they are returned as bare lists.

  • Tools will raise ValueError for user-facing errors; internal exceptions are logged.

  • For file inputs, prefer uploading first via upload_file to ensure files are in the server temp directory.

  • page_range syntax uses utils.parsers.parse_page_range: e.g., "1-3,5,7-9".

  • If both pages and page_range are passed, pages takes precedence.

  • Image conversion requires Poppler (see below).

Example JSON: extract_text (simple)

  • Request arguments:

{
  "file": "C:/path/to/input.pdf",
  "encoding": "utf-8"
}

  • Response shape:

{
  "text": "... full extracted text ...",
  "page_count": 3,
  "char_count": 1234,
  "meta": { "operation_id": "<hex>", "execution_ms": 42 }
}

Uploading files (Claude Desktop and clients)

Claude may not automatically send binary file contents. Use one of these upload tools to persist a file to the server temp directory, then reference it by short filename in subsequent calls.

  1. Upload a file (generic)

  • Tool: upload_file

  • Request:

{
  "name": "upload_file",
  "arguments": {
    "file": { "base64": "<BASE64_DATA>", "filename": "document.pdf" }
  }
}

  • Response contains filename and absolute path under the server temp_dir.

  1. Upload a file as base64 (explicit schema)

  • Tool: upload_file_base64

  • Request:

{
  "name": "upload_file_base64",
  "arguments": { "base64": "<BASE64_DATA>", "filename": "document.pdf" }
}

  1. Upload a file from URL (explicit schema)

  • Tool: upload_file_url

  • Request:

{
  "name": "upload_file_url",
  "arguments": { "url": "https://example.com/document.pdf", "filename": "document.pdf" }
}

  1. Extract text using the saved short filename

  • Request:

{
  "name": "extract_text",
  "arguments": { "file": "document.pdf" }
}

Alternative: provide a URL to upload_file (requires requests installed):

{
  "name": "upload_file",
  "arguments": {
    "file": { "url": "https://example.com/document.pdf", "filename": "document.pdf" }
  }
}

Manual option: run server_info to get temp_dir, copy your file into that directory, then call tools with the short filename.

Example JSON: merge_pdfs

  • Request arguments:

{
  "input_files": [
    "C:/path/a.pdf",
    "C:/path/b.pdf"
  ],
  "output_path": "C:/path/merged.pdf"
}

  • Response shape:

{
  "output_path": "C:/path/merged.pdf",
  "page_count": 10,
  "size": 456789,
  "meta": { "operation_id": "<hex>", "execution_ms": 87 }
}

Configuration

Configuration is loaded via pydantic-settings from .env and environment variables.

Env vars (case-insensitive):

  • MAX_FILE_SIZE_MB (int, default 50): Max file size for inputs.

  • LOG_LEVEL (str, default INFO): Logging level.

  • LOG_FILE_PATH (str, default logs/pdf-processor-server.log): Log file path.

  • TEMP_DIR (str, default temp_files): Working temp storage directory.

  • SERVER_NAME (str, default pdf-processor-server): Server name.

  • SERVER_VERSION (str, default 1.0.0): Server version.

Path helpers:

  • TEMP_DIR resolves to absolute settings.temp_path.

  • LOG_FILE_PATH resolves to absolute settings.log_path.

Storage & Security

  • Temp files are stored under TEMP_DIR and cleaned up automatically after 24h of inactivity.

  • ensure_within_temp(path) prevents reading files outside TEMP_DIR for base64 retrieval.

  • Validators enforce allowed extensions and size limits for PDFs and images.

Logging & Telemetry

  • Rotating logs at LOG_FILE_PATH (10MB x 5). No stdout/stderr prints.

  • Each tool returns meta.operation_id and meta.execution_ms for traceability.

  • Server banner and lifecycle logs are emitted by FastMCP at startup/shutdown.

Windows: Poppler for pdf2image

pdf2image requires Poppler binaries.

Linux: Poppler for pdf2image

pdf2image requires Poppler binaries. Install via your package manager:

  • Debian/Ubuntu: sudo apt update && sudo apt install -y poppler-utils

  • Fedora: sudo dnf install -y poppler-utils

  • Arch: sudo pacman -S --noconfirm poppler

  • Verify: pdftoppm -v prints a version.

macOS: Poppler for pdf2image

Install Poppler with Homebrew:

brew install poppler

If Homebrew is in /opt/homebrew/bin (Apple Silicon), ensure your shell PATH includes it. Verify: pdftoppm -v.

Developer Guide

Project layout

  • src/fastmcp_pdf_server/

    • main.py: Builds FastMCP app, registers tools, runs via STDIO.

    • config.py: Pydantic settings for env and paths.

    • utils/: Logger, validators, parsers.

    • services/: PDF and image operations, file manager.

    • tools/: Thin async wrappers exposing services as MCP tools.

Install & Run

python -m venv .venv
\.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
python -m fastmcp_pdf_server

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m fastmcp_pdf_server

Tests

pytest -q

Conversion tests are skipped if Poppler (pdftoppm) is not found.

Troubleshooting

  • Startup hangs after banner: normal for STDIO mode (waiting for an MCP client).

  • pdf2image errors: ensure Poppler on PATH; retry shell after updating PATH.

  • ValueError: File not found or Invalid file extension: check inputs and validators.

  • Large files slow/timeout: reduce dpi, use page-range, or increase resources.

Performance Notes

  • Max file size is enforced; adjust MAX_FILE_SIZE_MB if needed.

  • Prefer page-scoped ops for large PDFs.

  • Lower dpi for faster PDF→image conversions.

Optional HTTP Mode (advanced)

FastMCP supports a streamable HTTP transport. This server defaults to STDIO. For experimentation, you can run an HTTP endpoint:

# run_http.py
import asyncio
from fastmcp_pdf_server.main import build_app

async def main():
  app = build_app()
  await app.run_http_async(host="127.0.0.1", port=8000, path="mcp")

asyncio.run(main())

Happy Coding!

Available Tools

15 tools
extract_metadataC

Extract comprehensive PDF metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. 'Extract' implies a read-only operation, but the description does not specify what metadata fields are returned, whether the file parameter accepts a path or base64, or any side effects. This is minimal and vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

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

The description is short (one sentence), but it is under-specified rather than concisely effective. It lacks critical information that should accompany a one-sentence description, such as output format or parameter handling. Similar to the 'Process' example, this is over-simplification without substance.

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

Completeness2/5

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

Despite the tool being simple (1 parameter), the description does not provide enough context about what 'comprehensive metadata' includes or how the file input is supplied. While an output schema exists, the absence of any parameter description and annotations leaves the tool incomplete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the only parameter 'file' has no type or description in the input schema. The description 'PDF metadata' does not explain how the file should be provided (e.g., local path, URL, base64), nor does it add any parameter-level semantics. This is a critical gap.

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 description 'Extract comprehensive PDF metadata' clearly states the action (extract) and resource (PDF metadata), and uses 'comprehensive' to suggest thoroughness. However, it does not explicitly distinguish itself from the sibling tool 'get_pdf_info', which likely serves a similar purpose, 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.

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like get_pdf_info or extract_text. The description does not mention prerequisites, target users, or scenarios, leaving the agent to infer usage solely from the name.

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

extract_textA

Extract all text from a PDF.

Accepts:

  • Full path string

  • Short filename previously written to temp storage

  • Bytes / file-like / dict with base64 (will be saved to temp)

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYes
encodingNoutf-8

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses a meaningful behavioral trait: bytes/file-like/dict inputs will be saved to temp storage. However, it does not mention output format, potential errors, or any side effects beyond the temp save. This is partial transparency but not comprehensive.

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 highly efficient: a single topic sentence followed by a concise bulleted list of accepted inputs. There is zero fluff, and the most important information is front-loaded. Every word earns its place.

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?

An output schema exists, so return values are covered. The description explains the core purpose and input handling, which is the main complexity here. It lacks detail on encoding and edge cases (e.g., invalid PDFs), but for a straightforward extraction tool with structured output schema, it is sufficiently complete.

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?

Schema coverage is 0%, but the description compensates well for the required 'file' parameter by detailing three accepted forms (full path, short filename, bytes/file-like/dict with base64). However, it provides no explanation of the optional 'encoding' parameter, which remains undocumented. Significant but incomplete compensation.

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 clearly states the tool's function ('Extract all text from a PDF') with a specific verb and resource. 'All text' distinguishes it from sibling extract_text_by_page, and the list of accepted input forms adds useful context. This fully clarifies what the tool does.

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

Usage Guidelines3/5

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

The description implies usage for full-document text extraction via the phrase 'all text', but it does not explicitly mention alternatives or exclusions. With siblings like extract_text_by_page and extract_metadata, the description would benefit from saying when to use this tool instead, but the core context is present.

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

extract_text_by_pageB

Extract text from specific pages or page ranges.

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYes
pagesNo
encodingNoutf-8
page_rangeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It only states what the tool does, without disclosing return format, error behavior, page numbering, or encoding defaults. It does not contradict anything, but provides little 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.

Conciseness5/5

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

The description is a single, focused sentence that immediately conveys the core purpose. It is front-loaded and contains no filler, making it appropriately concise.

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

Completeness2/5

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

Given 4 parameters, no annotations, and a minimal description, the tool is under-specified. Users are left guessing how to format 'page_range', what 'encoding' does, and how the result is returned, so the description is not complete enough for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate for parameter meaning. It only mentions pages/page ranges, giving minimal context for two of the four parameters, while 'encoding' and the exact format of 'page_range' are left unexplained.

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 clearly states the tool extracts text from specific pages or page ranges, using a specific verb and resource. The mention of 'specific pages or page ranges' distinguishes it from the sibling tool 'extract_text', which likely handles whole documents.

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?

There is no guidance on when to use this tool versus alternatives like 'extract_text'. The description is purely functional, with no mention of scenarios where this is preferred or any exclusions.

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

get_pdf_infoB

Get comprehensive PDF information without processing content.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description must fully convey behavior. It discloses the key trait 'without processing content', which implies a read-only, fast operation. However, it omits other behavioral details such as error handling, permission requirements, or performance characteristics, making this only partially transparent.

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 a single, well-structured sentence that front-loads the primary purpose and includes only essential information. Every word contributes value, making it perfectly concise.

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?

Given the tool's simplicity (one parameter) and the presence of an output schema, the description provides sufficient context: it states what the tool does and its key non-behavior. It lacks only a brief mention of common use cases or cost implications, but overall it is complete.

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?

The schema has 0% description coverage for the single parameter file_path. The tool description does not elaborate on this parameter, but the name is self-explanatory and unambiguous, so the lack of additional explanation is acceptable.

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 description clearly states the tool gets 'comprehensive PDF information' and specifically notes it does so 'without processing content', which distinguishes it from content-focused siblings like extract_text. However, it does not explicitly differentiate from the similar extract_metadata tool, 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.

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. While 'without processing content' implies a use case for quick information retrieval, it does not name alternatives or specify conditions under which this tool is preferred.

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

get_resource_base64B

Return base64 for a file within the temp directory only.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

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 indicates a read operation ('Return base64') and a scope restriction ('temp directory only'), but it does not describe path resolution, error behavior for missing files, or the exact base64 output format. These omissions leave significant behavioral aspects undisclosed.

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 a single clear sentence with no wasted words. It conveys the action, resource, and scope efficiently, making it easy to parse quickly.

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 simple tool with one parameter and an output schema (as signaled), the description covers the essential operation and scope. The missing details about path format and error handling are relatively minor for a getter tool, though they would improve completeness. Overall, it is adequate for basic invocation but not exhaustive.

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?

The schema has no description for the file_path parameter (0% coverage), so the description must compensate. It adds semantic value by stating that the parameter represents a file within the temp directory, which is a meaningful constraint beyond the bare string type. However, it does not clarify whether the path should be relative or absolute, or whether subdirectories are allowed, leaving some ambiguity.

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 clearly states the tool's function: returning base64 for a file, with an explicit scope restriction to the temp directory. This distinguishes it from sibling tools like upload_file_base64 (which uploads) and list_temp_resources (which lists). The verb 'Return' and resource 'base64' are specific and non-tautological.

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?

There is no guidance on when to use this tool versus alternatives. The temp-directory-only constraint provides context but does not explain when to prefer this over other resource-access tools, nor does it mention exclusions or prerequisites. Essentially, it lacks any when-to-use or when-not-to-use instructions.

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

images_to_pdfC

Create PDF from multiple image files.

ParametersJSON Schema
NameRequiredDescriptionDefault
page_sizeNoA4
image_pathsYes
orientationNoportrait
output_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic creation action without mentioning whether output_path is overwritten, required permissions, file format constraints, or any side effects. This is insufficient for a tool that writes to disk, similar to the 'update_drive' example that received a 2.

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?

The description is a single concise sentence with no wasted words. It efficiently states the core purpose, though it skips other needed details. This is appropriately compact for the amount of information it provides, though not as informative as it could be.

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

Completeness2/5

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

Despite the tool having 4 parameters and an output schema, the description covers only the basic conversion concept. It omits crucial context such as accepted image formats, default page_size and orientation, behavior when output_path exists, and any return values. The output schema exists but the description still lacks sufficient detail for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description adds no information about any of the four parameters (image_paths, output_path, page_size, orientation). It fails to explain valid values, defaults, or relationships, leaving the agent to rely solely on parameter names, which is not enough given the 0% coverage.

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 description 'Create PDF from multiple image files' clearly identifies the tool's function with a specific verb ('Create') and resource ('PDF'), plus the input source ('multiple image files'). This distinguishes it from siblings like merge_pdfs (combines existing PDFs) and pdf_to_images (converts PDFs to images), though it does not explicitly name alternatives.

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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or conditions such as 'use this when you have image files rather than PDFs'. The usage is only implied by the phrase 'from multiple image files', with no explicit context or alternative comparisons.

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

list_temp_resourcesA

List available temporary files with optional filtering.

  • content_type: filter by 'application/pdf', 'image/png', 'image/jpeg'

  • max_items: limit the number of returned entries

ParametersJSON Schema
NameRequiredDescriptionDefault
max_itemsNo
content_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior3/5

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 correctly communicates the read-only listing nature and supported filters, but it does not explain the scope of 'available' (e.g., session-persistence, expiry) or any ordering/edge-case behavior. This is adequate but not rich.

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 extremely concise, with one introductory sentence and two bullet points, each carrying necessary information. No filler or redundancy exists; it is well-structured for quick parsing.

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?

The tool is simple, has an output schema, and the description covers its core purpose plus both parameters. Minor ambiguities around what 'available temporary files' means remain, but the overall context is sufficient for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly explains both parameters, including allowed MIME types for content_type and the limiting effect of max_items. Since the input schema has no descriptions, this fully compensates for the schema's lack of detail and adds meaningful guidance.

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 clearly states the tool lists available temporary files, using a specific verb and resource. It distinguishes itself from sibling tools like get_resource_base64 or get_pdf_info by focusing on enumeration rather than retrieval or processing.

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

Usage Guidelines4/5

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

The description clearly indicates the tool is for listing temporary files with optional filters, providing obvious context for when to use it. However, it does not explicitly mention alternatives or situations where another tool would be preferred, so it stops short of a 5.

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

merge_pdfsB

Merge multiple PDF files into one document.

ParametersJSON Schema
NameRequiredDescriptionDefault
input_filesYes
output_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It states the merge action but doesn't disclose whether it creates a new file, modifies inputs, requires permissions, or handles bookmarks/metadata. This is a significant gap for a mutation tool.

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?

The description is a single sentence that is efficient and front-loaded. It is appropriately concise for the operation, though it could add more context while remaining focused.

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

Completeness2/5

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

The tool has two required parameters and no annotations; the description fails to explain parameter semantics, file path expectations, or any limitations. While an output schema exists, the description still lacks sufficient context about how to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has two parameters with zero schema description coverage. The description does not explain that input_files expects an array of file paths or that output_path is the destination. It only says 'multiple PDF files', which is vague and does not compensate for the lack of schema descriptions.

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 clearly states the verb 'merge' and the resource 'PDF files', with the output being 'one document'. This directly distinguishes it from sibling tools like split_pdf and rotate_pages.

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

Usage Guidelines3/5

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

The description implies usage when combining multiple PDFs into a single document, but does not explicitly mention alternatives or when not to use it. No exclusionary guidance is provided, so the usage context is only implied.

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

pdf_to_imagesC

Convert PDF pages to image files.

ParametersJSON Schema
NameRequiredDescriptionDefault
dpiNo
pagesNo
formatNopng
file_pathYes
output_dirYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

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 only states the conversion action but fails to mention side effects such as whether output files are overwritten, whether output_dir is created if missing, or how pages are selected and named.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

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

The description is a single sentence, which is concise, but it is under-specified rather than effectively concise. It provides only the core function without adding any useful detail, making it insufficient for a tool with five parameters.

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

Completeness2/5

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

The tool has 5 parameters and no annotations, and although an output schema exists, the description lacks critical context about page selection, format options, and output behavior. It is not complete enough for a tool of this complexity, even considering the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description gives no explanation of the parameters (dpi, pages, format, file_path, output_dir). Schema description coverage is 0%, and the description does not compensate, leaving the agent without any semantic understanding of these options beyond their names and defaults.

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 description clearly states the tool converts PDF pages to image files, using a specific verb and resource. It is distinguishable from sibling tools like extract_text or images_to_pdf, though it lacks detail on scope (e.g., all pages vs selected pages).

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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or situations where another sibling tool (e.g., images_to_pdf for reverse conversion) would be more appropriate.

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

rotate_pagesC

Rotate specific pages in a PDF.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes
rotationsYes
output_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description carries the full burden. It does not disclose whether the original file is modified or a new file is created, despite an output_path parameter. It also doesn't mention permissions, reversibility, or side effects. The single sentence provides no behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The description is a single concise sentence with no wasted words. However, given the tool's parameter complexity, it is under-specified rather than efficiently concise. It would benefit from brief parameter context without being verbose.

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

Completeness2/5

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

The description is minimal, with no output behavior, side effects, or parameter details. The output schema is undefined, and the tool's complexity in the rotations parameter is unaddressed. Overall, it lacks the context needed for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain parameter meanings. The 'rotations' parameter is an array of objects with integer values, but the description doesn't clarify the expected structure (e.g., page-to-angle mapping). The parameter names are partly self-explanatory, but the complex rotations structure is left ambiguous.

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 clearly states the tool's function: 'Rotate specific pages in a PDF.' It uses a specific verb (rotate) and resource (pages in a PDF), and distinguishes from sibling tools like split_pdf or merge_pdfs.

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?

No guidance is provided on when to use this tool vs alternatives. There is no mention of use cases, exclusions, or prerequisites. The sibling tools include other PDF manipulation functions, but the description doesn't help the agent choose.

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

server_infoA

Return basic server info and configuration snapshot (non-secret).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations provided, the description carries the burden. It states 'non-secret' and uses 'Return' which implies a read-only, safe operation. This adds value beyond the tool name and schema, though it doesn't detail performance or side effects. Given the zero-parameter nature, this transparency is adequate.

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 a single, well-structured sentence that fully defines the tool's purpose. It avoids fluff and includes the important caveat about secrets. Every word earns its place.

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 presence of an output schema and the simple zero-parameter nature of the tool, the description provides sufficient context. It names the core output ('server info and configuration snapshot') and the non-secret guarantee. No additional detail is necessary for an AI agent to use this tool correctly.

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?

The tool has zero parameters, so per guidelines the baseline is 4. The description correctly implies the output focuses on server info/configuration, providing meaningful context even without parameters. No additional parameter explanation is needed.

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 uses a specific verb ('Return') and clearly identifies the resource ('server info and configuration snapshot'). It explicitly notes the non-secret nature, distinguishing it from potential sensitive operations. Among sibling tools that are all PDF-related, this stands out as the unique server info tool.

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

Usage Guidelines4/5

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

The description implies usage: when you need server info or configuration snapshot, use this tool. Since all sibling tools are PDF-specific, there is no ambiguity or competing alternative, providing clear context without explicit exclusions.

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

split_pdfB

Split PDF into separate files by page ranges.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes
split_rangesYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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

There are no annotations, so the description must carry the full burden of behavioral disclosure. It only says 'split PDF into separate files', implying output as files but gives no details about whether the original is modified, where files are saved, how results are returned, or any side effects. This is minimal and insufficient for a mutation-like operation.

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 a single, concise sentence that directly states the core function. There is no filler or redundant information; every word contributes to the meaning.

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

Completeness2/5

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

For a tool that splits PDFs by page ranges, the exact format and semantics of split_ranges are critical but omitted. The description also does not mention what happens with invalid ranges, whether ranges are inclusive, how output files are named or returned, or any edge cases. The existence of an output schema does not cover these input semantics, making the description incomplete for reliable invocation.

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?

With 0% schema description coverage, the description must compensate. It does clarify that split_ranges refers to 'page ranges', which adds meaning beyond the bare parameter name. However, it does not specify the structure of the ranges (e.g., array of {start,end} objects, inclusiveness, multiple ranges), leaving significant ambiguity for a tool that depends on this precise format.

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 uses a specific verb 'Split' and identifies the resource 'PDF' and the criterion 'by page ranges'. This clearly differentiates the tool from siblings like merge_pdfs (combining) and pdf_to_images (converting to images), making the purpose unmistakable.

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 does not provide any explicit guidance on when to use this tool versus alternatives. It only states the action without mentioning exclusions (e.g., if you need images, use pdf_to_images) or prerequisites, leaving the agent to infer usage from the name alone.

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

upload_fileB

Persist an uploaded file into the server temp directory.

Accepts:

  • Full path string

  • Short filename previously written to temp storage

  • Bytes / file-like / dict with base64 (will be saved to temp)

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYes
filenameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It discloses that files are saved to the server temp directory, which is useful, but it does not mention overwrite behavior, permissions, error conditions, file lifecycle, or how the operation interacts with temp resource listing. 'Persist' implies a write but lacks depth expected for a mutation-style tool with zero annotation support.

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?

The description is compact and front-loaded with the core purpose. The bullet list is a clear, scannable way to present accepted input types. Slightly more structure could clarify the relationship between `file` and `filename`, but there is no wasted prose.

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

Completeness2/5

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

For a tool with 0% schema parameter coverage, no annotations, and related sibling tools, the description is incomplete. It does not explain the `filename` parameter, the return value (despite an output schema), or how this tool connects to list_temp_resources and the specialized upload tools. The available information is not sufficient for an agent to confidently use all parameters and choose among siblings.

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 coverage is 0% and the `file` property is untyped ({}) in the schema, so the description is essential. It adds meaningful semantics by enumerating possible `file` values: full path, short filename, bytes/file-like, or base64 dict. However, the optional `filename` parameter is completely unexplained, leaving a gap in parameter understanding.

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 description names a specific action ('Persist') and a clear resource ('uploaded file into the server temp directory'). It also lists accepted input forms, which adds precision. However, it does not explicitly distinguish itself from sibling tools like upload_file_base64 or upload_file_url, despite overlapping capabilities (e.g., base64 dict).

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

Usage Guidelines3/5

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

The 'Accepts' bullet list implies usage scenarios (path, temp filename, bytes, base64 dict), giving some context for when to invoke the tool. But there are no explicit exclusions or comparisons with alternative sibling tools, leaving the decision between upload_file, upload_file_base64, and upload_file_url ambiguous.

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

upload_file_base64B

Upload a file encoded as base64 and persist it in temp storage.

Pass the base64-encoded content and the desired filename (e.g., "document.pdf").

ParametersJSON Schema
NameRequiredDescriptionDefault
base64Yes
filenameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries full burden for behavioral disclosure. It does reveal that files are persisted in temp storage, which is a meaningful side effect. However, it omits other behavioral details like validation, size limits, potential errors, or how the uploaded file is referenced later, leaving the agent partially informed.

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 two sentences: the first states the tool's purpose, the second confirms the parameter semantics. It is front-loaded, free of filler, and every word earns its place, making it highly concise and well-structured.

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

Completeness3/5

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

The tool is simple (2 required strings, no nested objects) and has an output schema, so return-value details are not needed in the description. However, the lack of usage guidance relative to sibling upload tools is a notable omission, and the description doesn't mention how the stored file relates to other temp-resource tools, leaving some contextual gaps.

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?

The input schema has no descriptions (0% coverage), so the description must clarify both parameters. It explains that 'base64' is the base64-encoded content and 'filename' is the desired name, with a concrete example. This adds meaningful context beyond the raw schema properties, though it doesn't specify details like allowed formats or max length.

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 description clearly states the tool uploads a base64-encoded file and persists it in temp storage. It uses specific verb 'upload' with resource 'file encoded as base64' and destination 'temp storage'. However, it does not distinguish from sibling tools like upload_file or upload_file_url, which also upload files, so it stops 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.

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus its siblings (upload_file, upload_file_url). It merely instructs how to pass parameters, with no mention of context, exclusions, or alternatives. This leaves the agent without criteria for tool selection.

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

upload_file_urlA

Download a file from a URL and persist it in temp storage.

Provide a direct URL and optional filename override. Requires 'requests' to be installed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
filenameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral transparency burden. It discloses the side effect of persisting the file to temp storage and mentions the runtime dependency ('Requires 'requests' to be installed'). However, it does not detail failure modes, size limits, or the relationship to temp storage resources, leaving some gaps.

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 concise: two short sentences, front-loaded with the primary purpose and then usage essentials. Every sentence contributes value without redundancy.

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?

Given the simple parameter set, presence of an output schema, and sibling tools that use temp storage, the description is sufficiently complete. It explains the operation and dependency, and the output schema can cover return values. Minor gaps exist regarding temp storage details, but it is adequate for the tool's scope.

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?

Schema description coverage is 0%, so the description must add meaning. It explicitly mentions 'url' and 'optional filename override', clarifying the role of each parameter beyond the bare schema. It does not fully describe filename behavior (e.g., default derived from URL), but it covers the main semantics.

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 clearly states 'Download a file from a URL and persist it in temp storage', using a specific verb (download/persist) and resource (URL file to temp storage). This clearly distinguishes it from sibling tools like upload_file (local file) and upload_file_base64 (base64 data).

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

Usage Guidelines3/5

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

The description implies usage: 'Provide a direct URL and optional filename override.' This gives context on how to use the tool. However, it does not explicitly mention when to use this versus the sibling upload_file/upload_file_base64 tools, or any exclusions. The usage is implied rather than explicitly contrasted with alternatives.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 15 tool updatesv0.1.0
    • First observedextract_metadata
    • First observedextract_text
    • First observedextract_text_by_page
    • First observedget_pdf_info
    • First observedget_resource_base64
    • First observedimages_to_pdf
    • First observedlist_temp_resources
    • First observedmerge_pdfs
    • First observedpdf_to_images
    • First observedrotate_pages
    • First observedserver_info
    • First observedsplit_pdf
    • First observedupload_file
    • First observedupload_file_base64
    • First observedupload_file_url
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0
Disambiguation3/5

Most tools have clear, distinct purposes (extract_text vs extract_text_by_page vs extract_metadata), but get_pdf_info and extract_metadata overlap conceptually, and upload_file accepts base64 dicts, making upload_file_base64 redundant. The three upload tools introduce ambiguity about which to use.

Naming Consistency4/5

The majority of tools follow a verb_noun snake_case pattern (e.g., extract_text, merge_pdfs, upload_file). However, server_info lacks a verb, and pdf_to_images/images_to_pdf are noun_to_noun, creating minor inconsistencies in an otherwise predictable naming scheme.

Tool Count4/5

15 tools is at the upper boundary of the ideal 3-15 range, but the coverage of PDF processing operations (extract, merge, split, rotate, convert, upload) justifies the count. A few upload variants could be consolidated, but the overall scale is reasonable for a specialized server.

Completeness4/5

The tool set covers core PDF lifecycle operations well: creation from images, text extraction, metadata, merging, splitting, rotation, and conversion to images. The main gap is the absence of any delete/remove operation for temporary resources, which can leave dead ends in workflows.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PDF Reader MCP Server

    averagejoeslab
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides comprehensive PDF processing capabilities including text extraction, image extraction, table detection, annotation extraction, metadata retrieval, page rendering, and document structure analysis.
    -

  • pdf-mcp

    angshuman
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides tools for reading, writing, and manipulating PDF files, including text extraction, metadata retrieval, and merging or splitting documents. It also enables users to create PDFs from plain text and convert specific pages or entire documents into images.
    53
    ISC

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gabrielmrojas/pdf_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server