Skip to main content
Glama
talonicdev

talonic-mcp

Official
by talonicdev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Filter Talonic Documents

talonic_filter
Read-only

Filter documents by extracted field values using conditions like equality, range, or substring matching. Retrieve sortable, paginated results for structured queries such as invoices over 1000 EUR.

Instructions

STATUS: stable. Field-name resolution is server-side. The is_not_empty operator is intentionally not exposed in v0.1; see workaround below.

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.

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.

NOT SUPPORTED IN v0.1:

  • is_not_empty: underreports against fields known to be populated. Removed from the supported operator list to keep filter results trustworthy. Workaround: filter with eq/gt/contains against a known value, or use is_empty then invert the result client-side. Tracked for a later release.

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
conditionsYesOne or more filter conditions, AND-ed together.
searchNoOptional free-text search applied alongside the filters.
sortNoOptional sort by a field.
pageNoPage number for pagination.
limitNoResults per page. Default 50 server-side.
source_connection_idNoOptionally scope to a specific source connection.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataYesDocuments matching the filter conditions, with their extracted field values.
totalNoTotal documents matching across all pages.
pageNoCurrent page number.
paginationNoCursor-based pagination metadata.

Tool Definition Quality

A4.9/5.0
Behavior5/5

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

Annotations provide readOnlyHint and openWorldHint. The description adds critical behavioral context: field-name resolution is server-side, operator details including is_not_empty absence with workaround, schema typing pitfalls (silent zero matches for numeric operators on string fields), and field discovery tips. No contradictions with annotations.

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 lengthy but well-structured with clear sections (STATUS, USE WHEN, DO NOT USE WHEN, OPERATORS, SCHEMA TYPING, NOT SUPPORTED, TIPS). Every section adds value for a complex tool. Could be slightly shorter, but the detail is justified.

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 parameters, nested conditions, output schema exists), the description is comprehensive. It covers typical use cases, edge cases (is_not_empty workaround), schema typing gotchas, field discovery, and pagination. Output schema exists, so return values are handled.

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?

Input schema covers all parameters (100% coverage). The description adds significant meaning: explains conditions structure, operator semantics, use of field vs field_id, the is_not_empty workaround, and tips for discovering filterable fields. It goes beyond what the schema alone provides.

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 it filters Talonic documents by extracted field values using composable conditions, with specific verb and resource. It distinguishes itself from sibling tools like talonic_search, talonic_get_document, etc., in the 'DO NOT USE WHEN' 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?

The description provides explicit 'USE WHEN' and 'DO NOT USE WHEN' sections, listing concrete scenarios (e.g., 'invoices over 1000 EUR') and naming alternative tools. This helps the agent decide when to invoke this tool.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/talonicdev/talonic-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server