Find Field Reference
Disambiguates a field name to its exact column reference (column_ref) — the
Country-vs-Country1 class of problem where a human-readable name maps to more
than one underlying column. It matches the name against the fields in a local
Tableau Studio workbook snapshot; with workbookFile omitted it takes that
snapshot itself, reading the workbook open in the running Tableau Studio
instance. It reports one of three outcomes:
exact— the name resolves to a single column; thecolumn_refis returnedambiguous— the name matches more than one column; the candidates are returned so the caller can choosenot_found— no column matches the name
ambiguous and not_found are reported with isError: true in the result body
(the tool call itself still succeeds).
APIs called
Acts on the open Tableau Studio workbook via a local workbook snapshot file. The
name is always matched in-process. The tool reaches the local Tableau Studio
External Client API — a REST API the running Tableau Studio instance serves at
http://127.0.0.1:<port>/v<x> (authorized by a per-session loopback bearer token,
where <x> is the latest API version) — whenever it has to take a snapshot:
always when workbookFile is omitted, and once as a self-heal when a supplied
snapshot yields no match.
- Take a fresh snapshot when
workbookFileis omitted: read the open workbook, write it to a new local snapshot file, and match the name against that.GET /v<x>/workbook/document— read the current workbook document from the runningTableau Studioinstance. API reference- Writing the new snapshot file and its session companion file is a local
filesystem write; no
External Client APIcall.
- Resolve the field name against a supplied snapshot file. Reads the snapshot
file from the local filesystem and matches the name in-process; no
External Client APIcall. - Self-heal a supplied snapshot that yielded no match: re-read the live workbook
once, rewrite that same snapshot file, and retry the match. This is bounded to a
single refresh (no loop).
GET /v<x>/workbook/document— re-read the current workbook document. API reference- Rewriting the local snapshot file and its session companion file is a local
filesystem write; no
External Client APIcall.
Required arguments
query
The field name to resolve — the human-readable name the caller wants mapped to a
column_ref. String.
Example
{ "query": "Profit" }
Optional arguments
workbookFile
Absolute path to a local workbook snapshot file (the cached workbook XML) whose
fields are searched. String. This is a path an earlier call handed back — every
result carries the workbookFile it read — not a workbook or sheet name. A
supplied path must exist; a missing one is reported as a file-not-found error
rather than quietly falling back to a live read.
Omit it to read the workbook live
With workbookFile omitted — an empty or whitespace-only value counts as
omitted — the tool reads the workbook open in the running Tableau Studio
instance, writes that snapshot to a new cache file, and resolves against it.
The path it minted is returned as workbookFile, so a follow-up call can pass it
back and reuse the same snapshot instead of re-reading Tableau Studio.
The one-shot refresh described under session exists to rule out a stale
snapshot, so it applies only when you supply one. With workbookFile omitted the
XML being searched is already the live workbook, and a not_found is final: it
comes back with the "the field genuinely does not exist in the current workbook"
guidance rather than a second read.
Example
{ "workbookFile": "/Users/me/.tableau-mcp/cache/workbook-abc123.xml" }
datasource
Restricts resolution to a single datasource by name, so a name that appears in more than one datasource resolves within only the named one. String. When omitted, all datasources in the workbook are searched.
Example
{ "datasource": "Sample - Superstore" }
session
The Tableau Studio session id (for example, studio-1) identifying the running
instance to read from. String. When omitted, the session is resolved
automatically — the pinned instance, or the only one running — so a live read
still happens without naming one; it fails only when no instance is running or
when several are and none is pinned.
Self-heal on not_found
When a supplied workbookFile yields no match, the tool re-reads the live
workbook from the running Tableau Studio instance, rewrites that snapshot file,
and retries the match once. This covers a datasource or field that was connected
after the snapshot was written and is therefore invisible to a snapshot-only read.
The retry is bounded to one refresh, whether or not session was named.
A refresh failure never surfaces as a tool error. If the live read fails — or the
session cannot be resolved — the tool degrades to the original not_found
result, marks it stale_not_found with stale: true, and appends guidance (the
failure reason plus a suggested next step, such as checking the session) to the
result body, so the outcome is never dropped and a stale miss is never mistaken
for proof the field is absent.
Example results
Every result carries a status (resolved, ambiguous, not_found, or
stale_not_found) and the workbookFile the match was made against — the path
you passed, or the one the tool minted when you omitted it. isError is a legacy
mirror of status: it is true for anything other than resolved.
Exact match (kind: "exact")
{
"resolution": {
"kind": "exact",
"query": "Profit",
"column_ref": "[Sample - Superstore].[sum:Profit:qk]",
"datasource": "Sample - Superstore"
},
"status": "resolved",
"workbookFile": "/Users/me/.tableau-mcp/cache/workbook-abc123.xml",
"isError": false
}
Ambiguous match (kind: "ambiguous")
{
"resolution": {
"kind": "ambiguous",
"query": "Profit",
"candidates": [
{
"column_ref": "[DS1].[sum:Profit:qk]",
"datasource": "DS1",
"column_name": "[Profit]",
"role": "measure",
"is_aggregated": false
},
{
"column_ref": "[DS2].[sum:Profit:qk]",
"datasource": "DS2",
"column_name": "[Profit]",
"role": "measure",
"is_aggregated": false
}
],
"reason": "Multiple matches"
},
"status": "ambiguous",
"workbookFile": "/Users/me/.tableau-mcp/cache/workbook-abc123.xml",
"isError": true
}
No match (kind: "not_found")
The name did not resolve even after the workbook was read live, so note says so
plainly:
{
"resolution": {
"kind": "not_found",
"query": "NonExistent",
"candidates": [],
"reason": "No match"
},
"status": "not_found",
"workbookFile": "/Users/me/.tableau-mcp/cache/workbook-abc123.xml",
"isError": true,
"note": "Refreshed the workbook live from Tableau and \"NonExistent\" still does not resolve. The field genuinely does not exist in the CURRENT workbook — stop re-reading stale caches. Call list-available-fields (with session) to see the fields that DO exist, or ask-user to clarify."
}
Unrefreshable snapshot (status: "stale_not_found")
The supplied snapshot yielded no match and the live re-read failed, so the miss is reported as possibly stale rather than as an error:
{
"resolution": {
"kind": "not_found",
"query": "Profit",
"candidates": [],
"reason": "No match"
},
"status": "stale_not_found",
"workbookFile": "/Users/me/.tableau-mcp/cache/workbook-abc123.xml",
"isError": true,
"stale": true,
"note": "Attempted a live refresh from Tableau to rule out a stale cache, but it failed."
}
Related
list-available-fields— lists the datasource fields available in the open workbook, the population this tool disambiguates againstadd-field— places a field on a worksheet shelf once its exact reference is known