PDFHaul MCP

ocr_pdf

Call this when a PDF's text cannot be extracted, selected, or searched -- typically a scanned document or a photo of a page saved as PDF. It runs OCR and returns a new PDF with a real, selectable text layer; the original file is not modified. Do NOT use this to convert a PDF to Word or Excel -- pdf_to_word already runs OCR internally on scanned pages, so call ocr_pdf only when you need the output to stay a PDF (e.g. to make it searchable, or before another PDF-only tool). If the PDF already has a usable text layer, OCR is skipped automatically, ocrApplied is returned false, and message explains that no OCR was needed -- relay that message to the user rather than assuming OCR ran. Pass forceOcr: true to force a full re-recognition pass anyway (useful if the existing text layer is garbled). Supports 15 languages in a single pass. Use list_files or upload_from_url to obtain the fileId first.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fileId": "<fileId>"
    },
    "name": "ocr_pdf"
  }
}

Input Schema

Name	Required	Description
`fileId`	Yes	The ID of the PDF file to OCR
`forceOcr`	No	Force a full OCR re-recognition pass even if the PDF already appears to have a text layer. Defaults to false.
`language`	No	Primary language of the document text. Defaults to eng.
`idempotencyKey`	No	Optional unique key (UUID) for this operation. If provided and the same key is received again within 5 minutes, the cached result is returned instead of re-executing the operation. Generate a fresh UUID per operation intent; reuse it only on retry.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 1, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the substantive behavior: a new file is produced and the input is never modified, OCR is auto-skipped when a text layer exists with ocrApplied=false and a message to relay to the user, forceOcr triggers a full re-recognition pass when the existing layer is garbled, and 15 languages are handled in one pass. This is behavior an agent cannot infer from the structured fields.

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?

Front-loaded with the call condition, then the negative case, then edge-case behavior, then parameters, then prerequisites. Dense but every sentence carries decision-relevant content; nothing is repeated from the schema or annotations.

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?

No output schema exists, yet the description covers the return shape (new PDF, ocrApplied flag, explanatory message) and warns against misreporting a skipped OCR as a success. Combined with clear prerequisites, an agent has everything needed to call it and interpret the result 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining the real use case for forceOcr (garbled existing text layer rather than simply 'force re-recognition') and by noting single-pass multi-language support, which frames the language enum as non-restrictive. It does not explain idempotencyKey, which the schema already covers well.

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?

States a specific verb and resource: runs OCR on a PDF and returns a new PDF with a selectable text layer, with the original left untouched. It explicitly distinguishes itself from pdf_to_word, which also OCRs, so an agent can tell the two apart without opening either schema.

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

Usage Guidelines5/5

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

Gives a precise trigger condition (text cannot be extracted, selected, or searched, e.g. a scanned document), an explicit exclusion (do NOT use to convert to Word or Excel because pdf_to_word already OCRs), and the narrowing condition for still choosing this tool (output must remain a PDF, or must precede another PDF-only tool). It also names list_files and upload_from_url as the way to obtain fileId.

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

All PDFHaul MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?