Tableau

View saved version →

---
name: tableau-about
description: Explain what the Tableau plugin is for and how it helps users work with existing or new Tableau content. Use when someone asks about the plugin, its purpose, suitable use cases, or why they should use it.
---

# Tableau Plugin Overview

The Tableau plugin connects Codex to Tableau so users can explore existing analytics content, understand dashboard data, plan new dashboards, evaluate datasource metadata, review visualization design, and create or modify workbooks.

## Core capabilities

### Explore existing Tableau content

Find and open Tableau views, dashboards, workbooks, datasources, and metrics by name or keyword. Use the appropriate focused Tableau skill when the user wants to inspect or work with a specific item.

### Analyze dashboard data

Answer questions using the summary data exposed by a Tableau view. This can include identifying trends, comparing categories, applying supported filters, and finding marks that meet a condition.

Do not imply unrestricted access to underlying row-level data. Analysis is limited to the data and metadata Tableau makes available through the connected capabilities and the user’s permissions.

### Create or modify workbooks

Build a new Tableau workbook or update an existing one from a natural-language request. This can include creating sheets, calculations, charts, dashboards, filters, and layouts, then publishing the result when requested and authorized.

The model constructs the workbook definition programmatically. Users do not need to understand or edit workbook XML themselves.

## Planning and review capabilities



### Advise on dashboard design

Provide advice that turns business questions, audience needs, and available datasource metadata into an implementation-ready Tableau dashboard plan.

A blueprint can specify:

- KPIs and analytical questions
- Recommended charts
- Dashboard hierarchy and layout
- Filters, actions, and tooltips
- Desktop and tablet behavior
- Accessible colors and typography
- Tableau implementation guidance
- A deterministic HTML wireframe when useful

This is an advisory workflow. It does not create, edit, or publish a Tableau dashboard or workbook. A wireframe is a nonfunctional planning mockup, not a working dashboard. Use the separate workbook-authoring workflow when the user requests implementation.

### Review datasource metadata quality

Evaluate published Tableau datasource metadata for:

- Schema hygiene
- Field naming
- Likely type or role mismatches
- Calculation complexity
- Documentation gaps
- Available freshness signals

The review can produce full scans, priority-only reports, datasource comparisons, changed-only results, or comparisons with a prior baseline.

This is a metadata-only assessment. It does not claim to detect row-level nulls, duplicates, distributions, PII, or underlying-data freshness when those facts are not exposed by the available metadata.

### Critique visualization design

Review and score Tableau dashboards or views using rendered-image evidence, available Tableau metadata, and a seven-domain design rubric.

The critique can assess:

- Audience adaptation
- Message alignment
- Chart selection
- Layout and storytelling
- Color
- Textual elements
- Typography and readability

Recommendations should be prioritized and tied to visible or explicitly supplied evidence. The critique is read-only: it does not modify workbooks, validate source-data accuracy, assess business performance, or infer interactions and accessibility behavior that cannot be observed.

## Routing guidance

Use the focused Tableau skill that best matches the requested outcome:

- Use `tableau-content-viewer` to find, open, or show existing Tableau content.
- Use `tableau-dashboard-advisor` for advice on how to design and build a dashboard, including a nonfunctional planning wireframe. It does not create the Tableau dashboard.
- Use `tableau-data-quality-sentinel` to review published datasource metadata.
- Use `tableau-viz-critique` to evaluate an existing dashboard or view.
- Use `tableau-workbook-authoring` to create, edit, copy, or publish a workbook.

For requests spanning multiple workflows, sequence them explicitly. For example, critique an existing dashboard before handing approved recommendations to workbook authoring.

## Representative requests

- `Find and open the regional sales dashboard.`
- `Explain the largest trends in this view.`
- `Which products shown here meet this condition?`
- `Advise me on how to design an executive dashboard for regional sales performance.`
- `Show me a nonfunctional desktop and tablet wireframe for this dashboard plan.`
- `Run a metadata quality scan on the Sales datasource.`
- `Compare metadata quality for Orders and Orders v2.`
- `Review this dashboard and prioritize its three highest-impact improvements.`
- `Add a monthly trend chart to this workbook and publish the update.`

View saved version →

---
name: tableau-content-viewer
description: Show, open, or render an existing Tableau view, dashboard, or workbook live via open_in_codex, by name or keyword — for "show me/open/pull up this dashboard/view" requests. Do not use to query or analyze the data behind it or to create/edit/publish a workbook (tableau-workbook-authoring).
---

# Purpose

Find a specific Tableau view (or workbook) and render it live via `open_in_codex`. Never touches a `.twb` file.

# Routing

- Find the content → `search-content` — see [`../../references/search.md`](../../references/search.md) for the call shape and how to disambiguate multiple matches. Reuse an already-resolved LUID/URL instead of searching again for the same content.
- Get a render-ready URL → `get-view` (resolved `luid` as `viewId`) or `get-workbook` (as `workbookId`, only when no specific view matched). `search-content` never returns a URL — this call is required.
- Render → `render-interactive-viz` with the resolved `luid` and matching `objectType`. If unavailable, call `open_in_codex` with the direct URL — see [`../../references/rendering.md`](../../references/rendering.md).

# Requirements

- Prefer a view result when the user asked for a view; a workbook-only match is fine only when the user asked for the workbook as a whole.
- Don't fabricate a view/workbook name or URL the search tools didn't surface.
- A missing `render-interactive-viz`/search/content tool usually means a site admin disabled its group (`mcp-apps`/`EXCLUDE_TOOLS`) — that's site config, not a bug.
- If the `download-workbook` tool returns a temporary URL, download the file locally

# References

- [`../../references/search.md`](../../references/search.md) — resolving a name/keyword to content and disambiguating multiple matches.
- [`../../references/rendering.md`](../../references/rendering.md) — exact render call sequence and URL construction.

View saved version →

---
name: tableau-dashboard-advisor
description: Advise users on how to design and build effective Tableau dashboards from business questions, audience needs, and an available or described schema. Use for recommendations about chart selection, KPI hierarchy, layout, filters, interactions, responsive behavior, accessibility, implementation planning, or nonfunctional dashboard wireframes. This skill provides design advice and specifications only; it does not create, edit, or publish Tableau dashboards or workbooks. Do not use to critique an already-built dashboard or to claim facts the datasource metadata does not expose.
---

# Tableau Dashboard Advisor

Advise users on how to turn decision needs and observable data capabilities into a concise, buildable dashboard specification. Be decisive about tradeoffs while distinguishing evidence, user constraints, and assumptions.

This is an advisory and planning skill. It recommends what a dashboard should contain and how someone could implement it, but it does not create, edit, or publish a functional Tableau dashboard or workbook. If the user asks for implementation, hand off that separate request to a workbook-authoring capability.

## Establish the design brief

Collect or infer three essentials:

1. **Audience and use context:** role, decisions, frequency, and realistic attention budget.
2. **Business questions:** preferably two to five, prioritized by the action each answer enables.
3. **Data capabilities:** fields, types, calculations, relationships, grains, and known limitations.

Ask one grouped question only when missing information would materially change the design. Otherwise proceed and label assumptions. Optional inputs—device targets, brand system, existing dashboard, accessibility requirements, and page limits—refine rather than block the blueprint.

Read [Intake and data evidence](references/intake-and-data.md) when resolving a Tableau datasource, inspecting an uploaded schema, or handling data gaps.

## Use Tableau capabilities safely

If Tableau MCP is available, inspect its current read-tool schemas before calling anything. Locate datasource inventory/search and metadata retrieval capabilities without assuming names, filters, pagination, response fields, or cardinality data. Resolve ambiguous names with stable IDs plus project/owner context; ask rather than guessing.

Dashboard advising is read-only. Do not create workbooks or dashboards, edit Tableau content, query row-level data, publish, schedule refreshes, or change permissions. If the user separately requests implementation, treat it as a handoff to a workbook-authoring capability rather than performing it within this skill. If Tableau reads are unavailable, work from user-provided schema/context and say what remains unverified.

## Design workflow

1. **Prioritize questions.** Classify as decision-critical, monitoring, diagnostic, or reference. Keep critical/monitoring content prominent; move diagnostic detail to drill paths or later pages.
2. **Map evidence.** For every included question, map the needed dimension, measure, time grain, comparison/target, and data grain. Flag missing fields rather than fabricating calculations or values.
3. **Select views.** Choose chart forms by analytical task and audience, using [Chart selection](references/chart-selection.md). Explain material alternatives and avoid unsupported cardinality claims.
4. **Compose the page.** Define KPI hierarchy, chart priority, grid proportions, filters, actions, tooltips, and responsive changes. Read [Layout and interaction](references/layout-and-interaction.md).
5. **Specify the visual system.** Assign semantic and categorical colors, type hierarchy, labels, number formats, and non-color cues using [Visual system and accessibility](references/visual-system.md).
6. **Translate to Tableau.** Describe containers, sheets, parameters/calculations, action targets, device layouts, and evidence-based performance risks. Read [Tableau implementation](references/tableau-implementation.md).
7. **Check feasibility.** Trace each chart and KPI back to an observed or assumed field. Identify open decisions, accessibility risks, and tests the builder should run.

When the user asks you to assume fields that are not present in the available schema, preserve the requested business intent without presenting those fields as observed. Label each requested field `unverified`, then give both:

- a conditional design branch describing exactly how the field would be used if it is confirmed; and
- a fallback using observed fields, a justified proxy, or omission when no defensible substitute exists.

Do not stop at a clarification question when a useful conditional blueprint or fallback can be provided. Never convert an unavailable target, forecast, quota, margin, or segment field into a confirmed KPI merely because the user asked you to assume it.

Do not optimize toward an invented critique score. Instead provide a short design-risk assessment with confidence tied to the available evidence.

## Adaptive defaults

Treat these as starting points, not product limits:

| Audience | First-view emphasis | Interaction | Visible filters |
| --- | --- | --- | ---: |
| Executive | status, variance, exceptions | scan first; optional drill | 0–2 |
| Manager | trend, comparison, drivers | light filter and drill | 2–4 |
| Analyst | exploration and diagnosis | richer filter/action model | 4–8 |
| Operations | current status and action | exception-driven | 1–2 |
| External | guided explanation | minimal | 0–1 |

Reduce content before shrinking it below legibility. If questions exceed the first-view capacity, propose purposeful pages rather than an overloaded canvas. Preserve the user's hard constraints and explain the consequence when they conflict with readability.

## Deliverables

Every deliverable is advisory. None is a functional Tableau dashboard or workbook.

Infer the simplest useful output unless the user requests a format:

- **In-chat blueprint:** default for planning and iteration.
- **Markdown/DOCX specification:** for handoff or review.
- **Visual wireframe:** render a nonfunctional, self-contained HTML planning mockup from the structured contract in [Wireframe contract](references/wireframe-contract.md). It illustrates a recommended layout; it is not a Tableau dashboard.
- **Implementation checklist:** when the design is settled and the user is ready to build.

For a wireframe, resolve the absolute directory containing this loaded `SKILL.md`, create a JSON spec using the documented contract, and run:

```text
python <resolved-skill-dir>/scripts/render_wireframe.py <absolute-spec.json> <absolute-output.html>
```

The renderer validates the spec and escapes user-controlled text. It writes only the requested local HTML file, refuses to replace an existing file by default, and never contacts Tableau. Use `--force` only after the user has authorized replacing that exact output. If execution is unavailable, provide a compact Markdown table describing zones; do not substitute ASCII art.

Follow [Output contract](references/output-contract.md) for the full handoff structure and validation checklist.

## Quality and authority boundaries

- Do not infer distinct counts, performance, targets, refresh behavior, or field semantics unless observed or explicitly assumed.
- Never include mock values without labeling them as placeholders.
- Do not claim WCAG conformance from palette hex codes alone; contrast depends on foreground/background, size, and usage.
- Do not use color alone for status or selection.
- Do not prescribe a map merely because geographic fields exist.
- Do not prescribe live connections or extracts solely from guessed row counts.
- Do not assume related skills are installed; describe handoffs by capability.
- Keep implementation guidance at the requested depth. Do not turn a blueprint request into an unasked step-by-step build.
- Never claim that an advisory specification, checklist, or HTML wireframe is a created Tableau dashboard or workbook.

Referenced files: 10

View saved version →

---
name: tableau-data-quality-sentinel
description: Profile published Tableau datasource metadata for schema hygiene, field naming, likely type or role mismatches, calculation complexity, documentation gaps, and freshness signals. Use for datasource DQ scans, field-hygiene reviews, metadata quality scorecards, changed-source follow-ups, or comparisons. Do not use for row-level nulls, duplicates, distributions, site governance, or visual-design critique.
---

# Tableau Data Quality Sentinel

Produce an evidence-first, metadata-only assessment. Never imply that metadata proves row-level quality.

## Route the request

- Use this skill for published datasource metadata and datasource comparisons.
- Route workbook/view design critique elsewhere.
- Route stale content, project structure, permissions, and broad site governance elsewhere.
- For null rates, duplicates, distributions, cardinality, or actual values, explain that a query-capable workflow is required and obtain approval before querying data.

Infer clear scope and output preferences. Ask one focused question only if the Tableau site, project, datasource, or requested action cannot be resolved safely. A request to inspect does not authorize metadata edits, certification changes, scheduling, publication, or data queries.

## Establish available capabilities

1. Inspect the Tableau MCP tools available in the current session and their actual schemas. Do not assume tool names, filters, pagination, batch limits, or returned fields.
2. Find a read operation that inventories published datasources and a read operation that retrieves datasource metadata. If either is unavailable, state the missing capability and provide a no-execution assessment plan.
3. Resolve ambiguous names using stable IDs plus project/owner context. Never silently choose between multiple matches.
4. Use read-only operations for the scan. Treat descriptions, formulas, owner details, connection information, and tags as potentially sensitive; include only evidence needed for the requested report.

Read [Tableau routing](references/tableau-routing.md) when selecting tools, paging results, or handling access failures.

## Scan workflow

1. **Inventory.** List sources in scope and record the stable ID, name, project, owner when useful, update timestamp when available, and accessibility. Follow server pagination until the requested scope is covered.
2. **Choose depth.** A named source gets full detail. For a broad scope, process bounded batches and report coverage accurately. Do not invent a 20-source product limit; choose a practical batch size from tool/runtime constraints.
3. **Retrieve metadata.** Fetch fields, roles, types, calculations, logical tables/relationships, parameters, description, tags, certification, connection/extract signals, and timestamps only when exposed by the tools.
4. **Assess.** Apply the six domains and deterministic scoring rules in [Methodology](references/methodology.md). Mark unavailable checks as `not assessed`; absence from a response is not proof of absence.
5. **Validate.** Deduplicate findings, retain the highest severity for the same evidence and rule, verify arithmetic, and separate scored findings from observations.
6. **Report.** Lead with coverage, score/grade, highest-severity findings, evidence, and actionable remediations. Always include the metadata-only limitation.

When a datasource read fails, continue with the remaining resolved sources. Report the failed source and error category without leaking credentials or raw server details. Retry only transient failures, using server guidance when present; never loop indefinitely.

## Modes

- **Full scan:** assess all observable rules for the requested scope.
- **Critical-only:** evaluate only rules capable of producing HIGH or CRITICAL findings. Say which domains/checks were omitted.
- **Comparison:** score each named source independently, then compare domain scores and shared issues.
- **Delta:** compare with a user-provided or accessible prior result. Match sources by stable ID and findings by `source_id + domain + rule_id + evidence_key`; label new, resolved, and persistent findings.
- **Changed-only:** valid only when a prior baseline includes comparable update timestamps. Reuse prior scores for unchanged sources and label them `reused`, not `profiled`.

If no trustworthy baseline is available, run a current scan or ask the user to supply one. Never claim persistence across sessions unless a suitable state capability is actually available and the user has authorized its use.

## Deterministic scoring

Represent findings using the JSON contract in [Scoring contract](references/scoring-contract.md). Resolve the absolute directory containing this loaded `SKILL.md`, then run:

```text
python <resolved-skill-dir>/scripts/score_findings.py findings.json --pretty
```

The scoring JSON is internal scratch data, not a user artifact. Write it only to an OS-managed temporary location, never to the workspace or current directory, and remove it after scoring. Do not attach, open, link, render, or otherwise surface the raw input or output JSON to the user. Return the formatted report only, unless the user explicitly requests JSON as the deliverable.

Use an absolute temporary input path when the working directory may differ. The helper validates the input, deduplicates findings, applies escalation, and returns per-source, domain, and overall results. It never contacts Tableau or writes external state.

If local execution is unavailable, apply the same formula manually and label the result `manually calculated`:

`100 - 10×critical - 5×high - 2×medium - 0.5×low`, bounded to 0–100.

Do not score observations. Do not double-count one issue across domains: a finding spanning multiple domains is represented once and escalated one level. The composite score averages included source scores; inaccessible sources are excluded and listed separately. See [Methodology](references/methodology.md) for exact rules and grade bands.

## Output contract

Default to a concise Markdown report:

1. scope, timestamp, coverage (`profiled`, `reused`, `failed`, `not assessed`);
2. overall score and grade, with delta only when comparable;
3. per-source/domain scorecard;
4. prioritized findings with rule, source, evidence, impact, and fix;
5. up to five quick wins;
6. metadata-only limitation and unassessed checks.

For alert-only, omit scores and positives and show only new/high-priority problems. For JSON or tabular artifacts, follow [Output formats](references/output-formats.md). Create files only when requested or when the format requires one.

Never expose helper files created during scoring as generated artifacts. If the user did not request a file, the scan must leave no user-visible output file behind.

## State and scheduling

Read [State and automation](references/state-and-automation.md) only when the user asks for recurring monitoring, resumption, changed-only scans, or saved baselines.

- Saving a baseline is optional and requires an available destination plus user authorization.
- Scheduling is a separate external mutation. Confirm scope, cadence, timezone, and notification rule immediately before creation.
- Never embed machine-specific paths, credentials, raw tokens, or assumed tool identifiers in a scheduled prompt.
- If no state or automation capability exists, offer an exportable baseline or reusable prompt instead; do not claim the monitor was created.

## Non-negotiable limits

- Do not claim null rates, duplicate counts, distributions, row counts, referential integrity, PII presence, or underlying-data freshness from metadata.
- Treat an update timestamp only as a metadata/extract activity proxy and label it accordingly.
- Do not infer downstream use, field descriptions, certification, relationships, or connection risk when the API omits those properties.
- Do not mutate Tableau, query row-level data, save state, or schedule anything without explicit authorization for that action.
- Do not cite unsupported sibling skills or assume they are installed.

Referenced files: 8

View saved version →

---
name: tableau-viz-critique
description: Review and score Tableau dashboards or views from a render plus available Tableau metadata, using an evidence-based seven-domain rubric and prioritized recommendations. Use for critique or scoring; do not use to edit workbooks, validate underlying data accuracy, or assess business performance.
---

# Tableau Viz Critique

Evaluate the visualization first and advise second. Ground every score in visible evidence, distinguish observation from inference, and keep review work read-only.

## Resolve the target

Accept any of these inputs:

- an attached screenshot or render;
- a Tableau view or workbook URL;
- a Tableau content name or canonical identifier;
- a workbook with a user-specified view to review.

When a Tableau MCP server is available, discover its actual search/list, metadata, and view-image capabilities before calling them. Resolve names and URLs to the canonical identifier returned by the server; do not assume a numeric route segment is an API identifier. Use only read operations.

For a workbook with several relevant views, use the view the user named. If none was named and the choice would change the review, ask which view to score; otherwise state the selected view and why it is representative. Review every view only when the user requests workbook-wide coverage.

Fetch the largest practical render without distorting its intended aspect ratio. Metadata may establish owner, project, device layout, view names, or intended audience, but it is not evidence for a visual quality that is absent from the render.

Tableau image tools may return the render as an inline image block or as a `resource_link` containing a short-lived presigned URL.

- If an inline image is returned, inspect it directly.
- If a `resource_link` is returned, immediately download it with a direct HTTP client to a temporary or workspace file before the URL expires, then inspect the local file with the available image-viewing tool.
- Treat this read-only download as the normal completion of the Tableau image request. Do not open the presigned URL in a browser unless the user explicitly asked to view it there.
- Verify that the downloaded file is non-empty and is actually an image before scoring.
- If the URL expires, request a fresh render and retry the download once.
- Only ask the user for a screenshot after both inline inspection and direct download are unavailable or fail.

Do not conclude that a render is inaccessible merely because a browser blocks the image-host domain. Browser access and direct retrieval of an MCP-returned resource are separate paths; exhaust the connector's supported resource-delivery path first.

If the render is too small, clipped, blank, or stale enough to make scoring unreliable, request a better image instead of guessing. A screenshot supplied directly by the user does not require Tableau access.

## Establish context

Before scoring, identify:

- the dominant genre: business dashboard, analytical/exploratory, narrative, editorial, expressive/data art, or scientific/technical;
- the likely audience and time budget when supported by the request or artifact;
- the primary question the visualization appears to answer.

State the primary question in the review. Mark it **unclear** when the evidence does not support one. Do not penalize a narrative, analytical, or expressive visualization for lacking dashboard conventions that do not serve its genre.

## Score from evidence

Read [rubric.md](references/rubric.md) before assigning scores. Catalog meaningful strengths before gaps, but do not use a predetermined passing floor. Score each domain from 0–10 against its anchor descriptions and cite observable evidence for both high scores and material deductions.

Assess visible interactivity cues—filters, controls, navigation, selection state, and disclosure model—inside Audience Adaptation and Layout. Do not claim tooltip quality, action responsiveness, keyboard support, screen-reader structure, or parameter behavior from a static render.

Record the seven base scores, documented adjustments, and applicable caps in a JSON assessment. Read [assessment-schema.md](references/assessment-schema.md) for the required shape and adjustment identifiers.

The assessment JSON and the scoring helper's raw JSON output are internal scratch data, not user deliverables. Store scratch files only in an OS-managed temporary directory, never in the workspace or current directory. Do not create them with an artifact-producing file-edit tool. Do not attach, open, link, render, mention, or otherwise surface them to the user. Remove temporary files after scoring. Return only the formatted review unless the user explicitly requests JSON.

Resolve `skill_dir` as the absolute directory containing this `SKILL.md`; do not assume the skill is the current working directory. Then use the bundled helper for deterministic weighting, validation, half-even rounding, safety status, and tier assignment:

```bash
python3 "$skill_dir/scripts/score_viz.py" "/absolute/os-temp/path/assessment.json"
```

The helper is the arithmetic authority, not the visual evaluator. Never manufacture an adjustment merely to reach a tier. When it returns `safety_status: blocked`, display `Safety remediation required` instead of a quality tier and lead with the blocking issue.

If any domain genuinely cannot be assessed, do not invent a value or calculate an overall score. Deliver the supported qualitative findings, mark the missing domain, and request the evidence needed for a complete score.

## Deliver the review

Default to a complete but compact inline review unless the user requested a brief answer or a file. Do not delay useful findings behind a mandatory format question.

Include:

1. final score, tier, genre, and primary question;
2. a short verdict;
3. the seven-domain scorecard with concrete evidence;
4. the main score drivers and any cap;
5. two to four prioritized recommendations.

For each recommendation, describe the current issue, the proposed change, the affected domain, and a coarse effort level such as Low, Medium, or High. Give numeric uplift or time estimates only when the evidence supports them; otherwise avoid false precision.

Read [report-guide.md](references/report-guide.md) when the user requests a detailed review, multiple views, or a document artifact. If a `.docx`, Google Doc, or another format is requested, use the appropriate available document capability and preserve the same evidence and score.

Keep humor light and never use it when discussing misleading presentation, accessibility barriers, or exposed sensitive data.

## Boundaries

- Review-only requests do not authorize workbook edits, publishing, comments, subscriptions, or other Tableau mutations.
- Route an authorized workbook repair to a workbook-authoring skill when available; do not silently change scope.
- Visual design review does not validate source data, calculation correctness, business conclusions, or performance unless the user supplies separate evidence and requests that analysis.
- Treat visible personal or sensitive data as evidence to minimize in the report, not content to reproduce.
- When only a static image is available, label interaction and accessibility limitations explicitly.

For implementation changes, run `python -m unittest discover -s scripts/tests -v` and the active skill validator.

Referenced files: 6

View saved version →

---
name: tableau-workbook-authoring
description: Create, edit, copy, or republish a Tableau workbook by editing TWB XML and publishing it through Tableau MCP. Use for create, build, edit, modify, copy, republish, or add-chart requests. Do not use for read-only analysis or for just opening/showing an existing view (tableau-content-viewer).
---

# Purpose

Build or edit a Tableau workbook — from the bundled chart catalog when the request matches it, otherwise by hand-editing TWB XML — validate, publish through Tableau MCP, and render the result.  

## Resolve the requested Tableau object

Resolve the object the user named before resolving its containing workbook.

- “Dashboard” always means a Tableau `view`. Search with
  `filter: { contentTypes: ["view"] }`.
- After resolving the dashboard view, use its metadata to identify the parent
  workbook, then download that workbook for editing.
- Search with `contentTypes: ["workbook"]` only when the user explicitly names
  a workbook or when no dashboard/view was specified.
- Never substitute a workbook search for a dashboard search.

## Canonical Tableau MCP tools

Call these tool IDs directly when they are available. Do not scan or print the
full tool catalog merely to rediscover their names or schemas.

- Workbook search:
  `mcp__tableau__search_content`
  with `{ terms, filter: { contentTypes: ["workbook"] }, limit }`
- View / Dashboard search:
  `mcp__tableau__search_content`
  with `{ terms, filter: { contentTypes: ["view"] }, limit }`
- Exact project lookup:
  `mcp__tableau__list_projects`
  with `{ filter: "name:eq:<project-name>", limit }`
- Workbook download:
  `mcp__tableau__download_workbook`
  with `{ workbookId, includeExtract: true }`
- Workbook publish:
  `mcp__tableau__publish_workbook`
  with `{ name, projectId, workbookFilePath, overwrite }`
- Staged-upload fallback:
  `mcp__tableau__request_workbook_upload`
- Workbook metadata:
  `mcp__tableau__get_workbook`
- View metadata:
  `mcp__tableau__get_view`
- Static view render:
  `mcp__tableau__get_view_image`
  with `{ viewId, format: "PNG", width, height }`

If a directly named tool is not callable, perform one focused availability
lookup for that tool only. Do not enumerate the entire Tableau or global tool
catalog.

# Routing

- Follow-up edit on a workbook already resolved this task → the fast path below.
- Building or adding a chart:
  1. First run:
     `python3 scripts/tableau_resources.py list --tier executable --query "<intent>"`
  2. If the result is empty, immediately follow the hand-edit path below. Do not read `references/catalog-templates.md`.
  3. If a match is returned, read [`references/catalog-templates.md`](references/catalog-templates.md), inspect the match, and use `instantiate` for a new workbook or `inject` for an existing one.
- Adding a breakdown/color split, or a filter, to an existing worksheet (not a whole new chart) → read [`references/field-edits.md`](references/field-edits.md) and use `add-encoding`/`add-filter`. Run `inspect-workbook` first if the field names the user gave aren't confirmed against the workbook yet.
- No catalog match, and no field-level match above, or a genuinely custom construct neither covers → hand-edit the TWB XML per the steps below.
- First edit/republish of an existing workbook this task → resolve it with `search-content` (`filter: { contentTypes: ["workbook"] }`; see [`../../references/search.md`](../../references/search.md) for disambiguating multiple matches), then `download-workbook`.
- Brand-new workbook with no starting point and no catalog match → read [`references/new-workbook.md`](references/new-workbook.md) first.
`request-workbook-upload`, `publish-workbook`, `download-workbook`, and interactive rendering may be feature-gated — report a missing tool rather than retrying it.

## Fast path for follow-up edits

Reuse the extracted TWB/TWBX, published workbook ID, project ID, name, and view URL from this task. Make the smallest targeted XML edit, validate once, and republish with whichever transport already worked (`overwrite: true` for the same workbook, `false` for a new copy). Don't re-search, re-download, or re-inspect the whole workbook unless the current artifact is missing or stale.

## Existing workbook, first pass this task

1. Resolve the workbook (and destination project, if named) — reuse LUIDs already known this task; otherwise `search-content` (see [`../../references/search.md`](../../references/search.md) for disambiguating multiple matches). Resolve independent lookups in parallel when supported.
2. `download-workbook` with `includeExtract: true` unless this is pure inspection that won't be republished. Unzip a TWBX and edit the root TWB.
3. Add or change content: prefer `inject` against a catalog match (see Routing and [`references/catalog-templates.md`](references/catalog-templates.md)); otherwise hand-edit only the affected worksheet/dashboard and its `<datasource-dependencies>`, matching adjacent XML conventions. **Skip this step** for a plain copy/republish/move with no requested content change.
4. Validate and publish (below).
5. Render the result — see [`../../references/rendering.md`](../../references/rendering.md).

If the downloaded package looks incomplete or a dependency is missing, read [`references/package-and-upload-fallbacks.md`](references/package-and-upload-fallbacks.md). For a new XML construct or a validation failure, read [`references/xml-troubleshooting.md`](references/xml-troubleshooting.md).

## Validate and publish

Skip local validation for unmodified content (plain copy/republish/move) — it's already known-valid. A workbook produced by `instantiate`/`inject` is already validated by that command itself — re-running the standalone validator on it is redundant but harmless. For a hand-edited TWB, after the edit:

```bash
sh "$PLUGIN_ROOT/skills/tableau-workbook-authoring/scripts/run_validator.sh" path/to/workbook.twb
```

The session-start hook prepares the validator environment and installs `lxml` from `skills/tableau-workbook-authoring/scripts/requirements.txt`. If the environment is missing, run `bootstrap_python.sh` from that same directory before running the validator.

For TWBX, run `unzip -t` after rebuilding it. Publish with `publish-workbook`, using `workbookFilePath` when the runtime can pass a local path, otherwise `request-workbook-upload` first and pass its `workbookUploadId`. A TWB is validated inline (`status: 'invalid'` with structured `errors`/`warnings`); a TWBX is validated by Tableau during publish itself, so a failure there surfaces as a publish error instead of a findings list.

If validation fails, fix the reported lines/elements and retry once; stop after 10 cycles and report the remaining errors.

Record the workbook/project LUIDs, URL, and local artifact paths so a follow-up can use the fast path.

# Requirements

- Keep worksheet, dashboard, datasource, and zone names unique and consistent.
- Prefer fields already declared in the TWB's `<column>` metadata over inspecting the extract or datasource metadata; `inspect-workbook` (see `references/field-edits.md`) reads exactly that metadata.
- Don't invent field names, roles, or numbers not backed by inspected metadata.
- Don't force-fit a catalog template onto a chart it doesn't match — fall back to hand-editing instead of stretching the closest template.
- If the `download-workbook` tool returns a temporary URL, download the file locally

# References

- [`../../references/search.md`](../../references/search.md) — resolving a name/keyword to a workbook and disambiguating multiple matches.
- [`references/catalog-templates.md`](references/catalog-templates.md) — chart catalog: discover, inspect, and render bundled templates via `scripts/tableau_resources.py`.
- [`references/field-edits.md`](references/field-edits.md) — add a breakdown/color split or a filter to an existing worksheet via `inspect-workbook`/`add-encoding`/`add-filter`.
- [`references/new-workbook.md`](references/new-workbook.md) — brand-new workbook, no starting point, no catalog match.
- [`references/package-and-upload-fallbacks.md`](references/package-and-upload-fallbacks.md) — incomplete TWBX package or staged-upload fallback.
- [`references/xml-troubleshooting.md`](references/xml-troubleshooting.md) — new XML construct or validation failure.
- [`../../references/rendering.md`](../../references/rendering.md) — render the published/target view.

Referenced files: 199