Document to Markdown
talonic_to_markdownConvert any document—PDF, scan, or image—into clean markdown text using OCR. Accepts document ID, file upload, local path, or URL for flexible input.
Instructions
STATUS: stable.
Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown.
USE WHEN:
The user wants the full text content of a document for summarisation, translation, or analysis.
A previous tool call returned a document_id and you want to inspect its content.
The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise).
The user has a raw PDF / scan / image and wants markdown directly without designing a schema first.
DO NOT USE WHEN:
The user wants specific structured fields (use talonic_extract with a schema).
INPUTS (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path):
document_id: id of an already-ingested document. Cheapest path, one API call.
file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit.
file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead.
file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | No | The Talonic document id whose markdown you want. Get this from a previous talonic_extract or talonic_search response. | |
| file_data | No | Base64-encoded file bytes. Recommended path when the agent already has the file in memory (e.g., the user attached a PDF to the conversation). Pair with `filename` so MIME type can be inferred. | |
| filename | No | Original filename including extension, e.g. 'invoice.pdf'. Used to infer MIME type when uploading via `file_data`. Required when `file_data` is provided. | |
| file_path | No | Local path to a document file. Only works if the MCP server has read access to that path. In sandboxed chat clients (Claude Desktop, Cowork) use `file_data` instead. | |
| file_url | No | URL to a document file. The Talonic API fetches it server-side. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ID of the document the markdown was extracted from. | |
| markdown | Yes | OCR-converted markdown text content of the document. | |
| cost | No | Per-call cost and post-call balance from the underlying extract step, parsed from the X-Talonic-* response headers. `null` when the document was already ingested (document_id path) and no extract call ran. Not always present on legacy clients. |