talonic_filter
ChatGPTSTATUS: stable. Field-name resolution is server-side. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both value and value_to. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. - is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing. SCHEMA TYPING: - Numeric operators (gt, gte, lt, lte, between) only resolve correctly when the schema field is typed as number. A field typed as string that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. - Preventive check: call talonic_search first and inspect fieldMatches[].dataType / fields[].dataType on the field you intend to filter. If dataType !== 'number', do NOT use a numeric operator on it — either pick a different field, switch to a string-friendly operator (eq, contains), or warn the user that the schema field needs a data_type change before the filter can succeed. - Reactive fallback: if the filter response contains a warnings array, surface its message (and suggestion, if present) to the user verbatim — these explain why a query returned zero or unexpected results and typically suggest a schema-design change. Do not silently retry without flagging the warning. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as field here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both field (name) and field_id (UUID) reach the API as fieldId. Either is fine.
talonic_filter
ChatGPTSTATUS: stable. Field-name resolution is server-side. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both value and value_to. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. - is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing. SCHEMA TYPING: - Numeric operators (gt, gte, lt, lte, between) only resolve correctly when the schema field is typed as number. A field typed as string that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. - Preventive check: call talonic_search first and inspect fieldMatches[].dataType / fields[].dataType on the field you intend to filter. If dataType !== 'number', do NOT use a numeric operator on it — either pick a different field, switch to a string-friendly operator (eq, contains), or warn the user that the schema field needs a data_type change before the filter can succeed. - Reactive fallback: if the filter response contains a warnings array, surface its message (and suggestion, if present) to the user verbatim — these explain why a query returned zero or unexpected results and typically suggest a schema-design change. Do not silently retry without flagging the warning. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as field here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both field (name) and field_id (UUID) reach the API as fieldId. Either is fine.
talonic_filter
ChatGPTSTATUS: stable. Field-name resolution is server-side. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both value and value_to. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. - is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing. SCHEMA TYPING: - Numeric operators (gt, gte, lt, lte, between) only resolve correctly when the schema field is typed as number. A field typed as string that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. - Preventive check: call talonic_search first and inspect fieldMatches[].dataType / fields[].dataType on the field you intend to filter. If dataType !== 'number', do NOT use a numeric operator on it — either pick a different field, switch to a string-friendly operator (eq, contains), or warn the user that the schema field needs a data_type change before the filter can succeed. - Reactive fallback: if the filter response contains a warnings array, surface its message (and suggestion, if present) to the user verbatim — these explain why a query returned zero or unexpected results and typically suggest a schema-design change. Do not silently retry without flagging the warning. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as field here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both field (name) and field_id (UUID) reach the API as fieldId. Either is fine.
talonic_get_balance
ChatGPTSTATUS: stable. Read the user's current Talonic credit balance, EUR value, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp. Use this to make budget- aware decisions before kicking off large batches or re-extractions. USE WHEN: - The user asks how many credits or how much budget they have left. - You are about to run a large or expensive operation (batch extract, re-extract many documents) and want to confirm budget headroom first. - The user asks how long their balance will last at the current rate. DO NOT USE WHEN: - The user just wants the per-call cost of a single extraction (that is already on the talonic_extract response under cost). - The user wants to top up credits (route them to the dashboard; auto top-up is guarded by a separate scope). RESPONSE SHAPE: - balance_credits: current credit balance. - balance_eur: current balance in EUR (rounded to two decimals). - burn_rate_30d_credits: total credits consumed in the trailing 30 days. - projected_runway_days: days of runway at the current 30-day average burn. -1 indicates no consumption in the trailing window (cannot compute runway). - tier: API tier of the workspace (free, pro, enterprise, etc.). - tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.
talonic_get_balance
ChatGPTSTATUS: stable. Read the user's current Talonic credit balance, EUR value, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp. Use this to make budget- aware decisions before kicking off large batches or re-extractions. USE WHEN: - The user asks how many credits or how much budget they have left. - You are about to run a large or expensive operation (batch extract, re-extract many documents) and want to confirm budget headroom first. - The user asks how long their balance will last at the current rate. DO NOT USE WHEN: - The user just wants the per-call cost of a single extraction (that is already on the talonic_extract response under cost). - The user wants to top up credits (route them to the dashboard; auto top-up is guarded by a separate scope). RESPONSE SHAPE: - balance_credits: current credit balance. - balance_eur: current balance in EUR (rounded to two decimals). - burn_rate_30d_credits: total credits consumed in the trailing 30 days. - projected_runway_days: days of runway at the current 30-day average burn. -1 indicates no consumption in the trailing window (cannot compute runway). - tier: API tier of the workspace (free, pro, enterprise, etc.). - tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.
talonic_get_balance
ChatGPTSTATUS: stable. Read the user's current Talonic credit balance, EUR value, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp. Use this to make budget- aware decisions before kicking off large batches or re-extractions. USE WHEN: - The user asks how many credits or how much budget they have left. - You are about to run a large or expensive operation (batch extract, re-extract many documents) and want to confirm budget headroom first. - The user asks how long their balance will last at the current rate. DO NOT USE WHEN: - The user just wants the per-call cost of a single extraction (that is already on the talonic_extract response under cost). - The user wants to top up credits (route them to the dashboard; auto top-up is guarded by a separate scope). RESPONSE SHAPE: - balance_credits: current credit balance. - balance_eur: current balance in EUR (rounded to two decimals). - burn_rate_30d_credits: total credits consumed in the trailing 30 days. - projected_runway_days: days of runway at the current 30-day average burn. -1 indicates no consumption in the trailing window (cannot compute runway). - tier: API tier of the workspace (free, pro, enterprise, etc.). - tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.
talonic_get_document
ChatGPTSTATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - You called talonic_request_upload and need to poll until the user has uploaded the file. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document). STATUS VALUES on the response status field: - pending_upload: document slot reserved via talonic_request_upload, file not yet received. Keep polling (~5 s interval). Token expires after 15 min — if status stays 'pending_upload' past the expires_at returned by talonic_request_upload, the user did not upload in time. - queued / extracting: file received, OCR and exhaustive extraction in progress. Keep polling. - completed: extraction is done. This is the state to wait for before calling talonic_extract with a schema or schema_id — the schema-specific LLM pass runs off the cached OCR'd text. - uploaded: file received but the extraction queue could not be enqueued (rare, e.g. Redis unavailable). The talonic_extract endpoint will trigger processing inline if called. - error / ocr_failed / extraction_failed: terminal failures; processing_log carries the reason.
talonic_get_document
ChatGPTSTATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - You called talonic_request_upload and need to poll until the user has uploaded the file. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document). STATUS VALUES on the response status field: - pending_upload: document slot reserved via talonic_request_upload, file not yet received. Keep polling (~5 s interval). Token expires after 15 min — if status stays 'pending_upload' past the expires_at returned by talonic_request_upload, the user did not upload in time. - queued / extracting: file received, OCR and exhaustive extraction in progress. Keep polling. - completed: extraction is done. This is the state to wait for before calling talonic_extract with a schema or schema_id — the schema-specific LLM pass runs off the cached OCR'd text. - uploaded: file received but the extraction queue could not be enqueued (rare, e.g. Redis unavailable). The talonic_extract endpoint will trigger processing inline if called. - error / ocr_failed / extraction_failed: terminal failures; processing_log carries the reason.
talonic_get_document
ChatGPTSTATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - You called talonic_request_upload and need to poll until the user has uploaded the file. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document). STATUS VALUES on the response status field: - pending_upload: document slot reserved via talonic_request_upload, file not yet received. Keep polling (~5 s interval). Token expires after 15 min — if status stays 'pending_upload' past the expires_at returned by talonic_request_upload, the user did not upload in time. - queued / extracting: file received, OCR and exhaustive extraction in progress. Keep polling. - completed: extraction is done. This is the state to wait for before calling talonic_extract with a schema or schema_id — the schema-specific LLM pass runs off the cached OCR'd text. - uploaded: file received but the extraction queue could not be enqueued (rare, e.g. Redis unavailable). The talonic_extract endpoint will trigger processing inline if called. - error / ocr_failed / extraction_failed: terminal failures; processing_log carries the reason.
talonic_list_schemas
ChatGPTSTATUS: stable. List all saved schemas in the user's Talonic workspace. Returns a COMPACT SUMMARY of each schema: id (UUID), short_id (SCH-XXXXXXXX), name, description, version, and field_count. Either id form is accepted by talonic_extract's schema_id parameter, so you can extract with a saved schema straight from this list. The full JSON Schema definition for each field is intentionally NOT included here — for many schemas that payload is large and gets truncated by some clients. To inspect a schema's full field definitions, read the talonic://schemas resource. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as schema_id.
talonic_list_schemas
ChatGPTSTATUS: stable. List all saved schemas in the user's Talonic workspace. Returns a COMPACT SUMMARY of each schema: id (UUID), short_id (SCH-XXXXXXXX), name, description, version, and field_count. Either id form is accepted by talonic_extract's schema_id parameter, so you can extract with a saved schema straight from this list. The full JSON Schema definition for each field is intentionally NOT included here — for many schemas that payload is large and gets truncated by some clients. To inspect a schema's full field definitions, read the talonic://schemas resource. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as schema_id.
talonic_list_schemas
ChatGPTSTATUS: stable. List all saved schemas in the user's Talonic workspace. Returns a COMPACT SUMMARY of each schema: id (UUID), short_id (SCH-XXXXXXXX), name, description, version, and field_count. Either id form is accepted by talonic_extract's schema_id parameter, so you can extract with a saved schema straight from this list. The full JSON Schema definition for each field is intentionally NOT included here — for many schemas that payload is large and gets truncated by some clients. To inspect a schema's full field definitions, read the talonic://schemas resource. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as schema_id.
talonic_request_upload
ChatGPTSTATUS: stable. Request a file upload link for the user. Use this when the user wants to extract a file but you cannot deliver it directly (e.g., the file is too large for tool-call arguments, or you're running in a sandboxed environment like Claude.ai). Returns an upload URL the user can open in their browser to drop the file, plus a document_id to track the upload. After showing the URL to the user, poll with talonic_get_document until status is 'completed' (the file has been uploaded, OCR'd, and is ready for schema-specific extraction). Then call talonic_extract with the document_id and a schema or schema_id. IMPORTANT: a user message like 'uploaded', 'done', or 'I dropped it' only confirms the browser-side upload finished. It is NOT a signal that server-side processing is complete. The document still needs OCR and exhaustive extraction (typically 10-30 s after the browser upload). You MUST poll talonic_get_document yourself until status is 'completed' regardless of what the user says. Calling talonic_extract before status is 'completed' may return errors. USE WHEN: - The user has a file to extract but you cannot send it via tool-call arguments (e.g., file is larger than ~32KB, or the environment blocks outbound data). - You are running in a hosted/sandboxed environment (Claude.ai, ChatGPT) where file_data cannot be used reliably. - The user explicitly asks for an upload link. DO NOT USE WHEN: - You can deliver the file directly via file_data (local-stdio installs with small files). - The file is already accessible via a public URL (use file_url on talonic_extract instead). - The document is already in the workspace (use document_id on talonic_extract instead).
talonic_request_upload
ChatGPTSTATUS: stable. Request a file upload link for the user. Use this when the user wants to extract a file but you cannot deliver it directly (e.g., the file is too large for tool-call arguments, or you're running in a sandboxed environment like Claude.ai). Returns an upload URL the user can open in their browser to drop the file, plus a document_id to track the upload. After showing the URL to the user, poll with talonic_get_document until status is 'completed' (the file has been uploaded, OCR'd, and is ready for schema-specific extraction). Then call talonic_extract with the document_id and a schema or schema_id. IMPORTANT: a user message like 'uploaded', 'done', or 'I dropped it' only confirms the browser-side upload finished. It is NOT a signal that server-side processing is complete. The document still needs OCR and exhaustive extraction (typically 10-30 s after the browser upload). You MUST poll talonic_get_document yourself until status is 'completed' regardless of what the user says. Calling talonic_extract before status is 'completed' may return errors. USE WHEN: - The user has a file to extract but you cannot send it via tool-call arguments (e.g., file is larger than ~32KB, or the environment blocks outbound data). - You are running in a hosted/sandboxed environment (Claude.ai, ChatGPT) where file_data cannot be used reliably. - The user explicitly asks for an upload link. DO NOT USE WHEN: - You can deliver the file directly via file_data (local-stdio installs with small files). - The file is already accessible via a public URL (use file_url on talonic_extract instead). - The document is already in the workspace (use document_id on talonic_extract instead).
talonic_request_upload
ChatGPTSTATUS: stable. Request a file upload link for the user. Use this when the user wants to extract a file but you cannot deliver it directly (e.g., the file is too large for tool-call arguments, or you're running in a sandboxed environment like Claude.ai). Returns an upload URL the user can open in their browser to drop the file, plus a document_id to track the upload. After showing the URL to the user, poll with talonic_get_document until status is 'completed' (the file has been uploaded, OCR'd, and is ready for schema-specific extraction). Then call talonic_extract with the document_id and a schema or schema_id. IMPORTANT: a user message like 'uploaded', 'done', or 'I dropped it' only confirms the browser-side upload finished. It is NOT a signal that server-side processing is complete. The document still needs OCR and exhaustive extraction (typically 10-30 s after the browser upload). You MUST poll talonic_get_document yourself until status is 'completed' regardless of what the user says. Calling talonic_extract before status is 'completed' may return errors. USE WHEN: - The user has a file to extract but you cannot send it via tool-call arguments (e.g., file is larger than ~32KB, or the environment blocks outbound data). - You are running in a hosted/sandboxed environment (Claude.ai, ChatGPT) where file_data cannot be used reliably. - The user explicitly asks for an upload link. DO NOT USE WHEN: - You can deliver the file directly via file_data (local-stdio installs with small files). - The file is already accessible via a public URL (use file_url on talonic_extract instead). - The document is already in the workspace (use document_id on talonic_extract instead).
talonic_save_schema
ChatGPTSTATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
talonic_save_schema
ChatGPTSTATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
talonic_save_schema
ChatGPTSTATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
talonic_search
ChatGPTSTATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a filterable boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.
talonic_search
ChatGPTSTATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a filterable boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.
talonic_search
ChatGPTSTATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a filterable boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.
talonic_to_markdown
ChatGPTSTATUS: stable. Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown. USE WHEN: - The user wants the full text content of a document for summarisation, translation, or analysis. - A previous tool call returned a document_id and you want to inspect its content. - The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise). - The user has a raw PDF / scan / image and wants markdown directly without designing a schema first. DO NOT USE WHEN: - The user wants specific structured fields (use talonic_extract with a schema). INPUTS (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path): - document_id: id of an already-ingested document. Cheapest path, one API call. - file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit. - file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead. - file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.
talonic_to_markdown
ChatGPTSTATUS: stable. Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown. USE WHEN: - The user wants the full text content of a document for summarisation, translation, or analysis. - A previous tool call returned a document_id and you want to inspect its content. - The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise). - The user has a raw PDF / scan / image and wants markdown directly without designing a schema first. DO NOT USE WHEN: - The user wants specific structured fields (use talonic_extract with a schema). INPUTS (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path): - document_id: id of an already-ingested document. Cheapest path, one API call. - file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit. - file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead. - file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.
talonic_to_markdown
ChatGPTSTATUS: stable. Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown. USE WHEN: - The user wants the full text content of a document for summarisation, translation, or analysis. - A previous tool call returned a document_id and you want to inspect its content. - The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise). - The user has a raw PDF / scan / image and wants markdown directly without designing a schema first. DO NOT USE WHEN: - The user wants specific structured fields (use talonic_extract with a schema). INPUTS (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path): - document_id: id of an already-ingested document. Cheapest path, one API call. - file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit. - file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead. - file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.
