talonic_get_field
Get the concept card for one field: what it means (curated description and extraction instruction), its synonyms and merge aliases, maturity, where it occurs (document and 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). Accepts a field name in the user's own words — it is resolved through canonical name, synonyms, merge aliases and the registry's spelling fold, then followed to the live concept.
When to use
- You must decide whether a field is the right concept for a question.
- You need example values or the value shape before writing a filter or a query.
- The user names a field ('Invoice No', 'Vertragsnummer') and you need the live concept behind it.
When not to use
- To list many fields — use
talonic_list_fields. - To read every value of a field — use
talonic_field_values.
Parameters
| Parameter | Type | Description |
|---|---|---|
| field_id | string | Field UUID. Provide either `field_id` or `name`. |
| name | string | Field name to resolve (canonical → synonyms → aliases → spelling fold, redirects followed). |
| include_history | boolean | Append the curation trail (tier changes, merges, renames), newest first. |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| definition | object | `description`, `instruction`, `synonyms[]`, `aliases[]`. |
| identity | object | `pinned`, `source`, `superseded_by`, `absorbed[]`. |
| occurrence | object | `occurrence_count`, `document_count`, `first_seen_at`, `last_seen_at`, `document_type_distribution`. |
| values | object | `total`, `distinct_count`, `top[]` (value, count, share), `examples[]`. |
| usage | object | `schema_count`, `schema_field_count`. |
| resolution | object | Present when `name` was given: `matched_by` and `redirected_from[]`. |
| history | object | Present when `include_history` is true. |
Tool input
{ "name": "Invoice No", "include_history": true }Tool response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"canonical_name": "invoice_number",
"maturity": "proven",
"data_type": "string",
"definition": { "description": "The supplier's invoice identifier", "instruction": "Extract the invoice number as printed", "synonyms": ["inv_no"], "aliases": [{ "name": "invoice no", "source": "merge" }] },
"identity": { "pinned": false, "source": null, "superseded_by": null, "absorbed": [] },
"occurrence": { "occurrence_count": 412, "document_count": 398, "first_seen_at": "2026-03-02T09:14:00.000Z", "last_seen_at": "2026-09-04T16:02:11.000Z", "document_type_distribution": { "invoice": 398 } },
"values": { "total": 412, "distinct_count": 405, "top": [{ "value": "INV-2026-0001", "count": 2, "share": 0.0049 }], "examples": ["INV-2026-0001", "RE-88231"] },
"usage": { "schema_count": 2, "schema_field_count": 2 },
"resolution": { "matched_by": "synonym", "redirected_from": [] },
"history": { "total": 1, "data": [{ "kind": "tier_changed", "at": "2026-04-01T00:00:00.000Z", "detail": { "direction": "promoted", "from_maturity": "candidate", "to_maturity": "proven" } }] }
}Frequently asked questions
Can I pass the user's wording instead of an id?+
Yes. `name` is resolved through the canonical name, synonyms, merge aliases and the registry's spelling fold, then followed to the live concept; the response's `resolution.matched_by` says which arm matched.