Talonic

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.

talonic_to_markdown

STATUS: stable. Production-safe when called with a schema. Schema-less extraction is disabled at the MCP layer. Extract structured, schema-validated data from a document using Talonic. Returns clean JSON matching the schema, with per-field confidence scores and metadata about the document (detected type, language, page count). USE WHEN: - The user has a document (PDF, image, scan, DOCX, etc.) and wants specific fields pulled out. - You need structured data (vendor name, total amount, dates, parties, terms) rather than free text. - The user uploads or references any invoice, contract, certificate, statement, or form. - You want validated JSON instead of trying to OCR + parse with raw LLM calls. DO NOT USE WHEN: - The user just wants the full text content (use talonic_to_markdown after extracting once). - The user wants to find documents matching a query (use talonic_search or talonic_filter). FILE SOURCES (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path): - 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: a local path to the document. Only works if the MCP server process can read that path on its own filesystem. Chat clients (Claude Desktop, Claude.ai, Cowork) store user uploads in a sandbox the MCP server cannot access, so file_path is only useful when the agent explicitly knows a path on the same machine as the MCP server. - 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. - document_id: re-extract a document already in the workspace. Cheapest option when the document is already uploaded via app.talonic.com or a previous extract call. SCHEMA (REQUIRED, provide exactly one of `schema` or `schema_id`): - JSON Schema (RECOMMENDED): { type: "object", properties: { vendor_name: { type: "string" } } }. - Flat key-type map: { vendor_name: "string", invoice_total: "number" }. Accepted, but if you get a "no fields" error, fall back to JSON Schema. - schema_id: id of a saved schema from talonic_list_schemas. Accepts UUID or SCH-XXXXXXXX short id. Calls without `schema` or `schema_id` are rejected with a validation error before they hit the API, to prevent unreliable schema-free extractions reaching production. RESPONSE SHAPE (key fields): - data: the structured extracted JSON, shaped by your schema. - confidence.overall: 0..1 confidence for the extraction as a whole. - confidence.fields: per-field confidence map. Treat fields below ~0.7 as needing human review. - document.id, document.filename, document.pages, document.type_detected, document.language_detected. - extraction_id, request_id: stable identifiers for support and re-fetch. - processing.duration_ms, processing.region: useful for debugging and capacity planning. - markdown: present only when `include_markdown: true`. - provenance: present only when `include_provenance: true`. Per-field source evidence: { field_name: { source_text, section, page } }. Useful for audit trails and citations. Cost, EUR price, and remaining credit balance are not surfaced in v0.1 and may appear in a later version. LARGE FILES / HOSTED ENVIRONMENTS: For files larger than ~32KB, or when running in a hosted/sandboxed environment (Claude.ai, ChatGPT), use talonic_request_upload first to get a browser upload link, then use the returned document_id with this tool.

talonic_extract

STATUS: stable. Field-name resolution is server-side. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both `value` and `value_to`. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. - is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing. SCHEMA TYPING: - Numeric operators (`gt`, `gte`, `lt`, `lte`, `between`) only resolve correctly when the schema field is typed as `number`. A field typed as `string` that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. - **Preventive check:** call `talonic_search` first and inspect `fieldMatches[].dataType` / `fields[].dataType` on the field you intend to filter. If `dataType !== 'number'`, do NOT use a numeric operator on it — either pick a different field, switch to a string-friendly operator (`eq`, `contains`), or warn the user that the schema field needs a `data_type` change before the filter can succeed. - **Reactive fallback:** if the filter response contains a `warnings` array, surface its `message` (and `suggestion`, if present) to the user verbatim — these explain *why* a query returned zero or unexpected results and typically suggest a schema-design change. Do not silently retry without flagging the warning. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as `field` here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both `field` (name) and `field_id` (UUID) reach the API as `fieldId`. Either is fine.

talonic_filter

STATUS: stable. Read the user's current Talonic credit balance, EUR value, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp. Use this to make budget- aware decisions before kicking off large batches or re-extractions. USE WHEN: - The user asks how many credits or how much budget they have left. - You are about to run a large or expensive operation (batch extract, re-extract many documents) and want to confirm budget headroom first. - The user asks how long their balance will last at the current rate. DO NOT USE WHEN: - The user just wants the per-call cost of a single extraction (that is already on the talonic_extract response under `cost`). - The user wants to top up credits (route them to the dashboard; auto top-up is guarded by a separate scope). RESPONSE SHAPE: - balance_credits: current credit balance. - balance_eur: current balance in EUR (rounded to two decimals). - burn_rate_30d_credits: total credits consumed in the trailing 30 days. - projected_runway_days: days of runway at the current 30-day average burn. `-1` indicates no consumption in the trailing window (cannot compute runway). - tier: API tier of the workspace (`free`, `pro`, `enterprise`, etc.). - tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.

talonic_get_balance

STATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - You called talonic_request_upload and need to poll until the user has uploaded the file. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document). STATUS VALUES on the response `status` field: - pending_upload: document slot reserved via talonic_request_upload, file not yet received. Keep polling (~5 s interval). Token expires after 15 min — if status stays 'pending_upload' past the expires_at returned by talonic_request_upload, the user did not upload in time. - queued / extracting: file received, OCR and exhaustive extraction in progress. Keep polling. - completed: extraction is done. This is the state to wait for before calling talonic_extract with a schema or schema_id — the schema-specific LLM pass runs off the cached OCR'd text. - uploaded: file received but the extraction queue could not be enqueued (rare, e.g. Redis unavailable). The talonic_extract endpoint will trigger processing inline if called. - error / ocr_failed / extraction_failed: terminal failures; processing_log carries the reason.

talonic_get_document

STATUS: stable. List all saved schemas in the user's Talonic workspace. Returns a COMPACT SUMMARY of each schema: id (UUID), short_id (SCH-XXXXXXXX), name, description, version, and field_count. Either id form is accepted by talonic_extract's `schema_id` parameter, so you can extract with a saved schema straight from this list. The full JSON Schema definition for each field is intentionally NOT included here — for many schemas that payload is large and gets truncated by some clients. To inspect a schema's full field definitions, read the `talonic://schemas` resource. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as `schema_id`.

talonic_list_schemas

STATUS: stable. Request a file upload link for the user. Use this when the user wants to extract a file but you cannot deliver it directly (e.g., the file is too large for tool-call arguments, or you're running in a sandboxed environment like Claude.ai). Returns an upload URL the user can open in their browser to drop the file, plus a document_id to track the upload. After showing the URL to the user, poll with talonic_get_document until status is 'completed' (the file has been uploaded, OCR'd, and is ready for schema-specific extraction). Then call talonic_extract with the document_id and a schema or schema_id. IMPORTANT: a user message like 'uploaded', 'done', or 'I dropped it' only confirms the browser-side upload finished. It is NOT a signal that server-side processing is complete. The document still needs OCR and exhaustive extraction (typically 10-30 s after the browser upload). You MUST poll talonic_get_document yourself until status is 'completed' regardless of what the user says. Calling talonic_extract before status is 'completed' may return errors. USE WHEN: - The user has a file to extract but you cannot send it via tool-call arguments (e.g., file is larger than ~32KB, or the environment blocks outbound data). - You are running in a hosted/sandboxed environment (Claude.ai, ChatGPT) where file_data cannot be used reliably. - The user explicitly asks for an upload link. DO NOT USE WHEN: - You can deliver the file directly via file_data (local-stdio installs with small files). - The file is already accessible via a public URL (use file_url on talonic_extract instead). - The document is already in the workspace (use document_id on talonic_extract instead).

talonic_request_upload

STATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with `schema_id` set to the returned id (UUID or SCH- short id) for consistent results.

talonic_save_schema

STATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a `filterable` boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.

talonic_search