Skip to main content
Glama
talonicdev

talonic-mcp

Official
by talonicdev
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

Read a field's values across documents

talonic_field_values
Read-onlyIdempotent

Retrieve every value captured for a field across documents, with provenance evidence—source text, document, and confidence—to analyze or aggregate one concept.

Instructions

Read a field's CURRENT VALUES across documents, with provenance — one row per bound occurrence: document id + filename + type, the value, confidence, the raw name it was captured under, the verbatim source text, and the resolution band that bound it.

USE WHEN: the user asks 'what are all the X across my documents', you need to tabulate or aggregate one concept across the corpus, or you want the evidence (source text + document) behind a value. NOT FOR: multi-field row-shaped queries over documents (talonic_filter) or one document's full field set (talonic_get_document).

ARGS: exactly one of field_id or name; optional document_id (one document), value (case-insensitive contains filter), limit (max 100), cursor. RETURNS: { field_id, canonical_name, concept_ids, data[] of { occurrence_id, document_id, document_filename, value, confidence, provenance{ raw_field_name, source_text, resolved_by, needs_confirmation, via_redirect }, links }, pagination }. Rows are Sources-IAM filtered for the caller.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoField NAME instead of an id — resolved through canonical name, synonyms, merge aliases and the registry's spelling fold, then followed to the live concept. Use the user's wording ('Invoice No', 'Vertragsnummer').
limitNoPage size (default 20, max 100).
valueNoCase-insensitive contains filter on the value text.
cursorNoOpaque cursor from pagination.next_cursor.
field_idNoField UUID (from talonic_list_fields / talonic_search).
document_idNoOnly occurrences on this document.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.76

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly and idempotent hints, so this is known to be safe. The description goes well beyond that by disclosing the one-row-per-bound-occurrence model, the provenance structure, the Sources-IAM filtering, and the 'exactly one of field_id or name' constraint. It also exposes the pagination limit and current-value semantics, which are not visible from annotations alone.

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

Conciseness5/5

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

The description is well-structured with labeled sections: a purpose sentence, USE WHEN, NOT FOR, ARGS, and RETURNS. Every sentence carries actionable information, and the most important scoping information is front-loaded. Despite its length, there is no redundancy or filler.

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?

The description is self-sufficient even though there is no output schema. It enumerates the full response shape including pagination and provenance, states the IAM filtering behavior, and covers parameter constraints. Combined with the sibling differentiation and use-case guidance, an agent has everything needed to call this tool correctly.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds the crucial constraint that exactly one of field_id or name must be provided, and clarifies that document_id restricts to a single document. It does not need to restate the schema's already-rich parameter descriptions, and the additional constraint meaningfully improves invocation correctness.

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 opens with a specific verb and resource, 'Read a field's CURRENT VALUES across documents, with provenance', and defines the row granularity precisely. It also distinguishes itself from siblings by explicitly naming what it is NOT for: talonic_filter and talonic_get_document, so an agent can disambiguate immediately.

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 an explicit USE WHEN section with concrete triggers ('what are all the X across my documents', tabulating/aggregating a concept, wanting evidence behind a value) and a NOT FOR section naming the exact alternative tools. This is exemplary routing guidance that leaves no ambiguity.

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

Deploy Server

Other Tools