Talonic

Claim an available decision task (or reclaim one whose lease expired) and receive the decision bundle: task metadata with the new execution_epoch, output_contract, precedents, and a package descriptor { package_kind, record_count, page_size, first_cursor, documents }. USE WHEN: ready to decide a listed task. There is no separate get: claiming IS the payload fetch. Save execution_epoch and lease_expires_at; then read the records with talonic_read_decision_package starting at first_cursor (null means the package has no records). NOT FOR: extending a live lease (talonic_heartbeat_decision_task) …

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

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.

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…

Contract documents whose terms have not been read yet, grouped by the contract key in their filename; keys Contract Pricing already models first. USE WHEN: choosing what to read, or checking how the documents will group before importing. NOT FOR: reading them (talonic_contracts_import). ARGS: `query` (filename contains). RETURNS: data[] { contract_key, in_price_baseline, documents[] { document_id, filename, import } }.

Where the read queue stands: counts by status (pending, running, done, failed) and the latest failures with their error. USE WHEN: after talonic_contracts_import, poll until pending and running are 0. NOT FOR: the contracts themselves (talonic_contracts_register). ARGS: none. RETURNS: { counts, failed[] { document_id, filename, error, attempts } }.

The cleaning worklist: contracts that look wrong and why. Codes: several_base_contracts (one key holds several contracts), printed_number_differs, several_counterparties, several_sites, ended_by_message (an email read as the termination), unread_documents, no_dates, unverified_terms. USE WHEN: after an import, to decide what to fix; again after fixing, to confirm it is clean. NOT FOR: contracts that are fine (talonic_contracts_register). ARGS: `code` (only contracts with this issue, optional). RETURNS: data[] { contract_id, contract_key, title, status, issues[] { code, detail, document_ids } …

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

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.

Mark a process item handled (it ran: the price was agreed, the invoice went out, the entry was filed) or open again. A decision, recorded with who made it; it survives every rebuild. A moved deadline opens the process again. USE WHEN: a process from talonic_contracts_processes was done, or was marked by mistake. NOT FOR: key dates (talonic_contracts_key_date). ARGS: `process_id`, `handled` (true / false), `note` (what was done). RETURNS: { id, handled }.

Open processes the contract data starts for people across contracts, from the captured Spec fields, the ERP contract register (Dynamics ku_* columns), document types and Money Found: sales (price fixing 3 months before commissioning, the notice window as the ERP keeps it, missing sales opportunity, tacit renewals to reprice, lost to competition), billing (billing held until commissioning, ERP record after signing, run-out phase, CPI adjustment, rent due), legal (land-register entry, termination received, breach, change of control, consumer law), operations (overdue supply start, missing commis…

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, doc…

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.

Set one term on one document by hand, with the passage that states it copied verbatim from that document. The platform saves it only when the quote occurs in the document and prints the value. USE WHEN: a term was missed or read wrong and you have the exact passage (talonic_get_document or talonic_search to find it). NOT FOR: guessing a value; decisions (talonic_contracts_decide). ARGS: `contract_id`, `document_row_id`, `field`, `value` (ISO date for dates; fraction for escalation_pct; months for *_months), `quote`. RETURNS: the contract, recomputed; an error naming the problem when the quote…

Open key dates across all contracts, soonest first: notice deadlines, ends of term, renewals, price changes, terminations, dated obligations. Dates marked handled are left out. USE WHEN: what needs someone soon; preparing a renewal or notice decision. NOT FOR: one contract's dates (talonic_contracts_contract). ARGS: `days` (horizon, default the workspace's alert horizon, 90). RETURNS: data[] { id, contract_id, contract_key, title, kind, due_date, days_left, label, quote }.

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 o…

Confirm fields of a template's field sheet: the named keys, or every unconfirmed field (with include_entered false, leaving the fields entered per document unconfirmed). Confirming says a person checked the field's source; it is the user's decision, so only call this when the user asked to confirm. Run with dry_run first to list what would be confirmed. USE WHEN: the user reviewed the sheet and asks to confirm it (or some fields). NOT FOR: changing a field's source (talonic_doc_gen_update_template). ARGS: `template_id`, `keys[]` (omit for every unconfirmed field), `include_entered` (default t…

Delete a template and its field sheet for good. Generated batches keep their documents. Cannot be undone; only when the user asked. USE WHEN: the user asks to remove a template. NOT FOR: replacing the Word file (upload the new one, then delete the old one if asked). ARGS: `template_id`. RETURNS: { ok: true }.

Fill documents without generating them: for each row and template, every field's value with its origin, and what is still missing. Nothing is stored. USE WHEN: before talonic_doc_gen_generate, to check `missing` and the values the data gives. Fields whose source type is `case` are entered per document: the data does not hold them (e.g. the new owner), so pass them in `values` by field key (or case key). A value for any other field overrides the fill and is recorded as an edit in the document history. NOT FOR: making the files (talonic_doc_gen_generate). ARGS: `template_id` (+ `with_pair`) or …

Description is built at runtime.

Fill and generate the documents: one Word file (and PDF) per row and template, every value's origin kept in the document history. Refused while documents leave fields empty unless `allow_missing` (the empty fields are left out). The batch runs in the background: pass `wait_seconds` to wait for it (polls every 3 s). Run talonic_doc_gen_draft (or dry_run) first. USE WHEN: the user asks to generate letters or agreements for rows of a product. Fields whose source type is `case` are entered per document: the data does not hold them (e.g. the new owner), so pass them in `values` by field key (or cas…

The Doc Gen worklist: templates never proposed, proposals failed or with fields left without a suggestion, fields nobody confirmed, and batches of the last 30 days that failed, have failed documents or miss PDFs. USE WHEN: deciding what to fix before generating, or after a batch. NOT FOR: the headline counts (talonic_doc_gen_status). ARGS: none. RETURNS: { data[] { code (never_proposed|proposal_failed|proposal_pending|fields_unconfirmed|job_failed|documents_failed|pdf_missing), template_id?, template_name?, job_id?, detail, fields?[] } }.

Generated batches: the history (newest first, with document, failed and PDF-missing counts), or one batch with its documents, their files and errors. USE WHEN: checking a batch started by talonic_doc_gen_generate, or finding the document ids to download. NOT FOR: the file itself (talonic_doc_gen_file). ARGS: `job_id` (one batch; omit for the history), `limit` (1-50, history only). RETURNS: { data[] } or one batch { id, status, templateNames, savedToWorkspace, filesExpireAt, filesExpired, documents[] { id, recordLabel, status, files[] { kind, name, size }, error, pdfError } }.

The data products a template is filled from: the list, one product with its columns and reference table, or its rows (one document per row). USE WHEN: choosing the product to propose or generate against, or picking the rows (record ids) to generate for. NOT FOR: the template's fields (talonic_doc_gen_templates). ARGS: `product_id` (one product; omit for the list); with `records: true` its rows, filtered by `query` (label or any value contains) and `limit` (1-500, default 50). RETURNS: list { data[] }, one product { id, name, columns[], reference }, or rows { total, data[] { id, label, values,…

Read or change the writer's details a fill reads for fields with source { type: 'user' }: name, kuerzel (initials), titel, bereich (department), unterschrift (signature line). They belong to the person who owns the key or signed in. Changing merges the given details into the saved ones; only when the user asked. USE WHEN: a draft is missing a profile field, or the user asks to set their details. For one batch only, pass `profile` to talonic_doc_gen_draft / _generate instead. NOT FOR: per-document values (`values` on talonic_doc_gen_generate). ARGS: none to read; any of `name`, `kuerzel`, `tit…

Propose a template's field sheet from a data product: the platform reads the product's columns (and its reference table) and suggests a source for every field; suggestions stay unconfirmed. One template runs in the background: pass `wait_seconds` to wait for it (polls every 3 s). Without template_id, starts proposals for several templates (bulk; dry_run first). USE WHEN: a template is new, never proposed, or should be mapped to another product. Then read the sheet with talonic_doc_gen_templates and fix fields by key. NOT FOR: setting one field (talonic_doc_gen_update_template). ARGS: `data_pr…

Make a batch's missing PDFs again (documents whose Word file was made but the PDF conversion failed). USE WHEN: talonic_doc_gen_issues reports pdf_missing, or a batch's documents carry pdfError. NOT FOR: failed documents (fix the data or values and generate again). ARGS: `job_id`. RETURNS: the batch as talonic_doc_gen_jobs returns it.

Read the workspace's rules (named derivations a field with source { type: 'rule', rule } uses, e.g. a salutation from a gender column), or replace them all with `rules`. Replacing deletes every rule not in the new list: read first, change, send the whole list, and only when the user asked. USE WHEN: explaining a rule-sourced value, or setting up the workspace's rules. NOT FOR: one field's source (talonic_doc_gen_update_template). ARGS: none to read; `rules[] { name, description?, definition }` to replace. RETURNS: { data[] { name, description, definition } } (after a replace: the stored list)…

Document Generation at a glance: how many templates, field-sheet fields (confirmed, unconfirmed, entered per document), proposals running / failed / never run, and batches of the last 30 days with the latest one. USE WHEN: starting any Doc Gen work, or to report where things stand. NOT FOR: what to fix (talonic_doc_gen_issues); one template (talonic_doc_gen_templates). ARGS: none. RETURNS: { templates, fields { total, confirmed, unconfirmed, entered_per_document }, proposals { running, failed, never_proposed }, jobs { last_30_days, documents_last_30_days, failed_last_30_days, last } }.

List the Word templates, or read one template with its field sheet and proposal state. USE WHEN: finding a template, or before proposing, fixing or generating: the field sheet names every field's key, label, source ({ type: product|reference|extract|first|case|user|rule|today, ... }) and whether a person confirmed it. Fields whose source type is `case` are entered per document: the data does not hold them (e.g. the new owner), so pass them in `values` by field key (or case key). A value for any other field overrides the fill and is recorded as an edit in the document history. NOT FOR: changing…

Change a template's metadata (name, group, kind, companion template, version) and its fields by key: a field's label, source, confirmed flag or reason. Fields not named stay as they are; an unknown key is refused. Run with dry_run first to see the sheet as it would be. USE WHEN: fixing a field the proposal got wrong (e.g. pointing it at another column or making it entered per document with source { type: 'case', caseKey }), or pairing a letter with its agreement. Setting `confirmed: true` is a person's decision: only do it when the user asked (see talonic_doc_gen_confirm_fields). Red passages …

Upload a Word template (.docx or .dotx) to Document Generation. Its placeholders become the field sheet; propose it against a data product next. USE WHEN: the user gives a new letter or agreement template. NOT FOR: documents to read data from (talonic_request_upload / talonic_extract). ARGS: `filename` (with extension) and `content_base64` (the file bytes); in a local install `file_path` instead (the server reads the file). Optional `name`, `group`, `kind` letter|agreement, `version`. RETURNS: the new template with its fields.

Extract structured, schema-validated JSON from a document: PDF, scan, image, DOCX, email, or photo. Returns the requested fields with per-field confidence scores. USE WHEN: the user asks to extract data from a document, turn a PDF into JSON, pull fields from a file, or parse a scan / form / statement / receipt / report, for common (invoice, contract) or unusual document types. 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: de…

Report that the claimed decision task cannot be decided: raises a Human Review with your reason AND applies the app's declared fallback policy (rules decide, hold for review, or fail the run). USE WHEN: the package is insufficient or contradictory and no claimant could decide it. This ends the task (status 'failed'). NOT FOR: temporary give-backs (talonic_release_decision_task) or a decision you can make with low confidence (submit it with confidence set). ARGS: task_id, execution_epoch, reason (up to 2,000 characters). Stale epoch is HTTP 409. AUTH: a tlnc_ key needs a per-app 'decide' grant…

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 …

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`/`val…

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 …

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.

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

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.

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…

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 FO…

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

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?[] }, d…

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 docume…

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 talo…

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.

Read Talonic's agentic product funnel: WAEW (weekly active extracting workspaces — the North Star), time-to-first-extraction p50/p90 + 24h activation rate, W2/W4 creation-cohort retention, and acquisition by surface (claude_ai, cursor, raw_api, ...). USE WHEN: asked about WAEW, activation, retention, or which surfaces drive extractions. INTERNAL: Talonic-superadmin-only; other accounts are rejected by the platform. ARGS: range (optional: 7d | 30d | 90d, default 30d). RETURNS: { configured, rangeDays, waew, ttfe, retention[], bySurface[] } — configured:false means PostHog is unwired, not zero …

Read Talonic's website conversion funnels: Platform registration (Visit → Sign-up click → Account created → Activated) and Sales call booking (Visit → Book-demo click → Contact page → Demo booked). USE WHEN: asked about signups, activation counts, demo bookings, or website conversion. INTERNAL: Talonic-superadmin-only; other accounts are rejected by the platform. ARGS: range (optional: 7d | 30d | 90d, default 30d). RETURNS: { rangeDays, funnels[] } — each stage carries { count, pending }; pending:true means that stage's source is not wired yet, not zero.

Read anonymous visitor behavior on the free tools at talonic.com/tools: views, attempt/success/bounce rates, dwell, CTA clicks, per-tool leaderboard, and country/device/acquisition splits. USE WHEN: asked how the free tools perform, which tools convert, or where tool visitors come from. INTERNAL: Talonic-superadmin-only; other accounts are rejected by the platform. ARGS: all optional — range (today | 7d | 30d | 90d | all, default 30d), tool (slug), category, country (ISO code), device (desktop | mobile | tablet), source (utm/referrer key), funnel_stage (attempted | succeeded | downloaded | ct…

Read talonic.com traffic: visitors, pageviews, top pages, and referrers split into AI assistants (ChatGPT, Claude, Perplexity, ...) vs other domains. USE WHEN: asked about website traffic, top pages, or how many visitors AI assistants refer. INTERNAL: Talonic-superadmin-only; other accounts are rejected by the platform. ARGS: range (optional: 7d | 30d | 90d, default 30d). RETURNS: { configured, visitors, pageviews, topPages[], topReferrers[], aiReferrers[] }.

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.

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 …

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). READ-ONLY BY CONSTRUCTION: API-key credentials are restricted by the platform to the registry's read-only tools (capability `data.read`); write-capable registry tools are never invocable through this c…

List Agent-stage tasks visible to this Talonic workspace credential. USE WHEN: looking for external-agent work to process; begin with status 'available'. To take a batch of one pipeline (e.g. 'take 10 tasks of pipeline X'), list with pipeline_id and status 'available', then claim each with talonic_claim_agent_task; a task another agent took returns HTTP 409, so skip it and take the next. NOT FOR: reading the immutable task payload (use talonic_get_agent_task) or taking a lease (use talonic_claim_agent_task). ARGS: optional status, pipeline_id, limit, and cursor. RETURNS: metadata only plus pa…

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. Target API: https://talonic.com/docs/api (GET /v1/agent/tools). 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…

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 timi…

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`/`pro…

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

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-insensi…

Master data changes from the source systems' change logs, each checked against the evidence documents: a bank account change `matches` when a document for the party names the new account, `contradicts` when documents name another, `no_document` otherwise; flagged bank changes carry the party's open payables across every source as `exposure`. Read live; nothing is stored. USE WHEN: "which bank detail changes have no document behind them", vendor bank fraud checks, terms changes. NOT FOR: the golden records (talonic_master_records_overview). ARGS: `domain`, `flagged` (only the changes that need…

Read the Master Records configuration: per domain (vendors, customers, materials) the source systems (label, SQL connection, the read-only SELECT aliasing columns to the canonical fields; order is survivorship priority), the match thresholds, and the optional change logs, open items and evidence Spec. USE WHEN: before changing the configuration, or to explain which systems feed a domain. NOT FOR: the golden records (talonic_master_records_overview). ARGS: none. RETURNS: { domains { vendors|customers|materials { sources[], auto_threshold?, review_threshold?, changes[]?, open_items[]?, evidence…

The crosswalk: every source row (source, source id) mapped to its golden record key and name and the record's status, single-source rows included. USE WHEN: looking up which golden record a system's id belongs to, or handing the mapping to another system. NOT FOR: the merge reasons (talonic_master_records_get_record). ARGS: `domain`. RETURNS: { domain, rows[] { golden_key, golden_name, source, source_id, status } }.

Decide a golden record: `accept` keeps the merge, `split` breaks it into one record per source row, `reopen` removes an earlier decision. The domain is re-resolved at once and the decision survives every later run. USE WHEN: the user has reviewed a record and asks to accept or split it. NOT FOR: looking at the record (talonic_master_records_get_record). ARGS: `domain`, `key`, `decision` accept|split|reopen. RETURNS: { key, decision, stats } (stats of the re-run).

One golden record: each member row with its source and values, the golden value per field with the sources it came from, the fields where sources disagree (bank account and tax id are `bad`), the field-by-field reasons the rows were linked, status, score and any decision. USE WHEN: explaining why rows were merged, which system a value came from, or before accepting or splitting a record. NOT FOR: listing records (talonic_master_records_overview). ARGS: `domain`, `key` (from talonic_master_records_overview or talonic_master_records_crosswalk). RETURNS: { key, domain, name, members[] { source, …

A domain's latest run (stats per source, records, merged, to review, conflicts) and its golden records that join two or more source rows, review and bank / tax id conflicts first, each with status, match score, member sources and conflicting fields. USE WHEN: the headline ("how many duplicates across the ERPs, how many need review") or finding a record by name or source id. NOT FOR: one record's fields and reasons (talonic_master_records_get_record); single-source rows (talonic_master_records_crosswalk). ARGS: `domain`, `status` review|auto|accepted|split|conflict|all (default all), `query` (…

Resolve a domain now: read every configured source, match rows across systems, and replace the domain's golden records. Earlier accept / split decisions are kept. Deterministic; running it again on the same data gives the same records. USE WHEN: the sources changed, or the domain has never been resolved. NOT FOR: reading the result (talonic_master_records_overview). ARGS: `domain` vendors|customers|materials. RETURNS: { run_id, stats { source_rows, records, multi_source, auto_merged, to_review, conflicts, bad_conflicts, per_source, pairs_compared, resolve_ms } }.

Replace the Master Records configuration with a complete new one (validated by the platform: every SQL is checked read-only against its connection). Run with dry_run first. Saving needs an owner. USE WHEN: setting up Master Records for a workspace, or adding a source system or change log. NOT FOR: partial edits; read talonic_master_records_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.

Confirm suggested roles in bulk: by default only high-confidence suggestions (a verified quote the contract register agrees with), optionally only of named contracts or roles. Confirming says a person checked them; it is the user's decision, so only call this when the user asked. Run with dry_run first and say how many it would confirm. USE WHEN: the user asks to accept the suggestions (all, or of some contracts / roles). A read only makes suggestions and never overwrites a person's decision (a confirmed role stays, a rejected one never comes back). Confirming, rejecting and merging are a pers…

One contract's parties on a day: the computed view (partner, manager, tenant, previous and new owner, effective partner, addressee with its postal address lines, contacts, state), every role row with its party, state (suggested|confirmed|rejected), confidence and evidence (document quotes, reference table rows, a person's word), the issues, the cost unit (documents vs. contract register) and the read state. USE WHEN: checking or fixing a flagged contract; you need role ids (roles[].id) for talonic_parties_set_role, or to answer who the partner is and where a letter goes. Roles: partner (the co…

List the workspace's contracts with their parties today: effective partner, addressee and Verwalter by name, the parties' state (confirmed: every role counted is confirmed; suggested: any is a suggestion; none: no partner), open suggestions and the read state. USE WHEN: getting an overview, finding a contract by key, title or party name, or listing contracts still on suggestions (state: suggested) or without a partner (state: none). NOT FOR: one contract's roles and evidence (talonic_parties_contract); what needs fixing (talonic_parties_issues). ARGS: `query` (contract key, title, counterpart…

Read the workspace's own companies (the group: lead company, subsidiaries, sisters), or replace them all with `companies`. The read uses them to tell our side from the contract partner. Replacing deletes every company not in the new list: read first, change, send the whole list, and only when the user asked. USE WHEN: a read takes one of our own companies for the partner, or setting up the workspace. NOT FOR: contract partners (talonic_parties_party). ARGS: none to read; `companies[] { name, parent? (another name in the list), relation? subsidiary|sister|parent }` to replace. RETURNS: { data[…

The parties worklist: per contract what looks wrong today (no partner, several partners, the reference table names another partner, person-or-company unknown, no postal address, a Verwalter for a party no longer on the contract, a tenant entering the contract without a lease period, an owner change without a transfer date, cost unit disagreeing or missing, not read, read failed), plus parties that look like duplicates (same name, and postcode when both have one). USE WHEN: after talonic_parties_read, deciding what to fix; open each flagged contract with talonic_parties_contract. Duplicates are…

Add a contact person to a company or an owners' association (with their function), or remove a contact link. A contact is always a person; the company is a company or an owners' association. Adding the same person again updates the function. USE WHEN: the user names the person to write to at a company (e.g. the WEG's Verwalter contact), or a contact left. NOT FOR: a contact role on one contract (talonic_parties_set_role with role contact). ARGS: add: `party_id` (the company), `person_id`, `function` (e.g. 'Geschäftsführer'); remove: `member_id` (members[].id from talonic_parties_party) alone.…

Merge one party into another: every role and contact link moves to the survivor (`into`); a role the survivor already holds on the same contract keeps the survivor's row and takes the merged one's evidence. The merged party stays only as a pointer to the survivor. Cannot be undone; a person's decision, so only when the user asked. Run with dry_run first. USE WHEN: talonic_parties_issues lists duplicates (same name and postcode) and the user confirms they are the same party. NOT FOR: two different parties with similar names; moving one role to another party (talonic_parties_set_role with role_i…

Read, change or create one party. With `party_id` alone: the party with its roles on every contract, its contacts (members), the companies it is a contact of and the documents it appears in (with quotes). With `party_id` and fields: changes those fields (the rest stay). Without `party_id`: creates a party; `display_name` is required (kind and salutation are inferred from it when not given). USE WHEN: checking a party; fixing its name, kind (person or company decides a letter's wording), salutation or postal address (issues kind_unknown, address_missing); creating a party the documents miss bef…

Read the parties from contract documents: queues contracts for the platform to read in the background (one model call per contract) and store every party and role it finds as a suggestion, with quotes. By default every contract not read yet (only_unread); `contract_ids` reads exactly those again. With `status: true` only reports the queue. Pass `wait_seconds` to wait until the queue is empty (polls the queue every 5 s). USE WHEN: filling the app or after new contract documents arrived: run with dry_run first and say how many contracts it will read, then without dry_run and with wait_seconds; t…

Search the party register (people, companies, owners' associations): name, street, postcode, town, email or an external reference contains the query; each with how many contracts it holds a role on. USE WHEN: finding a party to add to a contract (its id for talonic_parties_set_role), checking whether a party already exists before creating one, or finding duplicates by name. NOT FOR: one party with its roles (talonic_parties_party); a contract's parties (talonic_parties_contract). ARGS: `query`, `kind` person|company|owners_association|unknown, `limit` (1-1000, default 200). RETURNS: { total, …

Add a role to a contract, or change one role row. With `contract_id`, `party_id` and `role`: adds the party in that role (confirmed unless `state` says suggested; a party already holding that role on the contract has that row updated). With `role_id`: changes that row: confirm or reject it (`state`), move it to another role or party, set the period, the Verwalter link or enters_contract. Any change by a person is a decision: an edited suggestion becomes confirmed unless `state` says otherwise. USE WHEN: fixing a contract's parties after reading talonic_parties_contract: a partner missing (no_p…

Contract Party Management at a glance: how many contracts, how many have confirmed parties, only suggestions, or no partner; active parties; open suggestions; and the parties-read queue. USE WHEN: starting any parties work, or to report where things stand. The loop: talonic_parties_status → talonic_parties_read (dry_run first, then with wait_seconds) → talonic_parties_issues → talonic_parties_contract per flagged contract → talonic_parties_set_role / talonic_parties_confirm → talonic_parties_merge duplicates → talonic_parties_issues again. NOT FOR: what to fix (talonic_parties_issues); one con…

Enter index values that have no free feed (EEX, THE levies, grid tariffs) for this workspace, each with its source. USE WHEN: a price needs an index talonic_price_baseline_refresh_indices cannot fetch. NOT FOR: public series with a feed (talonic_price_baseline_refresh_indices). ARGS: `values[]` { series, period (YYYY, YYYY-MM, YYYY-Qn, YYYY-Hn), value, unit?, base_year?, quote, source_url | document_id }. `quote` is the publisher's own line printing the value; a document-backed quote must verify in that document. RETURNS: { stored }. A value without a quote and a URL or document is rejected. …

Answer an open input of a contract workbook: enter a contract value with its verbatim quote, or record where the value will come from. USE WHEN: talonic_price_baseline_contract lists an open input whose options include enter_contract_value, from_invoice or request. NOT FOR: published index values (talonic_price_baseline_add_index_values); stand-in values (talonic_price_baseline_assume); editing formulas (talonic_price_baseline_update_model). ARGS: `model_id` (the open input's own `model_id`: the version that states the value), `action`: - enter_contract_value: `variable` (the input's `variabl…

Make, replace or withdraw an assumption: a marked stand-in for a value nobody has yet, for one contract or the whole workspace. USE WHEN: an open input offers `assume` and the real value cannot be had now (e.g. a levy not yet published, a quantity the customer has not sent). Use the input's `assume_target` as `target_kind` + `target`. NOT FOR: a value you can source: enter it (talonic_price_baseline_answer, talonic_price_baseline_add_index_values). Never assume a number you could read. ARGS: `action` (create | replace | withdraw), `assumption_id` (replace, withdraw). create/replace (full assu…

List the active assumptions: stand-in values used where no real value exists yet. USE WHEN: reviewing what the numbers rest on, or finding an assumption's id to replace or withdraw it. NOT FOR: making or changing one (talonic_price_baseline_assume). ARGS: `contract_key` (optional; the assumptions that apply to that contract, its own and the workspace's). Without it, every active assumption of the workspace. RETURNS: data[] { id, contract_key (null = workspace), target_kind, target, period_from, period_to, rule, value, unit, params { series, factor }, note, created_by }.

Check an invoice against a model: read the invoice's billed prices and quantities, recompute each price from the contract, and report the difference per line. USE WHEN: establishing Money Found for an invoice, or listing past checks (`list: true`). NOT FOR: prices without an invoice (talonic_price_baseline_prices). ARGS: `model_id`, `invoice_document_id` (invoice UUID, to run a new check) or `list: true` (past checks). RETURNS: { id, invoice, prices, comparison { lines[] { line, baseline_price, billed_price, unit, effect_eur, verdict, reason, independent }, totals { underbilled_eur, overbille…

One contract's workbook: what it should bill for a period, every open input as a question with the ways to answer it, and the assumptions its numbers rest on. USE WHEN: finding what is missing for a contract before answering it, or checking the expected invoice after an answer. NOT FOR: the Excel file (talonic_price_baseline_workbook); all contracts at once (talonic_price_baseline_register). ARGS: `model_id` (any version), one period: `year`, `comparison_id` (an invoice check) or `from`+`to` (YYYY-MM); default the newest invoice check, else the last full year. `include_grid` adds all cells. R…

Find contracts and invoices in the workspace to build a price baseline from. USE WHEN: picking the contract for talonic_price_baseline_extract or the invoice for talonic_price_baseline_compare. NOT FOR: general document search across all content (talonic_search). ARGS: `query` (filename contains, optional). RETURNS: data[] { id, filename, created_at }. Which contracts already have a model: talonic_price_baseline_models.

Read a contract's price clause into a standard price model: components (Arbeitspreis, Grundpreis, CO2, ...), their formulas, the named indices with base year and reference months, and every stated number with its verified contract quote. With `model_id` instead, read only the contract's identity (contract number, customer, site) and agreed quantities into that existing model, keeping its formulas and values. USE WHEN: a contract has no price model yet (`document_id`), or a model lacks its contract number or agreed quantities, e.g. the contract workbook asks for a quantity (`model_id`). Many co…

Queue contract documents for import: each one's price model is read in the background, and documents sharing a contract number become versions of one contract. USE WHEN: importing several contracts at once from talonic_price_baseline_imports candidates, or retrying failed imports (a failed document is queued again). NOT FOR: one contract you want to read now and inspect (talonic_price_baseline_extract). ARGS: `document_ids` (1–500 document UUIDs). RETURNS: { queued, skipped } (a document already queued or done is skipped). Each document costs one LLM call. Poll talonic_price_baseline_imports …

Contract documents in data capture that have no price model yet, grouped by contract number, or the state of the import queue. USE WHEN: bringing a workspace's contracts into Price Baseline: pick candidates, queue them with talonic_price_baseline_import, then poll `view: status`. NOT FOR: documents that already have a model (talonic_price_baseline_register); invoices (talonic_price_baseline_documents). ARGS: `view` (candidates, default | status), `query` (filename contains; candidates only). RETURNS: candidates data[] { contract_key, documents[] { document_id, filename, kind (contract | amend…

Show the index catalog (series the platform can fetch or accept manually), the sync state of the workspace's external series, or the stored values of given series. USE WHEN: a price period reports a missing index, to see which source a value came from, or to see which series are stale or failing (`view: sync`). NOT FOR: fetching new values (talonic_price_baseline_sync_series, talonic_price_baseline_refresh_indices) or entering them (talonic_price_baseline_add_index_values). ARGS: `series` (optional list of series keys, e.g. ['destatis.vpi', 'behg.co2']) for values; else `view` (catalog, defau…

List the workspace's price models, or read one in full when `model_id` is given. USE WHEN: finding a model id, or reviewing a model's components, formulas, indices and quotes before confirming it. NOT FOR: computed prices (talonic_price_baseline_prices); invoice checks (talonic_price_baseline_compare). ARGS: `model_id` (optional UUID). RETURNS: without id, data[] { id, document_id, contract_label, status, components, unverified_values, index_series, updated_at }; with id, the stored model with its full `model`.

Recompute every price of a model for each price period in a window, from the index values on file. USE WHEN: you need the contract's own price per period, independent of the biller's price sheet. NOT FOR: checking a specific invoice (talonic_price_baseline_compare); the Excel file (talonic_price_baseline_workbook). ARGS: `model_id`, `from`, `to` (YYYY-MM). RETURNS: prices[] { component, period { label, from, to }, price, unit, status, detail, indices[] { variable, series, months, value, sources, independent } } and the index values used. `status` other than ok (missing_index, missing_value, r…

Restate a checked invoice as the audit-proof invoice the contract supports: every line restated at the contract price, every input (base value, weight, index value, quantity) listed with its source (contract quote, publisher URL and line, the biller's invoice, or a marked assumption), and eight checks that say whether the restatement holds up without anyone's word for it. USE WHEN: an invoice was already checked (a comparison exists) and the user needs the corrected invoice to send, file or audit, or wants to know what still keeps it from being audit-proof. NOT FOR: running a new check or list…

Fetch index values from their publishers: BEHG CO2 price (§10 law text), Bundesbank VPI and Erzeugerpreise, Destatis GENESIS tables (needs the platform's GENESIS token). USE WHEN: talonic_price_baseline_prices reports a missing public index for a specific year range (backfill). NOT FOR: routine sync of every due series (talonic_price_baseline_sync_series); THE levies or grid tariffs, which have no free feed (talonic_price_baseline_add_index_values). ARGS: `series` (catalog keys), `from_year`, `to_year`. RETURNS: data[] { series, stored, error }. A failed series reports its error; it never suc…

The contract register: one row per contract (all its documents as versions), with the expected invoice for a year and what is still open. USE WHEN: seeing what every contract should bill for a year, which contracts still have open inputs, or finding a contract's `id` and `contract_key`. NOT FOR: one contract's open inputs in detail (talonic_price_baseline_contract); single model documents (talonic_price_baseline_models). ARGS: `year` (optional; default the last full calendar year). RETURNS: data[] { id (latest version's model id), contract_key, contract_number, customer, customer_number, site…

Sync external price data now (BEHG, Bundesbank, Destatis, EEX via Energy-Charts, DWD degree days), or change how often a series syncs. USE WHEN: talonic_price_baseline_indices `view: sync` shows a series as due, failed or stale, or a contract waits on a published value that should be out by now. NOT FOR: series with no feed, e.g. THE levies and grid tariffs (talonic_price_baseline_add_index_values); a backfill for a specific year range (talonic_price_baseline_refresh_indices). ARGS: sync: `keys` (series keys; omit to sync every shared series whose interval has passed). Schedule: `key` with `s…

Edit a price model after review: replace its model, confirm it, place it in a contract, or exclude it. USE WHEN: a formula, index or reference month was read wrong; the reviewer confirms the model; a document belongs to another contract (`contract_key`); a document of the contract sets no price, e.g. a withdrawn letter or cover mail (`status: excluded`). NOT FOR: first extraction (talonic_price_baseline_extract); entering one missing contract value (talonic_price_baseline_answer). ARGS: `model_id`, and at least one of `model` (the full model object from talonic_price_baseline_models, edited),…

Download the standard Excel workbook for a model: Variablen, Preise (live formulas), Indizes, Rechnungsprüfung, Hinweise, Quellen. Every contract comes out in the same layout. USE WHEN: the user wants the baseline as a spreadsheet, or to hand over an invoice check. NOT FOR: reading prices as data (talonic_price_baseline_prices). ARGS: `model_id`, `from`, `to` (YYYY-MM), `comparison_id` (optional, fills the Rechnungsprüfung sheet). RETURNS: the .xlsx as an embedded resource (base64) plus its filename and size.

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 limi…

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_m…

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 'co…

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 (tal…

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

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_mar…

What does not add up in one submission: totals that are not the sum of their rows, cumulative paid amounts that fall, and the target structure's identities (e.g. Total Incurred = Paid Loss + Paid LAE + Outstanding Loss). Each with the cell, the actual and the expected figure. USE WHEN: reviewing a submission's quality, or before quoting a figure that a finding concerns. NOT FOR: counts across submissions (talonic_submissions_list). ARGS: `document_id`, `spec_id` (optional; identities need it). RETURNS: [{ kind, severity, sheet, a1, embedded, expected, actual, parts[], check }].

One submission against a target structure: for every metric the client's format knows, how many facts the submission has and which fields they fill, plus metrics found that are not in the format. USE WHEN: judging whether a submission carries what a quote needs, or explaining what is missing. NOT FOR: the facts themselves (talonic_submissions_export). ARGS: `document_id`, `spec_id`. RETURNS: { metrics[] { metric, in_format, facts, fields[] } }.

Facts in the client's long format: a header (the structure's fields, then Metric, Figure, Document, Source) and one row per figure; Source is the cell the figure came from. Large: prefer one document. USE WHEN: handing facts to the client or another system, or answering a question about figures. NOT FOR: the inbox (talonic_submissions_list). ARGS: `spec_id`, `document_id` (optional; all submissions when omitted). RETURNS: { header[], rows[][] }.

One submission's figures, filtered: by metric, by year ('' = no period) and by field values (e.g. { "LoB Client": "Homeowners", "Category": "Cat" }). Each fact carries its fields and the source cell (sheet, A1, and the embedded file when it came from one), so every number can be cited. USE WHEN: answering a question about figures ("total incurred for accident year 2019", "paid loss by line of business"). Read talonic_submissions_matrix first to pick metric and year. Do not add up facts across lines of business or categories without checking for a Total row: a total and its parts are both facts…

The worklist: what needs a person, naming the submissions concerned. Kinds: not_captured, capture_failed, not_mapped, check_failed (with count), labels_to_review (with count), missing_metric (format metrics with no facts in a submission). USE WHEN: deciding what to do next; after talonic_submissions_process to see what is left. NOT FOR: the full list (talonic_submissions_list). ARGS: `spec_id` (optional; mapping-related kinds need it). RETURNS: [{ kind, document_id, filename, detail }].

The inbox: every submission workbook of the workspace with its cedent, status (not_captured, captured, mapped, failed), captured values, facts and metrics under a target structure, and failed / warned checks. USE WHEN: the headline ("which submissions are in, which are mapped, which have problems") or finding a submission by file name. NOT FOR: what to fix (talonic_submissions_issues); the facts (talonic_submissions_export). ARGS: `spec_id` (optional), `q` (file name contains), `limit` (default 100, max 500), `offset`. RETURNS: { total, submissions[] { document_id, filename, cedent, status, t…

Where one submission's figures are: facts per metric and year (accident, underwriting or reference period), every metric of the target structure included, grouped into families (premium, losses, exposure, cat, rates, other). Key '' counts facts with no period. USE WHEN: seeing what a submission covers before answering a question about it; finding which metric and year to read with talonic_submissions_facts. NOT FOR: the figures themselves (talonic_submissions_facts). ARGS: `document_id`, `spec_id`. RETURNS: { years[], rows[] { metric, family, in_format, facts, years { year: count } } }.

Capture new workbooks and map submissions into a target structure, in bulk. Capturing is deterministic (no model); mapping classifies only labels the workspace has not seen, and reuses every earlier and every human decision. Run with dry_run first. USE WHEN: new submissions arrived (only: not_captured), or a target structure changed and submissions need re-mapping (only: not_mapped or all). NOT FOR: reading results (talonic_submissions_list, talonic_submissions_issues). ARGS: `spec_id` (map into this structure), `document_ids` (restrict), `only` not_captured|not_mapped|all (default all), `rec…

The open questions the label review left for the client's experts, one per group, heaviest first. Without `group`: the questions with their options and the labels each settles. With `group` and `option`: record the expert's answer; every label of the group takes the mapping that answer means, and the submissions are re-mapped. USE WHEN: walking the client's experts through the few questions only they can answer, or recording their answers. NOT FOR: starting a review (talonic_submissions_review). ARGS: `spec_id`; to answer: `group` (from the list) and `option` (0-based index into its options).…

Agentic review of a target structure's label mappings (how each spreadsheet label maps onto the client's metrics and fields). Without `start`: the review's progress and the decisions stored (confirmed, corrected, best guesses, answered by experts, still proposed, open questions). With `start: true`: rule-made mappings are confirmed, the review agent decides the rest, the few only the client can answer become questions, and every mapped submission is re-mapped; runs in the background, poll without `start`. USE WHEN: labels are waiting for review (talonic_submissions_specs shows labels_to_review…

List the workspace's target structures: the client formats submissions are mapped into, with field count and how many label mappings still await review. USE WHEN: before any other submissions tool, to pick the spec_id. NOT FOR: the submissions themselves (talonic_submissions_list). ARGS: none. RETURNS: [{ id, name, updated_at, field_count, labels_to_review }].

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.

Submit the decision for a claimed decision task; the platform verifies it transactionally and resumes the run. USE WHEN: the decision is final. outcome must satisfy output_contract from the claim (plain JSON Schema, or the verdict_matrix / record_set envelope), evidence lists the package locators relied on (verbatim; [] only if the app allows unevidenced decisions), rationale is a short summary. Rejections are HTTP 422 with the reason and change nothing; the task stays claimed under your epoch, so fix and resubmit before the lease ends. NOT FOR: giving the task back undecided (talonic_release…

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 (…