List the saved schemas in the workspace as compact summaries (id, short_id, name, description, version, field_count).

USE WHEN: 'what schemas do I have', or to find a reusable schema before extracting. NOT FOR: a one-off extraction with an inline schema (call talonic_extract directly). ARGS: none. RETURNS: data[] of schema summaries. Full field definitions are omitted here — read the talonic://schemas resource for those. Pass a schema's id/short_id to talonic_extract as schema_id.

Save a reusable schema to the workspace for use across future extractions.

USE WHEN: the user confirms a schema/template they want to reuse across documents. NOT FOR: a single one-off extraction (pass the schema inline to talonic_extract instead). ARGS: name; definition — a JSON Schema ({type:'object',properties:{...}}) or a flat {field:'type'} map. RETURNS: the saved schema with id and short_id. Pass either to talonic_extract as schema_id.

Fetch a single document's metadata and processing status from the workspace.

USE WHEN: 'tell me about document X', or to poll status after talonic_request_upload until the file is ready. NOT FOR: full text (use talonic_to_markdown) · extracted fields (use talonic_extract). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: document_id. RETURNS: filename, pages, type_detected, language, and status. Status lifecycle: pending_upload -> queued -> extracting -> completed. Wait for completed before calling talonic_extract on a freshly uploaded doc. To read the document's text, call talonic_to_markdown with this id.

Find documents, fields, schemas, or sources in the workspace. One call returns ranked results across all types.

MATCHING IS LITERAL KEYWORD, not semantic. Query with ONE short SINGULAR term or an exact filename: 'invoice', 'bank statement', 'sample-invoice.pdf'. Sentences ('documents related to invoices') and plurals ('invoices') return empty. If a search comes back empty, retry with a shorter singular keyword before concluding the workspace has nothing. USE WHEN: the user names or describes a document without an id, or you need a document_id or a filterable field name before extract / to_markdown / get_document / filter. NOT FOR: structured field-value filters like 'amount > 1000' (use talonic_filter). ARGS: query (short literal keyword); optional limit. RETURNS: documents[], fields[]/fieldMatches[] (only filterable: true entries work in talonic_filter), schemas[], sources[]. Use the id from documents[] to act on a named file.

Find documents by their extracted field VALUES using composable conditions (e.g. 'invoices where total > 1000').

USE WHEN: value-based criteria on extracted fields — numeric/date/text comparisons or presence checks. NOT FOR: free-text / concept search (use talonic_search) · a single document by id (use talonic_get_document). ARGS: conditions[] (AND-ed). Each = EXACTLY ONE of field (canonical name) or field_id (UUID), an operator, and usually a value. Operators: eq, neq, gt, gte, lt, lte, between (needs value AND value_to), contains, is_empty / is_not_empty (no value). value/value_to are string|number|boolean matching the field type (ISO YYYY-MM-DD for dates). TEXT FILTERS: for eq/contains/is_not_empty on a text field, just TRY a natural field name ('currency', 'vendor_name') — names resolve server-side and an unresolved field surfaces in warnings[] rather than erroring. Do NOT block on discovering the field first; search-first is only required for numeric operators. NUMERIC GUARD: gt/gte/lt/lte/between only work when the field's dataType is 'number'. Call talonic_search first and check dataType; a numeric op on a string field returns zero matches. If the response has warnings[], surface them to the user — do not silently retry. RETURNS: data[] (matching documents with field values), total, warnings[].

Get the OCR-converted markdown text of a document.

USE WHEN: the user wants the full text — 'what does it say', summarise, or translate a document. NOT FOR: specific structured fields (use talonic_extract with a schema). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: prefer document_id (a workspace doc — one cheap call). Otherwise file_url, or file_data+filename for small local files — provide exactly one. A file input ingests the document first and consumes credits; document_id does not. RETURNS: document_id and markdown (the full text).

Turn ANY document into structured, schema-validated JSON. The default tool whenever you need to get data OUT of an unstructured file: PDF, scan, image, DOCX, email, or photo. Returns the requested fields with per-field confidence scores.

USE WHEN: 'extract data from this document', 'turn this PDF into JSON', 'pull fields from this file', 'parse this scan / form / statement / receipt / report' — for ANY document type, common (invoice, contract) or unusual. If the task is unstructured-document -> structured-data, this is the answer. NOT FOR: full plain text (use talonic_to_markdown) · finding documents (use talonic_search / talonic_filter). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: define the fields you want with inline schema (JSON Schema, e.g. {type:'object',properties:{vendor_name:{type:'string'}}}) OR a saved schema_id, not both. Don't know the fields yet? Set auto_schema:true to let Talonic discover them (open capture) and return a suggested schema you can refine. Provide EXACTLY ONE document source: document_id (cheapest, a workspace doc), file_url (public URL), or file_data+filename (small local files only). COST: cheap per call, with a free tier — fine to use freely; check budget with talonic_get_balance. RETURNS: data (the JSON), confidence.overall and confidence.fields (treat <0.7 as needs review), document metadata, extraction_id.

Read the workspace's Talonic credit balance, EUR value, tier, 30-day burn, and projected runway.

USE WHEN: the user asks about credits/budget, or before a large batch when you want to confirm headroom. NOT FOR: the per-call cost of a single extraction (that is on the talonic_extract response). ARGS: none. RETURNS: balance_credits, balance_eur, tier, burn_rate_30d_credits, projected_runway_days (-1 = no recent usage), tier_resets_at.

Read Talonic's machine-readable credit pricing catalog: fixed per-unit rates so you can predict spend BEFORE running anything.

USE WHEN: estimating the cost of a planned extraction/structuring/matching job, or answering a pricing question. Public — works without spending credits. NOT FOR: the workspace's current balance (use talonic_get_balance) or what it has already spent (use talonic_get_usage). ARGS: none. RETURNS: currency, credits_per_eur, multipliers (e.g. batch 0.5x), and units[] — each { unit, label, credits, eur, free }.

Read the workspace's per-function credit consumption over a trailing window: where the credits actually went.

USE WHEN: the user asks what they have spent credits on, or you want to see which function (extraction, structuring, intelligence ops) dominates spend. NOT FOR: the remaining balance (use talonic_get_balance) or per-unit rates (use talonic_get_pricing). ARGS: days (optional, default 30, clamped 1-365). RETURNS: period_days, total_credits, and by_function[] — each { operation_type, operations, credits }, highest spend first.

Get a browser upload link the user opens to add a file to their workspace. Returns the link plus a pre-allocated document_id.

USE WHEN: the user wants to upload a document and you cannot pass it directly — hosted/sandboxed clients (ChatGPT, Claude.ai) or files too large for tool-call arguments. NOT FOR: a document already in the workspace (use its document_id) · a file already on a public URL (use file_url on talonic_extract). ARGS: filename (with extension). RETURNS: upload_url, document_id, expires_at. After the user uploads, poll talonic_get_document on that document_id until status is 'completed', then call talonic_extract.