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 -> uploading -> queued -> extracting -> completed. Wait for completed before calling talonic_extract on a freshly uploaded doc. Terminal failure statuses: ocr_failed, extraction_failed, error — stop polling and report the failure to the user if any of these appear. 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. If status becomes ocr_failed, extraction_failed, or error, stop polling and report the failure to the user.

List the workspace's Field Registry — the canonical concepts Talonic has discovered across every ingested document, each with a stable id, maturity level, data type, synonyms and occurrence count.

USE WHEN: you need to know WHAT data exists before querying it, want to pick the right concept for a question, or need the exact field id for talonic_get_field / talonic_field_values. NOT FOR: locating a specific document (talonic_search) or filtering documents by a value (talonic_filter).

ARGS: search (case-insensitive contains on name), maturity (core | proven | candidate — prefer core/proven for anything you will build on), include_superseded (default false: rows merged into another concept are hidden so you never see two ids for one concept), limit, cursor. RETURNS: data[] of { id, canonical_name, display_name, data_type, maturity, tier, synonyms, description, occurrence_count, superseded_by, links } plus cursor pagination.

Get the CONCEPT CARD for one Field Registry field: what it means (curated description + extraction instruction), its synonyms and aliases, maturity, where it occurs (document/occurrence counts, first/last seen, document-type spread), its value distribution (top values with counts, distinct count, examples), schema usage, and identity links (superseded_by, absorbed concepts).

USE WHEN: you must decide whether a field is the right concept for a question, need example values or the value shape before writing a filter, or hold a field NAME from the user and need the live concept behind it. NOT FOR: listing many fields (talonic_list_fields) or reading every value (talonic_field_values).

ARGS: exactly one of field_id or name. Names are resolved through canonical name → spelling fold → merge aliases → synonyms (then case-insensitive fallbacks) and followed to the live concept; the response says which arm matched. include_history: true appends the curation trail (merges, renames, maturity moves). RETURNS: the card { id, canonical_name, maturity, data_type, definition, identity, occurrence, values, usage, links } plus resolution when a name was given and history when requested.

Read a field's CURRENT VALUES across documents, with provenance — one row per bound occurrence: document id + filename + type, the value, confidence, the raw name it was captured under, the verbatim source text, and the resolution band that bound it.

USE WHEN: the user asks 'what are all the X across my documents', you need to tabulate or aggregate one concept across the corpus, or you want the evidence (source text + document) behind a value. NOT FOR: multi-field row-shaped queries over documents (talonic_filter) or one document's full field set (talonic_get_document).

ARGS: exactly one of field_id or name; optional document_id (one document), value (case-insensitive contains filter), limit (max 100), cursor. RETURNS: { field_id, canonical_name, concept_ids, data[] of { occurrence_id, document_id, document_filename, value, confidence, provenance{ raw_field_name, source_text, resolved_by, needs_confirmation, via_redirect }, links }, pagination }. Rows are Sources-IAM filtered for the caller.

Locate the REAL data behind a natural-language concept before querying anything: semantic + lexical retrieval that resolves a phrase ('payment volume per transaction', 'counterparty', 'Vertragslaufzeit') to the registry fields, values, documents and text passages that carry it — even when the field is captured under a different name.

USE WHEN: the user asks about a concept and you are not sure which field holds it, when talonic_list_fields / talonic_search came back empty or ambiguous, or when the answer may live in document prose rather than a captured cell. NOT FOR: reading a known field's values (talonic_field_values) or filtering by a known field (talonic_filter).

ARGS: query (the concept, in the user's words), optional top_k (1–25, default 10), document_ids (hard scope). RETURNS: ranked planes — FIELDS (canonical_name, field ids/keys, maturity/tier, occurrence_count, sample values with their documents), VALUES, DOCUMENTS and PASSAGES — every item a ready handle for the next call. Read-only, no LLM cost.

List the platform's agent tool registry — every retrieval, provenance and analysis primitive the in-product Talonic agent runs on (find_data, describe_data, query_data for read-only SQL over the extracted data, get_document_markdown, workspace_overview, …) with its input schema and whether THIS credential may invoke it.

USE WHEN: you want a capability talonic_* tools do not cover directly (e.g. SQL over the structured data, a workspace overview, cohort discovery) — list here, then call talonic_invoke_agent_tool with the tool name and its args. NOT FOR: discovering fields (talonic_list_fields / talonic_find_data) or documents (talonic_search) — those are shaped for you.

ARGS: only_invocable (default true — hide tools this key cannot run), include_schemas (default true — include each tool's JSON input schema). RETURNS: { tools[] of { name, description, impact, capability, can_invoke, input_schema? }, invocable_count, totalCount }.

Invoke ONE named tool from the platform's agent tool registry directly, with no model in the loop — you choose the arguments. This is how an external agent uses Talonic's retrieval and provenance while driving control flow itself (e.g. query_data for a read-only SQL SELECT over the extracted data, describe_data for the queryable field list, get_document_markdown to read a document's text).

USE WHEN: talonic_list_agent_tools showed a tool with can_invoke: true that does what you need. Pass exactly the args its input_schema declares. NOT FOR: anything a dedicated talonic_* tool already does (prefer those — they are shaped for you).

ARGS: name (tool name), args (object matching the tool's input_schema), optional document_ids (hard scope for scope-aware tools). RETURNS: { tool, result (the tool's parsed output), citations?, artifacts?, cards? }. Denied capabilities come back as an error naming the capability required; the platform re-checks every call.

List Agent-stage tasks visible to this Talonic workspace credential.

USE WHEN: looking for external-agent work to process; begin with status 'available'. NOT FOR: reading the immutable task payload (use talonic_get_agent_task) or taking a lease (use talonic_claim_agent_task). ARGS: optional status, limit, and cursor. RETURNS: metadata only plus pagination.next_cursor.

Fetch one Agent-stage task's immutable input snapshot, instructions, and declared output contract. This disclosure is audited.

USE WHEN: inspecting a listed task before deciding whether to process it. NOT FOR: acquiring the task (use talonic_claim_agent_task) or returning results (use talonic_submit_agent_task). ARGS: task_id. RETURNS: metadata, input_snapshot, output_contract, instructions, and timeout_fallthrough.

Claim an available Agent-stage task, or reclaim it after its lease expires.

USE WHEN: ready to process a task. Save the returned execution_epoch and lease_expires_at. NOT FOR: merely inspecting work (use talonic_get_agent_task) or extending an active lease (use talonic_heartbeat_agent_task). A conflicting live claim returns HTTP 409. A successful claim returns the task payload.

Extend the lease on a claimed Agent-stage task.

USE WHEN: processing may continue past lease_expires_at; heartbeat before expiry using the epoch from claim. NOT FOR: acquiring a task (use talonic_claim_agent_task) or submitting finished outputs (use talonic_submit_agent_task). ARGS: task_id and execution_epoch. Stale or foreign claims return HTTP 409.

Submit declared output fields for a claimed Agent-stage task and resume the parked document.

USE WHEN: processing is complete and every required output in output_contract is ready. NOT FOR: undeclared fields or partial lease maintenance (use talonic_heartbeat_agent_task). ARGS: task_id, execution_epoch, outputs keyed exactly by declared field key, and optional summary. The platform validates all fields and types transactionally before writing anything.