talonic-mcp

Official

by talonicdev

Overview Schema Source Related Servers Discussions(1)Admin

TypeScript

Remote

Filter Talonic Documents

talonic_filter

Read-only

Find documents by extracted field values using composable conditions (e.g., 'total > 1000') for numeric, date, text, or presence checks.

Instructions

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

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

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number for pagination.
`sort`	No	Optional sort by a field.
`limit`	No	Results per page. Default 50 server-side.
`search`	No	Optional free-text search applied alongside the filters.
`conditions`	Yes	One or more filter conditions, AND-ed together.
`source_connection_id`	No	Optionally scope to a specific source connection.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Documents matching the filter conditions, with their extracted field values.
`page`	No	Current page number.
`total`	No	Total documents matching across all pages.
`warnings`	No	API warnings surfaced by the Talonic filter endpoint. Most commonly raised when a numeric operator is applied to a string-typed field, in which case the warning explains the lexicographic-comparison trap and suggests a schema-design change. Agents should surface these to the user rather than silently retrying.
`pagination`	No	Cursor-based pagination metadata.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.1.66Jun 12, 2026

changedInput schema / properties / conditions / items / properties / field / description

Previous value: -"Canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type'). The Talonic API resolves names to ids server-side. Mutually exclusive with `field_id`."New value: +"Canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type'). Provide EXACTLY ONE of `field` or `field_id` per condition — not both, not neither. The Talonic API resolves names to ids server-side."

changedInput schema / properties / conditions / items / properties / field_id / description

Previous value: -"Talonic field UUID. Mutually exclusive with `field`."New value: +"Talonic field UUID. Provide EXACTLY ONE of `field` or `field_id` per condition — not both, not neither."

addedInput schema / properties / conditions / items / properties / value / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  }
+]

changedInput schema / properties / conditions / items / properties / value / description

Previous value: -"Value to compare against."New value: +"Comparison value, typed to match the field (number for numeric fields, string for text and ISO 'YYYY-MM-DD' dates, boolean for flags). REQUIRED for every operator EXCEPT `is_empty` / `is_not_empty` (which take no value). For `between`, this is the lower bound — pair it with `value_to`."

addedInput schema / properties / conditions / items / properties / value_to / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  }
+]

changedInput schema / properties / conditions / items / properties / value_to / description

Previous value: -"Upper bound for `between` operator; ignored otherwise."New value: +"Upper bound. REQUIRED only for the `between` operator (paired with `value`); same type as `value`. Omit for all other operators."

Changed2 schema fields changedv0.1.38May 18, 2026

changedInput schema / properties / conditions / items / properties / operator / enum

Previous value: -[
-  "eq",
-  "neq",
-  "gt",
-  "gte",
-  "lt",
-  "lte",
-  "between",
-  "contains",
-  "is_empty"
-]New value: +[
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "contains",
+  "is_empty",
+  "is_not_empty"
+]

addedOutput schema / properties / warnings

Added value: +{
+  "description": "API warnings surfaced by the Talonic filter endpoint. Most commonly raised when a numeric operator is applied to a string-typed field, in which case the warning explains the lexicographic-comparison trap and suggests a schema-design change. Agents should surface these to the user rather than silently retrying.",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "code": {
+        "description": "Machine-readable warning code.",
+        "type": "string"
+      },
+      "field": {
+        "description": "Canonical name of the field this warning applies to.",
+        "type": "string"
+      },
+      "field_id": {
+        "description": "UUID of the field this warning applies to.",
+        "type": "string"
+      },
+      "message": {
+        "description": "Human-readable warning message.",
+        "type": "string"
+      },
+      "suggestion": {
+        "description": "Suggested mitigation, e.g. a recommended `data_type` change to make the query resolve correctly.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

Changed1 schema field changedv0.1.25May 7, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "description": "Documents matching the filter conditions, with their extracted field values.",
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "document_id": {
+            "type": "string"
+          },
+          "fields": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "filename": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "page": {
+      "description": "Current page number.",
+      "type": "number"
+    },
+    "pagination": {
+      "additionalProperties": false,
+      "description": "Cursor-based pagination metadata.",
+      "properties": {
+        "has_more": {
+          "type": "boolean"
+        },
+        "limit": {
+          "type": "number"
+        },
+        "next_cursor": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "total": {
+      "description": "Total documents matching across all pages.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.1.16May 6, 2026

changedInput schema / properties / conditions / items / properties / operator / enum

Previous value: -[
-  "eq",
-  "neq",
-  "gt",
-  "gte",
-  "lt",
-  "lte",
-  "between",
-  "contains",
-  "is_empty",
-  "is_not_empty"
-]New value: +[
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "contains",
+  "is_empty"
+]

First observedApr 30, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations give readOnlyHint and destructiveHint. Description adds: conditions are AND-ed, operator-specific behaviors (is_empty takes no value), numeric guard (check dataType first), text field name resolution with warnings, and instruction to surface warnings. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (USE WHEN, NOT FOR, ARGS, TEXT FILTERS, NUMERIC GUARD, RETURNS) and front-loaded. It's somewhat long but each sentence adds value, appropriate for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 params, nested objects, many operators) and existence of output schema, the description covers all critical aspects: purpose, usage, parameter details, edge cases, warnings, return structure. Nothing missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds deep semantics: explains field/field_id exclusivity, operator list, value/value_to for between, data types, and text filter resolution. This goes well beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Find documents by their extracted field VALUES using composable conditions' and gives an example. It distinguishes from siblings talonic_search and talonic_get_document in the 'NOT FOR' section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'USE WHEN: value-based criteria on extracted fields' and 'NOT FOR: free-text / concept search (use talonic_search); a single document by id (use talonic_get_document).' Also provides guidance on numeric guard and warning handling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.