Match Template
Builds a chart from a plain-language ask by matching it to a reusable authoring template. The tool reads the workbook open in Tableau Studio, resolves the fields named in the ask itself, and matches the ask to a fast-path template — then either returns the bound template arguments for you to apply, or (with auto_apply) applies the finished chart to the live workbook in one step. It works in up to two calls: a first call with just the ask, and — when no template matches deterministically — a second call carrying a chosen proposal.
Each call reports one outcome in its status field:
bound— the ask matched a template and every slot is filled; the response carries the bound arguments (and, whenauto_applysucceeded, an applied receipt).propose— no deterministic match; the response lists candidate templates and the fields to bind, for you to choose one and call again with aproposal.escalate— no fast-path template fits the ask/data; the response routes you to direct authoring (for examplebuild-and-apply-worksheet).blocked— this MCP server refused a repeated or unchanged retry for the same ask (see Notes and caveats).
This tool is not read-only and not idempotent. With auto_apply: true it writes the bound chart to the live workbook, and any calcs are authored into the workbook before the bind — both mutate the open document. A completed apply re-run is a real re-mutation, not a no-op.
APIs called
This tool acts on the workbook open in the local Tableau Studio instance, communicating with Tableau Studio directly rather than calling the Tableau Cloud or Server REST API. Under the hood these are calls to 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>, where <x> is the latest API version. These loopback calls carry no OAuth scopes; each is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface. A workbook must be open in the target session. Matching the ask to a template and building the workbook XML happen in-process; only the reads and writes below cross to Tableau Studio.
- Reads the open workbook once so the tool can resolve fields and match a template. Also done every time, before any bind.
GET /v<x>/workbook/document— read the current workbook XML. API reference
- Matches the ask to a template and binds each slot to a resolved field — done in-process against the read workbook XML and the bundled template library (not an API call). The
propose/escalate/blockedoutcomes are all resolved here without further calls. - Authors pre-bind calculations into the workbook (only when
calcsis supplied): the edited workbook is applied, then re-read to confirm the new fields landed.POST /v<x>/workbook/document(Content-Type: application/xml) — apply the workbook with the authored calculations. API referenceGET /v<x>/workbook/document— re-read to confirm the calculations were applied. API reference
- Checks whether the user changed the workbook after it was read, before an
auto_applywrite (the apply is whole-document last-writer-wins, so a concurrent edit would be silently reverted). This change-event gate has no External Client API endpoint — it is not an API call and is skipped on transports without event support. - Applies the bound chart to the live workbook (only when
auto_apply: true, the result isbound, and the matched template is fast-path eligible): the template is injected and any sort/top-N is spliced into the workbook XML, the whole document is validated in-process (not an API call), then posted back. On any inject/validation/apply failure the tool falls back gracefully — the bound arguments are returned intact so no bind is lost.POST /v<x>/workbook/document(Content-Type: application/xml) — apply the updated workbook XML. API reference
- Navigates to the newly applied sheet (best-effort follow-up after a successful apply; a failure here never changes the applied result).
POST /v<x>/workbook:goToSheet— focus the newly applied sheet. API referenceGET /v<x>/workbook/document— re-read to verify the sheet took focus. API reference
Required arguments
ask
The ask: a plain-language description of the chart to build, for example "bar chart of Sales by Region". The tool resolves the fields named in the ask against the open workbook and matches the ask to a fast-path template. This is the only always-required argument; a proposal is added only on the second call after a propose outcome.
Example
{ "ask": "bar chart of Sales by Region" }
Optional arguments
session
The Tableau Studio session to target (Desktop PID). Omit when the session is pinned or exactly one Tableau Studio instance is connected — it is resolved automatically. When two or more are connected the tool fails closed and lists the running instances rather than guessing; a value that is not a running instance is rejected.
Example
"studio-1"
proposal
The second-call payload that selects one template and binds every slot to a field, used after a propose outcome returned candidate templates. Its nested fields mirror the returned proposal schema verbatim (snake_case inside bindings), so a propose payload round-trips unchanged:
template— the chosen template name.title— the sheet title. Maximum 80 characters; control characters are rejected.bindings— an array of{ slot_id, field }(plus an optionalderivationoverride), one per bound slot, using exact field names.confidence— the match confidence.Range: 0-1.sort— optional{ by, direction }wheredirectionis"asc"or"desc".top_n— optional positive integer to keep only the top N members.
Example
{
"proposal": {
"template": "bar-basic",
"title": "Sales by Region",
"bindings": [
{ "slot_id": "cat", "field": "Region" },
{ "slot_id": "val", "field": "Sales" }
],
"confidence": 0.9
}
}
confidence must be present in a proposal. The matcher skips its low-confidence floor when confidence is undefined, so omitting it would bypass the escalation entirely — the schema rejects a proposal without it.
minConfidence
The minimum confidence floor for accepting a match. Range: 0-1.
Example
0.8
auto_apply
Boolean (schema description: "Apply now."). When true and the ask binds to a fast-path-eligible template, the bound chart is applied to the live workbook in one step and the response is a trimmed applied receipt (applied: true, sheet_name, phase_ms). When false or omitted, the tool returns the bound arguments and guidance without mutating the workbook.
Example
true
Applies only fast-path-eligible binds
auto_apply applies only a bound result whose matched template is fast-path eligible. A propose, escalate, or blocked outcome — or a bound result on a template that is not fast-path eligible — is returned unapplied even when auto_apply: true.
Refuses to overwrite concurrent edits
The apply is a whole-document write. If the user changes the workbook between the read and the apply, the tool refuses to apply, keeps the bound arguments intact, and directs you to re-run so it reads the current workbook. It does not offer to re-apply the returned arguments in this case, because they were computed against the pre-edit workbook and would revert the user's changes.
Graceful fallback on apply failure
If injecting the template, in-process validation, or the apply write fails, the response is applied: false with an apply_error and the bound args still present, so you can fall back to build-and-apply-worksheet (or the inject/apply template chain) using the returned arguments.
requireCompleteRequest
Prove full ask or decline, no writes
skip_validation
When true, the call requests that in-process validation of the bound document be skipped before apply (available September 2026 and later). The server honors this only when it has been configured to allow skipped validation; otherwise the flag is ignored and validation still runs. Omit it (or pass false) to keep the normal validation path.
Do not use this to work around a bind that fails validation — fix the mapping instead.
Example
true
keep_large_pie
User-confirmed big pie (available November 2026 and later). Set true only when resubmitting the same ask and the same pie proposal the tool already blocked because the pie has more slices than the workable maximum of 12, and only after the user explicitly says they want that pie. Keep the same datasource and target_worksheet. The confirmation applies only to that blocked proposal.
Example
true
target_worksheet
An existing worksheet to replace in place, given as its id or its name; omit to create a new sheet (available September 2026 and later for matching by id). Validated before the bind runs, for both apply modes: the value must resolve to an existing worksheet, and it must not be a sheet that belongs to a dashboard. An unknown name or id, or a dashboard-member sheet, is refused with a precise reason rather than silently creating a stray copy.
Example
"Sales by Region"
Checked against the open workbook before the bind runs. The name in the message is the sheet's name when the value matches a worksheet, and the value you passed when it does not.
target_worksheet "${}" not found in the workbook — check get-sheets, or omit target_worksheet to create a new sheettarget_worksheet "<name>" is a dashboard member sheet — replacing it in place could corrupt the dashboard; omit target_worksheet to create a new sheet
datasource
Internal datasource name or unique caption to use as the calc source when authoring pre-bind calculations.
Example
"Sample - Superstore"
datasource is resolved before any calculation is authored. A follow-up for the same ask must keep the datasource already retained, including a confirmed large-pie resubmit. When calcs is set and datasource is omitted, the calculation authoring chooses the target and refuses if it cannot.
datasource "<name>" not found or ambiguous in the workbook; use an internal datasource name or unique captiondatasource must match the retained bind-template datasource "<name>"Multiple datasources found; specify datasource. Candidates: <names>.—calcsis set,datasourceis omitted, and more than one datasource other thanParametersexists. The message lists up to five namesNo non-Parameters datasource found.—calcsis set and the workbook has no datasource other thanParametersDatasource "<name>" was not found. Candidates: <names>.andDatasource caption "<caption>" is ambiguous. Use an internal datasource name: <names>.— the calculation-authoring helper's wording when it is given a name directly. This tool resolvesdatasourcefirst and uses thenot found or ambiguousmessage above
calcs
Calculated fields to author into the workbook before the bind (schema description: "Author fields."), so the ask can reference them. Each entry is:
caption— the field caption to create.formula— the calculation formula.datatype— optional field data type.role— optional field role.
Invalid calculations (for example an empty formula) are rejected before any document load or bind. Authored calc captions are echoed back in authored_calcs.
Example
{
"calcs": [
{ "caption": "Margin", "formula": "[Sales] * 0.2" }
]
}
Each calculation is checked before the workbook is changed. A message for a calculation that has a caption is prefixed with calc "<caption>": . An empty caption is prefixed with calc "#<n>": , where <n> is the 1-based position in calcs. An existing field with the same caption, formula, role, and datatype is reused.
caption emptyformula emptyinvalid role—roleis notmeasureordimensioninvalid datatype—datatypeis notreal,integer,string,boolean,date, ordatetimecaption collision — pick a new caption or use the existing field— a field with that caption already exists and does not match this calculationfield reference [<name>] was not foundorfield reference [<name>] is ambiguous— an unbracketed name in the formula does not resolve to one field. When the workbook has candidates, the message continues with<one of: ...>and lists up to three namesfield reference [<name>] is ambiguous between parameters: <names>— the name matches more than one parameter
Notes and caveats
proposeandescalateare normal outcomes, not errors. They report that the tool needs a chosen proposal or that no fast-path template fits — the response'sguidancenames the next step. Only a genuine failure (for example a failed workbook read) is returned as an error.- Repeated retries for the same ask are blocked by this MCP server. To prevent blind retry thrash, this MCP server's in-process guard tracks bind attempts per ask and returns a
blockedoutcome for a repeated proposal-absent call, an unchanged proposal, an exhausted single-retry budget, or an ask already determined not recoverable in the fast path. This guard lives on the MCP server, not in Tableau Studio; to proceed, change the proposal meaningfully based on the reported blockers, or take the fallback authoring path the guidance names. - A reused sheet that still needs calculations cannot be a dashboard member. When
target_worksheetis omitted and the ask matches a sheet already applied, a dashboard member that still has calculations waiting to be authored is refused:deterministic worksheet "<title>" is a dashboard member sheet with pending calculations — missing calculations prevent safe reuse, and the dashboard member cannot be rebuilt in place. - Summary rows after apply. The summary read is called with the applied sheet's title and without a column list. A failure from that read is returned on
summary_rows_error. The helper's blank-worksheet message and its requested-column messages are not used on this call.
Example results
Bound, not applied (auto_apply omitted)
{
"status": "bound",
"used_llm": false,
"apply_hint": "worksheet-path",
"apply_instruction": "Create a sheet, substitute the fragment, then apply-worksheet.",
"args": {
"template_name": "bar-basic",
"title": "Sales by Region",
"sheet_type": "worksheet",
"template_parameters": { "DATASOURCE": "Superstore" },
"field_mapping": { "cat": "[Region]", "val": "[Sales]" }
},
"guidance": "Create a sheet, substitute the fragment, then apply-worksheet."
}
Bound and applied (auto_apply: true)
{
"status": "bound",
"applied": true,
"sheet_name": "Sales by Region",
"phase_ms": { "bind": 42, "inject": 7, "apply": 118 },
"guidance": "Applied \"Sales by Region\" to the live workbook (bind 42ms, inject 7ms, apply 118ms). Done — no further tool calls needed."
}
Propose (no deterministic match)
{
"status": "propose",
"decline_reason": {
"code": "no_llm_classifier_declined",
"detail": "classifyNoLlm returned no deterministic template; routed to proposal candidates"
},
"output_schema": { "type": "object" },
"guidance": "No deterministic (no-LLM) match. Choose exactly one template from llm_input.candidate_templates, bind every bindable slot to a field from llm_input.fields (match role/kind; use the exact field name), then call bind-template again with { session, ask, proposal } matching output_schema."
}
Escalate (field not found)
{
"status": "escalate",
"reason": "field-not-found",
"blockers": [
{ "code": "field-not-found", "slot_id": "val", "detail": "No field named \"Revenue\"." }
],
"guidance": "Escalated (field-not-found). No worksheet was produced. Blockers: [field-not-found] slot 'val' No field named \"Revenue\".. Next: Resolve the field(s) with the resolve-field tool, then call bind-template again with a corrected proposal; otherwise ask the user with ask-user (present the candidates)."
}
Blocked (unchanged retry)
{
"status": "blocked",
"reason": "unchanged_proposal",
"guidance": "Blocked: this proposal is semantically unchanged from the failed bind attempt. Title/confidence only changes do not count; change a binding, derivation, sort, or top_n based on evidence, otherwise ask-user or use build-and-apply-worksheet."
}
Related
resolve-field— resolve an ambiguous or not-found field before re-proposing.add-field— place a field on a worksheet in the manual authoring path.apply-worksheet— apply an edited worksheet in the fallback authoring path.refine-worksheet— apply a bounded sort/top-N refinement to an existing worksheet.