Talonic

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.

talonic_find_data

Fix one document of a contract: set what it is (`role`), leave it out of the fold (`excluded`), file it under another contract key (`contract_key`; a new key creates that contract, null returns it to its derived key), or take it off the contract (`remove`). USE WHEN: cleaning — a key holds several contracts (move each set to its own key, e.g. '1042460-WLV / An der Walze 12'), an email is read as a termination (exclude it), an amendment is read as a base contract (role). NOT FOR: moving all documents of a contract at once (talonic_contracts_merge). ARGS: `contract_id`, `document_row_id`, and one or more of `role`, `excluded`, `contract_key`; or `remove: true` alone. RETURNS: the contract the document ends up in, recomputed. A hand-set key and role survive re-reading.

talonic_contracts_update_document

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.

talonic_get_agent_task

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.

talonic_get_field

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.

talonic_get_balance

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.

talonic_get_document

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 }.

talonic_get_pricing

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.

talonic_get_usage

Get one Spec's structure: identity and version state, the schema it materializes onto, `nodes[]` (the rail as authored, in editing order) and `phases[]` (the compiled execution plan, in run order — a validation checkpoint expands to one phase per gate, so the two lists differ on purpose), and `fields[]` (Spec field ↔ schema field). USE WHEN: you need to explain what a run will do, confirm a Spec is published (`version` non-null) before talonic_run_spec, or map field names to keys. NOT FOR: listing Specs (talonic_list_specs) or starting a run (talonic_run_spec). ARGS: `spec_id` (UUID from talonic_list_specs); optional `include_versions` (adds `versions[]` — published versions newest first, each { version, content_hash, created_at, is_materialized }). RETURNS: the Spec object { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, schema, nodes[], phases[], fields[], links } plus optional versions[].

talonic_get_spec

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.

talonic_heartbeat_agent_task

Extend the lease on a claimed decision task, never past its sla_deadline_at. USE WHEN: deciding may run past lease_expires_at; heartbeat before expiry using the epoch from claim. NOT FOR: acquiring a task (talonic_claim_decision_task) or finishing one (talonic_submit_decision_task / talonic_release_decision_task / talonic_fail_decision_task). ARGS: task_id and execution_epoch. A stale or foreign epoch returns HTTP 409: stop, discard the work, and re-list. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

talonic_heartbeat_decision_task

The AP worklist: every held invoice, why (each hold with its reason, finding, explanation and dollars), and the dollars at stake. USE WHEN: deciding what to dispute or fix before posting. NOT FOR: invoices ready to post (talonic_ap_bills with status=ready). ARGS: none. RETURNS: { currency, data[] { key, vendor, invoice_number, entity, document_id, filename, amount, at_stake, holds[] } }.

talonic_ap_issues

List AP invoices as posting-ready vendor bills, each with vendor, invoice number, dates, amount (as invoiced and in the ledger currency), entity, status, holds with dollars and evidence, NetSuite mapping and lines. USE WHEN: looking up invoices by vendor or number, or listing the ready or held ones. NOT FOR: totals (talonic_ap_overview). ARGS: `status` ready|held, `entity` (entity code), `reason` above_contract|duplicate|missing_po|vendor_unknown, `query` (vendor, number, filename or contract contains), `limit` (default 500). RETURNS: { currency, total, data[] }.

talonic_ap_bills

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.

talonic_list_agent_tasks

List one External-mode app's decision tasks (runs parked for an outside agent to decide), newest first. USE WHEN: looking for decisions to make for an app; begin with status 'available'. This is the polling alternative to the app.decision_task.offered webhook. NOT FOR: Agent-stage document tasks (use talonic_list_agent_tasks), reading a task's input package (claim it, then talonic_read_decision_package), or taking a lease (talonic_claim_decision_task). ARGS: app_id, optional status, limit, cursor. RETURNS: task metadata only (id, run_id, status, execution_epoch, lease and sla_deadline_at timing) plus pagination.next_cursor. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

talonic_list_decision_tasks

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.

talonic_list_fields

List the workspace's Specs — the configured pipelines (rail + fields) that talonic_run_spec executes. Each row: id, name, description, schema_id (the schema a run materializes onto — a DIFFERENT id from the Spec's), version / materialized_version (null = never published), field_count, node_count, timestamps. USE WHEN: the user wants to run 'their pipeline' / 'the invoice Spec', or you need a spec_id for talonic_run_spec / talonic_get_spec. NOT FOR: ad-hoc extraction schemas (talonic_list_schemas) or discovering fields (talonic_list_fields). ARGS: optional `search` (name contains, case-insensitive), `limit` (1–100, default 20), `cursor` (from pagination.next_cursor), `order` (asc|desc by updated_at). RETURNS: { data[] of { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, created_at, updated_at, links }, pagination { total, limit, has_more, next_cursor } }.

talonic_list_specs

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`.

talonic_list_schemas

List the workspace's contracts: key, title, counterparty, status, start, end in force, notice deadline, document count, next open date, and what Contract Pricing and Money Found report per contract. USE WHEN: getting an overview, finding a contract by key/name, or counting by status. NOT FOR: one contract's terms and documents (talonic_contracts_contract); what needs cleaning (talonic_contracts_issues). ARGS: `query` (key, title or counterparty contains), `status`, `key` (exact). RETURNS: data[] { id, contract_key, title, counterparty, status, effective_date, expiry_date, notice_deadline, documents, next_date, links }.

talonic_contracts_register

Mark a key date handled (or open again), e.g. a notice deadline someone has dealt with. Handled dates leave the upcoming list and raise no alert. USE WHEN: the user confirms a date is taken care of. NOT FOR: changing the date itself (it follows the documents). ARGS: `key_date_id` (key_dates[].id from talonic_contracts_contract or id from talonic_contracts_upcoming), `handled`, `note`. RETURNS: { id, handled }.

talonic_contracts_key_date

Move every document of one contract under another key (the same contract read under two keys, e.g. '1042460' and '1042460-WLV'). The emptied contract disappears. USE WHEN: two register rows are the same contract. NOT FOR: moving single documents (talonic_contracts_update_document). ARGS: `contract_id` (the one to empty), `into_key`. RETURNS: { moved, contract } — the contract under into_key, recomputed.

talonic_contracts_merge

Simulated NetSuite posting runs: the list, or one run with its internal ids and posting log. USE WHEN: checking what an earlier export posted. NOT FOR: posting (talonic_ap_netsuite_post). ARGS: `run_id` (one run; omit for the list). RETURNS: { data[] } or one run { results[], skipped[], log[] }.

talonic_ap_netsuite_runs

The exact NetSuite vendor bill records a posting would send (REST Record API `vendorBill` bodies: entity, subsidiary, tranId, tranDate, dueDate, terms, currency, expense / item sublists, memo naming the source document and page), and the invoices left out with the reason. The NetSuite target is a simulated sandbox. USE WHEN: showing or checking what would be exported to NetSuite. NOT FOR: posting (talonic_ap_netsuite_post). ARGS: `include_held` (also send held invoices, on payment hold; duplicates are never sent). RETURNS: { adapter { mode: 'simulated_sandbox' }, records[] { bill_key, method, path, body }, skipped[], totals }.

talonic_ap_netsuite_preview

Poll a Spec run started by talonic_run_spec: normalised status plus document-level progress and, for pipelines, per-phase progress. USE WHEN: waiting for a run to finish — poll every 5–10 s; stop on `completed` or `failed`. NOT FOR: reading the structured rows (talonic_get_run_results) or starting a run (talonic_run_spec). ARGS: exactly one of `pipeline_id` (run_kind 'pipeline') or `run_id` (run_kind 'run'), from the RunEnvelope. RETURNS: { run_kind, run_id, pipeline_id, spec_id, status, raw_status, input_count?, progress { total_documents, completed_documents, error_documents, phases?[] }, documents?[], error_message?, created_at, updated_at }.

talonic_get_run

Poll an ask started by talonic_ask that was still processing when the wait ended. USE WHEN: talonic_ask returned status 'processing' with an ask_id — poll every few seconds until 'completed' or 'error'. NOT FOR: asking a new question (talonic_ask). ARGS: `ask_id`. RETURNS: the same answer envelope as talonic_ask (answer, citations[], verification, usage) or { status: 'processing', poll_hint }.

talonic_get_answer

Post the vendor bills to the SIMULATED NetSuite sandbox: each record is answered as NetSuite's REST API answers a created record (204 with the new internal id), and the run's posting log is kept. Nothing is sent to any NetSuite account; say so when reporting the result. USE WHEN: the user asks to run the NetSuite export or a shadow posting. NOT FOR: looking at the payload (talonic_ap_netsuite_preview). ARGS: `include_held` (held invoices on payment hold), `dry_run` (answer without keeping the run), `limit`. RETURNS: { id, records, amount, results[] { bill_key, external_id, internal_id, status, location, payment_hold }, skipped[], log[] }.

talonic_ap_netsuite_post

Read one page of a claimed decision task's frozen input package: the records the decision must be made from, with their provenance locators. Only the current claimant may read it; each page read is journaled onto the run. USE WHEN: after a successful claim, walking pages from package.first_cursor while pagination.has_more is true. The first page also carries the source documents list. A mining_round package is one record { system_prompt, first_turn, tools }. NOT FOR: unclaimed tasks (HTTP 409; claim first) or listing tasks (talonic_list_decision_tasks). ARGS: task_id, optional cursor and limit (1 to 2000). Copy evidence locators verbatim from these records for the submit. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

talonic_read_decision_package

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.

talonic_field_values

Read a Spec run's structured rows — one row per document with the Spec's fields as clean values (held/pending-review cells serialize null), plus the column definitions. USE WHEN: talonic_get_run reports `completed` (partial rows are also readable while `processing`). NOT FOR: progress (talonic_get_run) or per-field provenance of a single value (include: ['provenance'] here, or talonic_field_values). ARGS: exactly one of `pipeline_id` (run_kind 'pipeline', optionally with the envelope's `run_id` to scope to that submission) or `run_id` alone (run_kind 'run'); optional `document_id` (one document), `include` (['cells','provenance'] — heavier payload), `limit` (1–200, default 50), `cursor`. RETURNS: { run_kind, status, columns[] of { field_key, display_name, data_type }, data[] of { document_id, filename, record_id, status ('complete'|'partial'|'error'|'processing'), completed_at, fields { field_key: value }, cells?, provenance? }, pagination, pending_review_count, links }.

talonic_get_run_results

Read a contract's documents again (or one of them), e.g. after cleaning or when values did not verify. One model call per document; hand-set values and roles are kept. USE WHEN: a contract's terms look wrong and the documents are right. NOT FOR: documents never read (talonic_contracts_import). ARGS: `contract_id`, `document_row_id` (optional, all when omitted). RETURNS: { queued, skipped }. Then poll talonic_contracts_import_status.

talonic_contracts_reread

Queue contract documents to be read; the platform reads them in the background (one model call each) and files each under its contract. USE WHEN: filling the app. `all: true` queues every unread candidate (narrow with query, contract_keys, only_priced; `limit` for a first batch); `document_ids` queues exactly those. Always run `all` with `dry_run: true` first and say how many documents it will read. NOT FOR: reading a contract again after cleaning (talonic_contracts_reread). ARGS: `all` or `document_ids`; with all: `query`, `contract_keys`, `only_priced`, `limit`, `dry_run`; with document_ids: `force` (read again even if read). RETURNS: all → { dry_run, contracts, documents, queued, skipped }; document_ids → { queued, skipped }. Then poll talonic_contracts_import_status.

talonic_contracts_import

Read one contract in full: terms in force (each with the document and verbatim quote it rests on), documents in fold order with what each states (unverified values carry their `problem`), key dates, decisions and links to the other apps. USE WHEN: checking or cleaning a contract; you need document row ids for talonic_contracts_update_document. NOT FOR: the list of contracts (talonic_contracts_register). ARGS: `contract_id`. RETURNS: { contract, documents[] { id, document_id, filename, role, excluded, extract }, key_dates[], links, decision, history }.

talonic_contracts_contract

Read the AP configuration: which captured document kinds are bills, the contract register used for entity and cost centre, entities with their system and NetSuite subsidiary, the NetSuite mapping (accounts, departments, terms, currencies, vendors). USE WHEN: before changing the configuration, or to explain why an invoice maps the way it does. NOT FOR: invoices (talonic_ap_bills). ARGS: none. RETURNS: { config, saved, updated_at }.

talonic_ap_config

Record a decision on a contract: terminated, notice_sent, renewal_declined, or active (withdraws the earlier one). Recorded as made through the API key, with your note; the contract's status, end and key dates follow. USE WHEN: the user states the decision or it is confirmed by a document they point to. Never infer a termination on your own. NOT FOR: a termination letter already in the documents (it is read as a fact; check talonic_contracts_contract). ARGS: `contract_id`, `state`, `note` (say where the decision comes from). RETURNS: the contract, recomputed.

talonic_contracts_decide

Release a claimed decision task back to 'available' without deciding it; the next claim bumps the epoch. USE WHEN: you cannot finish within the lease or SLA but another claimant could decide it. NOT FOR: declaring the task undecidable (talonic_fail_decision_task, which raises a review and applies the app's fallback) or keeping the lease (talonic_heartbeat_decision_task). ARGS: task_id and execution_epoch. Stale epoch is HTTP 409. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

talonic_release_decision_task

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.

talonic_request_upload

Run a Spec — the customer's configured pipeline — over documents, in one call. Two inputs: `document_ids` (documents already in the workspace; for a new file, first talonic_request_upload → poll talonic_get_document until completed) OR `file_urls` (public https files, max 20; Talonic ingests them first). Consumes credits. USE WHEN: the user wants to 'run the invoice pipeline on these documents', process files through their Spec, or produce the Spec's structured rows. NOT FOR: one-off extraction with an ad-hoc schema (talonic_extract), or checking progress (talonic_get_run) / reading rows (talonic_get_run_results). ARGS: `spec_id` (talonic_list_specs); exactly one of `document_ids[]` (1–500) or `file_urls[]` (1–20, https); optional `name`, `pipeline_mode` (`new` default | `append` to the Spec's existing pipeline); `batch_id` and flat `metadata` only with file_urls. RETURNS: RunEnvelope { run_kind ('pipeline'|'run'), run_id, pipeline_id, spec_id, status ('processing'|'completed'|'failed'), raw_status, input_count, documents?, message?, links }. Then poll talonic_get_run with the `pipeline_id` when run_kind is 'pipeline', or with the `run_id` when it is 'run', every 5–10 s until status is completed/failed, then talonic_get_run_results.

talonic_run_spec

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`.

talonic_save_schema

Replace the AP configuration with a complete new one (validated by the platform). Run with dry_run first. USE WHEN: setting up AP for a workspace or changing the NetSuite mapping. NOT FOR: partial edits; read talonic_ap_config, change it, and send the whole object. ARGS: `config` (the whole configuration object), `dry_run` (validate only). RETURNS: { config, saved }. A broken config returns the list of problems.

talonic_ap_save_config

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.

talonic_search