Skip to main content

Find Field Reference

Available September 2026 and later.

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; the column_ref is returned
  • ambiguous — the name matches more than one column; the candidates are returned so the caller can choose
  • not_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 workbookFile is 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 running Tableau Studio instance. API reference
    • Writing the new snapshot file and its session companion file is a local filesystem write; no External Client API call.
  • 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 API call.
  • 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 API call.

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.

Reading live spends the self-heal

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.

note

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."
}
  • list-available-fields — lists the datasource fields available in the open workbook, the population this tool disambiguates against
  • add-field — places a field on a worksheet shelf once its exact reference is known