Skip to content

forcedotcom/sf-skills / skills/tableau-next-asset-create

tableau-next-asset-create

Verified

Build and edit Tableau Next semantic models (SDMs), vizzes, and dashboards via MCP. TRIGGER when: building a semantic model or dashboard from CSV/Excel files; ingesting a flat file/database into DLO/DMO; profiling a dataset (grain, measures, dimensions; large/wide files via `infer_object_schema`); adding a dimension, measure, AI-ready metric, join, or logical view; running a semantic query, interpreting a breakdown, analyzing account/customer engagement, or pulling counts/totals from existing Tableau Next data (even unnamed/read-only); creating/editing a viz (filter, forecast, sort, shelf, mark encoding, reference line), widget, or dashboard layout. Also: Data Cloud SQL transforms; show a dashboard; share/revoke access; reuse prod or promote Personal Org assets; provision users/licenses; data alerts ('alert me when'); list/classify verified questions or score agent SQL. DO NOT TRIGGER for: rewriting prose descriptions, layout-only dashboard review, debugging MCP, or writing app code.

FileKindSize
SKILL.mdskill md23.9 KB
references/admin-users.mdmarkdown5.9 KB
references/ai-readiness.mdmarkdown17.5 KB
references/alerts.mdmarkdown3.9 KB
references/build-workflow.mdmarkdown41.4 KB
references/dashboard-authoring.mdmarkdown15.5 KB
references/dashboard-design-principles.mdmarkdown18.6 KB
references/data-transform-gotchas.mdmarkdown9.5 KB
references/data-understanding.mdmarkdown26.8 KB
references/deep-reference-index.mdmarkdown4.8 KB
references/destructive-operations.mdmarkdown3.9 KB
references/edit-dashboard.mdmarkdown19.8 KB
references/edit-visualization.mdmarkdown41.5 KB
references/empty-source-handling.mdmarkdown4.9 KB
references/ingest-and-metric-gotchas.mdmarkdown35.4 KB
references/insight-bundle.mdmarkdown2.7 KB
references/large-flat-file-handling.mdmarkdown19.1 KB
references/schemas/edit-dashboard/_envelope.jsonconfig3.1 KB
references/schemas/edit-dashboard/_shared-widget-fields.jsonconfig7.0 KB
references/schemas/edit-dashboard/add_page.jsonconfig1.1 KB
references/schemas/edit-dashboard/delete_page.jsonconfig947 B
references/schemas/edit-dashboard/discard_dashboard.jsonconfig482 B
references/schemas/edit-dashboard/move_widget.jsonconfig1.4 KB
references/schemas/edit-dashboard/move_widget_to_page.jsonconfig1.4 KB
references/schemas/edit-dashboard/place_widget_on_page.jsonconfig1.4 KB
references/schemas/edit-dashboard/remove_widget_from_dashboard.jsonconfig864 B
references/schemas/edit-dashboard/remove_widget_from_page.jsonconfig1.1 KB
references/schemas/edit-dashboard/rename_page.jsonconfig1.0 KB
references/schemas/edit-dashboard/save_dashboard.jsonconfig775 B
references/schemas/edit-dashboard/undo.jsonconfig421 B
references/schemas/edit-dashboard/upsert_button_widget.jsonconfig3.3 KB
references/schemas/edit-dashboard/upsert_container_widget.jsonconfig4.2 KB
references/schemas/edit-dashboard/upsert_filter_widget.jsonconfig8.8 KB
references/schemas/edit-dashboard/upsert_metric_widget.jsonconfig3.8 KB
references/schemas/edit-dashboard/upsert_navigation_widget.jsonconfig4.4 KB
references/schemas/edit-dashboard/upsert_parameter_widget.jsonconfig9.9 KB
references/schemas/edit-dashboard/upsert_text_widget.jsonconfig5.5 KB
references/schemas/edit-dashboard/upsert_visualization_widget.jsonconfig3.4 KB
references/sdm-tool-reference.mdmarkdown33.1 KB
references/semantic-query-and-enrichment.mdmarkdown16.3 KB
references/shared-gates.mdmarkdown17.6 KB
references/sharing-and-promotion.mdmarkdown14.4 KB
references/tasks/ai-readiness-audit.mdmarkdown3.0 KB
references/tasks/analyze-data.mdmarkdown2.5 KB
references/tasks/build-dashboard.mdmarkdown3.7 KB
references/tasks/build-end-to-end.mdmarkdown4.4 KB
references/tasks/create-data-transform.mdmarkdown2.8 KB
references/tasks/create-viz.mdmarkdown3.6 KB
references/tasks/edit-dashboard.mdmarkdown5.0 KB
references/tasks/edit-sdm.mdmarkdown6.5 KB
references/tasks/edit-viz.mdmarkdown2.4 KB
references/tasks/enrich-model.mdmarkdown4.0 KB
references/tasks/ingest-flat-file.mdmarkdown3.9 KB
references/tasks/manage-alert.mdmarkdown1.6 KB
references/tasks/profile-dataset.mdmarkdown2.7 KB
references/tasks/promote-or-reuse.mdmarkdown2.3 KB
references/tasks/provision-user.mdmarkdown1.8 KB
references/tasks/query-model.mdmarkdown5.3 KB
references/tasks/review-verified-questions.mdmarkdown1.9 KB
references/tasks/share-asset.mdmarkdown1.8 KB
references/verified-questions.mdmarkdown4.6 KB
references/viz-authoring.mdmarkdown41.3 KB

references/sdm-tool-reference.md

View on GitHub
# SDM Tool Reference

Input shapes and gotchas for the Tableau Next MCP semantic-model tools. Tool
names are shown bare; invoke each under your client's name for that
`tableau-next-*` server tool (see `shared-gates.md`).

## Contents

Jump to the section that matches the current intent — do not apply the rest.

- `*__dll` / `*__dlm` / `*__dlc` rejected or missing → Source-name suffixes
- Invented / suffixed field apiName after auto-bind → The apiName-mutation gotcha
- Bind fields at create (one call, no N add_dimension) → create_semantic_model
- Join "field could not be found" / `leftFieldType` → add_semantic_model_relationship
- Cross-object query throws with no join path → queryUnrelatedDataObjects
- List DLOs / DMOs / models / dashboards → Discovering assets — browse_data_assets
- Create or extend an SDM / bulk-create timeout → create_semantic_model
- Measure agg vs `dataType` mismatch → add_semantic_model_measure
- Description-only or hidden-field update (`isVisible` echo) → Updates — sparse vs PUT
- Parameter PUT (`label`/`type`/`dataType`/`defaultValue`; `List` values) → Parameters
- HardJoin / Union / CustomSQL payloads → Logical views
- Component delete (calc / metric / object / LV / relationship) → Deleting a semantic definition
- `defaultExc` string vs flat object → Response double-wrap

---

## Source-name suffixes

`add_semantic_model_data_object.dataObjectName` requires a type suffix. Bare
names from `browse_data_assets` are rejected with "DMO/CI/DLO does not exist".

| Source type | `dataObjectType` | Suffix | Example |
|---|---|---|---|
| Data Lake Object | `Dlo` | `__dll` | `accounts__dll` |
| Data Model Object | `Dmo` | `__dlm` | `ssot__Account__dlm` |
| Calculated Insight | `Cio` | `__dlc` | `churn_score__dlc` |

If `__dlm` fails for a CSV-backed object that `browse_data_assets` labeled as a
DMO, retry once with `__dll` — the browse filter sometimes mislabels DLO-backed
CSV objects. This one-time suffix correction is distinct from a `run_query`
"table does not exist" error during the Step 2 row-count check: for an
*externally discovered* candidate that error means the object is unmaterialized
(0 fields) and must NOT be retried — exclude it. For a DMO you just created
and mapped in this same flow, the same error is NOT-READY — poll `run_query`
until the table exists (`COUNT = 0` is READY; `empty-source-handling.md`; G2).

The same `__dll` / `__dlm` / `__dlc` table names are what `run_query` selects
from for the Step 2 row-count checks.

## The apiName-mutation gotcha (most common failure)

**Do not bind with `shouldIncludeAllFields: true`.** That flag is deprecated
and the server **numerically suffixes every
auto-bound dimension/measure apiName**, even on the first object with no name
collision:

- `Order_ID__c` → `Order_ID3`
- `Region__c` → `Region4`
- `account_id__c` → `account_id5`

It also sometimes rewrites `dataObjectFieldName` (`Id__c` → `Idc__c`). The
suffix is not predictable from the source name. The suffixed apiName is what
`list_semantic_model_dimensions` returns, and it is the value to pass to
`add_semantic_model_relationship`.

**Preferred bind:** fetch the DMO/DLO fields first, then pass explicit
`semanticDimensions[]` / `semanticMeasurements[]` **nested in
`create_semantic_model`** (or `add_semantic_model_data_object` for a later
object) with `shouldIncludeAllFields: false`. You control each field's
`apiName`, so `add_semantic_model_relationship` resolves first-try. Do **not**
follow create with N incremental `add_semantic_model_dimension` /
`add_semantic_model_measure` calls — that is the 27-call / 365s bind path.

HardJoin logical-view objects still use `shouldIncludeAllFields: true`
(apiNames are assigned at first save — see Logical views). If you ever inherit
a bulk-bound object, always call `list_semantic_model_dimensions` (and
`list_semantic_model_data_objects` for object apiNames) and copy the exact
stored apiName into the next call. Never construct the suffixed name yourself.

## add_semantic_model_relationship — criteria field rules

The `criteria[].leftFieldType` / `rightFieldType` determines what apiName form
to use:

| fieldType | When | apiName to use |
|---|---|---|
| `TableField` | regular dimensions/measures (the common case) | the **semantic dimension apiName** from `list_semantic_model_dimensions` (e.g. `Account_Id5`) — NOT `dataObjectFieldName` |
| `SemanticField` | calculated dimensions only | the calculated dimension's apiName; must have a row-level dependency on the object (pure constants rejected; aggregations rejected with `SEMANTIC_FIELD_LEVEL_ERROR`) |
| `Formula` | expression-based joins | a TUA expression like `POWER([object].[field], 1)`; row-level only; left/right return types must match |

Using `dataObjectFieldName` with `TableField` returns "field could not be
found" even though the field exists — this is the single most common
relationship error.

Other relationship constraints:

- `joinType` MUST be `Auto` for model-level relationships. `Left` / `Right` /
  `Inner` / `Full` are valid only inside a logical view (`logicalViewId` set).
- `label` is REQUIRED despite the schema marking it optional.
- `cardinality`: `OneToOne` / `OneToMany` / `ManyToOne` / `ManyToMany` /
  `Unspecified`. A fact→dimension join is typically `ManyToOne`.
- `criteria` is usually a single `Equals` on the natural key.
- **Formula** left/right return types must match or the API returns
  `CREATE_SEMANTIC_ENTITY_FAILED` with a message containing "must be of the
  same type".

## queryUnrelatedDataObjects

`list_semantic_models` returns `queryUnrelatedDataObjects` per model. When it
is `"Exception"`, a semantic query that spans two objects with no join path
**throws** rather than returning partial data. This is why an island object
breaks queries hard, not softly. Joining every object avoids it.

**`list_semantic_models`: an unknown `dataspace` returns a raw 500**, not an
empty list or a 400. Verify the dataspace exists before filtering on it.

## Discovering assets — browse_data_assets

The single discovery endpoint across all asset types — DLOs/DMOs/CIOs, dashboards,
visualizations, workspaces, semantic models. Step 1 of the happy path below.

**Calling convention.** To list all assets of one type: `searchTerm: ""` (a literal
empty string — omitting it returns `UNKNOWN_EXCEPTION`) plus an `AssetType In [...]`
filter.

```jsonc
// Literal "" — omit searchTerm → UNKNOWN_EXCEPTION. Repeat with
// MktDataModelObject / MktCalculatedInsightObject for DMOs / CIOs.
{
  "searchTerm": "",
  "filters": {
    "filters": [
      { "field": "AssetType", "operator": "In",
        "values": ["MktDataLakeObject"] }
    ]
  },
  "limit": 50
}
```

**`AssetType` is case-sensitive and unvalidated — a typo returns zero results, not
an error.** Use the exact-cased values only: `AnalyticsDashboard`,
`AnalyticsVisualization`, `AnalyticsWorkspace`, `SemanticModel`,
`SemanticDefinition`, `MktDataLakeObject` (DLO), `MktDataModelObject` (DMO),
`MktCalculatedInsightObject` (CIO). A zero-result response for a plausible-looking
type name means "check the casing/spelling," not "no assets exist."

**Empty-`searchTerm` matrix.** `searchTerm: ""` works for `MktDataLakeObject` /
`MktDataModelObject` / `MktCalculatedInsightObject` but throws `UNKNOWN_EXCEPTION`
for `AnalyticsDashboard` / `AnalyticsVisualization` / `AnalyticsWorkspace` /
`SemanticModel` / `SemanticDefinition`. For those five, either use the per-type
list tool (`list_dashboards` / `list_visualizations` / `list_workspaces` /
`list_semantic_models`) or pass a real ≥2-character search term (1-char terms are
rejected with `search term must be longer than one character`).

**`And` behaves like `Or`.** `conjunctiveOperator: "And"` over multiple
`AssetType In` clauses returns the union, not an intersection — true intersection
isn't implemented (e.g. `AssetType In [SemanticModel] And AssetType In
[AnalyticsWorkspace]` returns the union, not the empty set). `conjunctiveOperator:
"Or"` over heterogeneous filter shapes also frequently returns `UNKNOWN_EXCEPTION`.
Compose at most one filter clause per call and intersect client-side if you need one.

**Only `AssetType` filters universally.** Type-specific fields (e.g. `CreatedBy`
on `SemanticModel`) return `Invalid filter field for type ...` — don't assume
per-type filter validity.

**Scope: current org only.**

Prefer the per-type tools (`list_visualizations`, `list_semantic_models`,
`list_workspace_assets`) when you need their richer per-type detail (dataSource,
chaining URLs, workspace scoping) rather than the generic `assets[]` shape.

**`list_workspaces` has no pagination metadata and an undocumented oldest-first
sort** (ascending by `createdDate`, no `total`/`hasNextPage`/page URL). To find
the *most recently created* workspace, don't page through everything — call
`browse_data_assets_v2` with `assetTypesFilter: ["AnalyticsWorkspace"]`,
`sortField: "LastModifiedDate"`, `sortOrder: "Descending"` instead.

## create_semantic_model — surface and recovery

- **Param names are `apiName` + `dataspace`, not `name` + `dataSpaceName`.**
  The natural-sounding `name`/`dataSpaceName` guess is rejected — use
  `apiName` (model's developer name) and `dataspace` (lowercase, e.g.
  `"default"`) as shown in the payload below.
- Nested `semanticDataObjects[].label` is REQUIRED — the server
  rejects without it.
- **Bind fields in this call.** Each `semanticDataObjects[]` item accepts
  nested `semanticDimensions[]` / `semanticMeasurements[]` with
  `shouldIncludeAllFields: false`. Fetch the DMO/DLO fields first (`run_query`
  `SELECT * … LIMIT 20` or the ingest SCHEMA REALITY CHECK), classify them
  (G5 / Step 0.5), and pass the explicit arrays — including join-key fields
  from Step 3 (e.g. `PartKey`) even if they look like system columns. You
  control each field's `apiName`, so a later `add_semantic_model_relationship`
  resolves first-try. Do **not** use `shouldIncludeAllFields: true` (deprecated;
  numeric-suffix mutation) and do **not** follow with N
  `add_semantic_model_dimension` / `_measure` calls.
- **Still post-create:** relationships, metrics, calculated fields, parameters,
  and logical views require `add_semantic_model_*` after create. Adding a
  *single extra field* to an already-bound object also uses
  `add_semantic_model_dimension` / `_measure`.
- **Extend a Model** uses the same tool: pass `baseModels[]` of
  `{ "apiName": "<existing SDM apiName>" }` in the **same `dataspace`**. There is
  no separate extend tool. Typical label `"<Base Label> (Extended)"`.

```jsonc
// One-call bind. shouldIncludeAllFields:false + explicit nested fields.
// Include every join-key column from Step 3 (PartKey, account_id__c, …).
{
  "apiName": "Pipeline_Analysis",
  "dataspace": "default",
  "label": "Pipeline Analysis",
  "description": "Tracks open pipeline opportunities and associated account data for sales forecasting.",
  "sourceCreation": "Other",
  "categories": ["Sales"],
  "semanticDataObjects": [
    {
      "apiName": "Opportunities",
      "label": "Opportunities",
      "description": "Active sales opportunities with stage, amount, and close date",
      "dataObjectName": "opportunities__dlm",
      "dataObjectType": "Dmo",
      "tableType": "Standard",
      "shouldIncludeAllFields": false,
      "semanticDimensions": [
        {
          "apiName": "Stage",
          "label": "Stage",
          "dataObjectFieldName": "stage__c",
          "dataType": "Text",
          "displayCategory": "Discrete",
          "description": "Opportunity sales stage. Values: Prospecting through Closed Won.",
          "isVisible": true
        },
        {
          "apiName": "Account_Id",
          "label": "Account ID",
          "dataObjectFieldName": "account_id__c",
          "dataType": "Text",
          "displayCategory": "Discrete",
          "description": "Join key to Accounts. Record identifier — do not aggregate.",
          "isVisible": true
        },
        {
          "apiName": "DataSource",
          "label": "Data Source",
          "dataObjectFieldName": "DataSource__c",
          "dataType": "Text",
          "isVisible": false
        }
      ],
      "semanticMeasurements": [
        {
          "apiName": "Amount",
          "label": "Amount",
          "dataObjectFieldName": "amount__c",
          "dataType": "Number",
          "aggregationType": "Sum",
          "description": "Gross opportunity amount in org currency. Primary pipeline measure.",
          "sentiment": "SentimentTypeUpIsGood",
          "isVisible": true
        }
      ]
    }
  ]
}
```

```jsonc
// Same create_semantic_model tool — no separate extend API.
{
  "apiName": "<NEW_SDM_API_NAME>",
  "dataspace": "default",
  "label": "<Base Label> (Extended)",
  "sourceCreation": "Other",
  "baseModels": [{ "apiName": "<BASE_SDM_API_NAME>" }]
}
```
- **Bulk-create timeout (>= ~5 objects).** Many `semanticDataObjects[]` in one
  call returns `"Unexpected error while invoking tool postSemanticModelCollection"`
  but the SDM **does persist** ~10–30s later. A naive retry hits
  `"Unique constraint violated"`. Recovery: wait ~30s, then `list_semantic_models`
  to confirm. Prefer create-with-anchor **and its nested fields**, then
  incremental `add_semantic_model_data_object` with the same nested
  `semanticDimensions[]` / `semanticMeasurements[]` shape. If a table has no FK
  to the anchor, add the intermediate first, then bridge through it.
- Optional final sanity check: `get_semantic_model` with
  `includeModelContent=true`.

## add_semantic_model_measure — agg / type allow-list

Create does **not** fully cross-validate `aggregationType` against `dataType` /
`storageDataType`. Some mismatches return 201 and fail at query time
(`Cannot convert from TEXT to NUMBER`); others reject at create. Per-type
allow-list (plus `Auto`, which resolves to the type default):

- `Text` / `Boolean`: only `Min`, `Max`, `Count`, `CountDistinct`.
- `Url` / `Email` / `Phone` / `Geo`: only `Count`, `CountDistinct`.
- `Number` / `Percentage` / `Currency`: all aggregations.

**`dataType: "Currency"` requires a backing record-currency field on the
DMO.** On a DMO with no `CurrencyIsoCode`-backed column, `Currency` is
rejected at create — fall back to `dataType: "Number"` for that measure
instead of retrying `Currency`.

Always set `dataType` to match the column's real `storageDataType` from
`list_semantic_model_dimensions` / `_measures`. PUT on an existing measure also
skips this allow-list — invalid combos return 200 and fail at query time.
Changing `aggregationType` on a measure referenced by a metric may break that
metric — `list_semantic_model_metrics` first.

Do not set `externalLevel` or `externalConnectionApiName` on a calculated
measure unless connecting to an external definition.

## Updates — sparse vs PUT

| Tool | Semantics | Must echo / re-send |
|---|---|---|
| `update_semantic_model_dimension` / `_measure` | **Sparse** — omitted fields stay put, except `isVisible` | Always echo `isVisible` and `dataObjectFieldName` |
| `update_semantic_model_data_object` | **Full PUT** | GET via `get_semantic_model_data_object`, send the complete object including nested `semanticDimensions[]` / `semanticMeasurements[]`; a partial body discards omitted nested fields |
| `update_semantic_model_metric` | **Full PUT** | Re-send `label`, `measurementReference`, `timeDimensionReference`, `insightsSettings` (GET first via `get_semantic_model_metric`) |
| `update_semantic_model_calculated_dimension` | **Full PUT** | GET via `get_semantic_model_calculated_dimension`, send the complete object (`apiName`, `label`, `expression`, `dataType`, `displayCategory`); omitted fields clear or reset to defaults |
| `update_semantic_model_calculated_measure` | **Full PUT** | GET via `get_semantic_model_calculated_measure`, send the complete object; omitted fields reset to defaults (`decimalPlace: 2`, `directionality: "Up"`, `sentiment: "SentimentTypeUpIsGood"`, …) |
| `update_semantic_model_relationship` | **Full PUT** | GET via `get_semantic_model_relationship`, modify, send the returned body back complete. Validate cardinality in the data before changing it. |
| `update_semantic_model_logical_view` | **PATCH** — only `description`, `filterLogic`, `filters` persist | GET first via `get_semantic_model_logical_view`. Empty body `{}` rejected. Label / SQL / view-type changes are discarded — delete-and-recreate for SQL or type |
| `update_semantic_model_parameter` | **Full PUT** — not PATCH | Re-send `label`, `type`, `dataType`, `defaultValue` even for a description-only change. `apiName` immutable — omit it. `List` needs `values`. See Parameters. |
| `update_semantic_model` (model) | Empty/missing body NPEs | Never call with no body |

**`isVisible` is NOT preserved by sparse update (server bug).** If a dimension or
measure is currently `isVisible: false`, omitting `isVisible` silently resets it
to `true`. Echo it from `list_semantic_model_dimensions` / `_measures` on every
call, even description-only backfills.

```jsonc
// Description-only backfill of a hidden measure. Same keys on
// update_semantic_model_dimension. Do NOT send description alone.
{
  "modelApiNameOrId": "My_Model",
  "dataObjectNameOrId": "My_Object",
  "measurementNameOrId": "My_Measure",
  "apiName": "My_Measure",
  "dataObjectFieldName": "my_measure__c",  // omit → [null] SEMANTIC_FIELD_NOT_VALID
  "isVisible": false,                      // echoed from list_*; omit → unhides
  "description": "Net revenue after discounts, in org currency."
}
```

`apiName` and `dataObjectFieldName` are immutable. Omitting `dataObjectFieldName`
sends `null` → `SEMANTIC_FIELD_NOT_VALID` / `UPDATE_ENTITY_API_NAME_ERROR`
("The referenced Data Cloud fields ([null]) could not be found…"). A wrong
(non-null) name uses the same error code — distinguish by `[null]` in the
brackets vs a literal field name. Empty-body dimension/measure updates return
500, not 400.

`dataType` transitions on a dimension (e.g. Text → Number) are permitted
without checking `storageDataType`. A mismatch fails at **query** time — read
`storageDataType` before changing `dataType`.

Path exception: metric tools use `metricNameOrId`, not `*ApiNameOrId`.
`apiName` on a metric PUT is immutable — a different value in the body is
silently ignored.

**Response wrap:** dimension/measure updates return a **flat parsed object** —
NOT double-wrapped (no `defaultExc` wrapper). Metric / calc-measure /
relationship updates double-wrap like the add tools. Errors on the unwrapped
pair use `{enhancedErrorType, message, output}`.

Incomplete metric PUT: omitting `measurementReference` → HTTP 500 NPE;
`{description: "x"}` → `"Required fields are missing: [MasterLabel]"` (the
payload field is `label`); `{}` → 500 NPE on `Parameter.getValue()`.

## Parameters

Parameters cannot be created inline on `create_semantic_model` — they
require post-create `add_semantic_model_parameter`. Enumerate with
`list_semantic_model_parameters`. Delete with
`delete_semantic_model_parameter` (destructive, no undo; success is often
HTTP 204).

### `update_semantic_model_parameter` — PUT, not PATCH

Full payload required every call. MUST re-send `label`, `type`,
`dataType`, and `defaultValue` even if only changing `description`.
Incomplete bodies fail validation.

- **Inputs:** `modelApiNameOrId`; `parameterApiNameOrId`; `label`; `type`
  (`All` or `List`); `dataType`; `defaultValue`. `description` is optional.
- **`apiName` is immutable** — omit it from the body. A different value is
  silently ignored.
- **`dataType` (live tool):** `Boolean` / `Date` / `DateTime` / `Email` /
  `Number` / `Percentage` / `PhoneNumber` / `Text`. **`Url` is not on the
  live sidecar** — do not send it.
- **`List` type:** `values` is required (array of plain strings) and
  `defaultValue` must exactly match one entry in `values`.
- **Scope:** current org only.
- **Response:** the API double-wraps as `{"defaultExc": "<stringified
  JSON>", "responseCode": <number>}`, but the MCP tool unwraps
  transparently — callers receive the parsed parameter object directly.

```jsonc
// Description-only change still re-sends the full PUT body.
{
  "modelApiNameOrId": "My_Model",
  "parameterApiNameOrId": "RegionPick",
  "label": "Region",
  "type": "List",
  "dataType": "Text",
  "values": ["East", "West", "Central"],
  "defaultValue": "East",              // must match one entry in values
  "description": "Sales territory, not billing geography."
}
```

## Logical views

A logical view is a virtual table (pre-joined / filtered / union) without
modifying base data objects. Enumerate existing ones via `get_semantic_model`
(`semanticLogicalViews[]`) before creating. `label` is required.
`Hierarchy` is **not currently supported via MCP**.

**HardJoin 3-step** (field apiNames are assigned at first save — unknown in
advance):

1. `add_semantic_model_logical_view` with `semanticDataObjects` only — **no**
   `semanticRelationships`.
2. `get_semantic_model_logical_view` to read assigned field apiNames.
3. `add_semantic_model_relationship` with those names. LV joins use `joinType`
   `Left`/`Right`/`Inner`/`Full`, **not** `Auto`.

Each LV data-object `apiName` must be unique vs model-level objects
(`Unique constraint violated` — prefix `LV_`). `dataObjectName` still needs
`__dll` / `__dlm` / `__dlc`. Auto-bind suffixes still apply — read back before
joining.

```jsonc
// HardJoin step 1 — objects only. Do NOT send semanticRelationships here.
{
  "modelApiNameOrId": "SalesSDM",
  "apiName": "OrdersWithCustomers_LV",
  "label": "Orders with Customers",
  "semanticViewTypeEnum": "HardJoin",
  "semanticDataObjects": [
    {
      "apiName": "LV_Orders",
      "label": "Orders",
      "dataObjectName": "orders__dll",
      "dataObjectType": "Dlo",
      "shouldIncludeAllFields": true
    },
    {
      "apiName": "LV_Customers",
      "label": "Customers",
      "dataObjectName": "customers__dll",
      "dataObjectType": "Dlo",
      "shouldIncludeAllFields": true
    }
  ]
}
```

**Union:** all tables live in **exactly one** `semanticUnions[]` entry. Use
`semanticUnions[]`, not top-level `semanticDataObjects[]`. **Do NOT pass
`"semanticViewTypeEnum": "Union"`** — the server infers Union from
`semanticUnions[]` and returns 500 if the enum is set to `"Union"`. GET
responses may show `semanticViewTypeEnum: "HardJoin"` for a Union (cosmetic
server bug). `semanticMappedFields[].fields[].fieldApiName` must be the
**locally-scoped** semantic dim/measure apiName defined on that ULV data
object — NOT `dataObjectFieldName` and NOT the base model's suffixed names.
Both fail `"Field API name X not found in either measurements or dimensions."`
Mapped-field `semanticDimension` / `semanticMeasurement` must be fully
populated (`apiName`, `label`, `dataObjectFieldName`, `dataType`) or GET 500s
with `Required fields are missing: [MasterLabel]`. Use `scanMinimalTables: true`
when the Union is used in a shared-dimension merge model.

```jsonc
// Union — omit semanticViewTypeEnum. fieldApiName is the local dim/measure
// apiName (US_OrderId), not order_id__c and not a base-model suffix (Order_Id8).
{
  "modelApiNameOrId": "SalesSDM",
  "apiName": "AllOrders_LV",
  "label": "All Orders",
  "semanticUnions": [
    {
      "apiName": "AllOrders_ULV",
      "label": "All Orders ULV",
      "semanticDataObjects": [
        {
          "apiName": "LV_Orders_US",
          "label": "Orders US",
          "dataObjectName": "orders_us__dll",
          "dataObjectType": "Dlo",
          "semanticDimensions": [
            {
              "apiName": "US_OrderId",
              "label": "Order ID",
              "dataObjectFieldName": "order_id__c",
              "dataType": "Text"
            }
          ],
          "semanticMeasurements": [
            {
              "apiName": "US_Revenue",
              "label": "Revenue",
              "dataObjectFieldName": "revenue__c",
              "dataType": "Currency",
              "aggregationType": "Sum"
            }
          ]
        },
        {
          "apiName": "LV_Orders_EU",
          "label": "Orders EU",
          "dataObjectName": "orders_eu__dll",
          "dataObjectType": "Dlo",
          "semanticDimensions": [
            {
              "apiName": "EU_OrderId",
              "label": "Order ID",
              "dataObjectFieldName": "order_id__c",
              "dataType": "Text"
            }
          ],
          "semanticMeasurements": [
            {
              "apiName": "EU_Revenue",
              "label": "Revenue",
              "dataObjectFieldName": "revenue__c",
              "dataType": "Currency",
              "aggregationType": "Sum"
            }
          ]
        }
      ],
      "semanticMappedFields": [
        {
          "apiName": "MF_OrderId",
          "label": "Order ID",
          "fields": [
            { "tableApiName": "LV_Orders_US", "fieldApiName": "US_OrderId" },
            { "tableApiName": "LV_Orders_EU", "fieldApiName": "EU_OrderId" }
          ],
          "semanticDimension": {
            "apiName": "MF_OrderId_dim",
            "label": "Order ID",
            "dataObjectFieldName": "order_id__c",
            "dataType": "Text"
          }
        },
        {
          "apiName": "MF_Revenue",
          "label": "Revenue",
          "fields": [
            { "tableApiName": "LV_Orders_US", "fieldApiName": "US_Revenue" },
            { "tableApiName": "LV_Orders_EU", "fieldApiName": "EU_Revenue" }
          ],
          "semanticMeasurement": {
            "apiName": "MF_Revenue_meas",
            "label": "Revenue",
            "dataObjectFieldName": "revenue__c",
            "dataType": "Currency",
            "aggregationType": "Sum"
          }
        }
      ]
    }
  ]
}
```

**CustomSQL:** prefer `customSQLV2`. Exactly **one** `semanticDataObjects`
entry with `dataObjectType: "CustomSQL"`. That entry must have explicit
dims/measures — `shouldIncludeAllFields: true` does **NOT** satisfy CustomSQL
validation. Measurements also need `aggregationType`.

```jsonc
{
  "modelApiNameOrId": "SalesSDM",
  "apiName": "TopCustomers_LV",
  "label": "Top Customers",
  "semanticViewTypeEnum": "CustomSQL",
  "customSQLV2": "SELECT customer_id__c, customer_name__c, SUM(revenue__c) AS total_revenue__c FROM orders__dll GROUP BY customer_id__c, customer_name__c",
  "semanticDataObjects": [
    {
      "apiName": "LV_TopCustomers_SQL",
      "label": "Top Customers SQL",
      "dataObjectName": "orders__dll",
      "dataObjectType": "CustomSQL",
      "semanticDimensions": [
        {
          "apiName": "CustomerId_dim",
          "label": "Customer ID",
          "dataObjectFieldName": "customer_id__c",
          "dataType": "Text"
        },
        {
          "apiName": "CustomerName_dim",
          "label": "Customer Name",
          "dataObjectFieldName": "customer_name__c",
          "dataType": "Text"
        }
      ],
      "semanticMeasurements": [
        {
          "apiName": "TotalRevenue_meas",
          "label": "Total Revenue",
          "dataObjectFieldName": "total_revenue__c",
          "dataType": "Currency",
          "aggregationType": "Sum"
        }
      ]
    }
  ]
}
```

`filterLogic` is required when `filters` has more than one entry;
`filters[].fieldName` is fully qualified `<dataObjectApiName>.<fieldApiName>`.

**Updates (PATCH).** `update_semantic_model_logical_view` only persists
`description`, `filterLogic`, and `filters` — see Updates above. GET first.
Label is silently ignored. SQL or `semanticViewTypeEnum` changes require
delete-and-recreate. Empty body `{}` is rejected.

## Tool sequence (happy path)

1. `browse_data_assets` (per AssetType) — discover candidates
2. `run_query` `SELECT COUNT(*)` per candidate — verify rows (Step 2)
3. `run_query` JOIN probe — confirm keys match (Step 3)
4. `run_query` `SELECT * … LIMIT 20` (or ingest SCHEMA REALITY CHECK) — fetch fields, classify (Step 0.5 / G5)
5. `create_semantic_model` — one call with nested `semanticDataObjects[]` that include explicit `semanticDimensions[]` / `semanticMeasurements[]` (`shouldIncludeAllFields: false`, join keys included). Extra objects after the anchor: `add_semantic_model_data_object` with the same nested arrays. HardJoin LV objects still use `shouldIncludeAllFields: true` (Logical views).
6. `list_semantic_model_data_objects` + `list_semantic_model_dimensions` — light confirm the apiNames you set
7. `add_semantic_model_relationship` per key pair (uses the apiNames you set — first-try)
8. `list_semantic_model_relationships` — confirm zero islands
9. `run_semantic_query` — confirm non-empty cross-object result

## Deleting a semantic definition

Component deletes (calculated dimension/measure, metric, data object, logical
view, relationship) are DESTRUCTIVE with no undo — get explicit user
confirmation first.
Whole-asset deletes (`delete_semantic_model` / viz / dashboard / workspace)
stay on `SKILL.md`. Cross-asset dependents of a viz or dashboard (how many
dashboards embed this viz) are `list_asset_dependencies` — details in
`dashboard-authoring.md`, **not** this section's
`list_semantic_model_dependencies`.

Use the real tool names: `delete_semantic_model_calculated_dimension`,
`delete_semantic_model_calculated_measure`, `delete_semantic_model_metric`,
`delete_semantic_model_data_object`, `delete_semantic_model_logical_view`,
`delete_semantic_model_relationship`.
There is no `delete_semantic_model_calculated_field`. Metric delete does **not**
cascade to the underlying measure (use `_calculated_measure` separately).
Confirm the target apiName with `list_*` / `get_*` first. Metric path is
`metricNameOrId`. For a logical view, confirm with
`get_semantic_model_logical_view`. For a relationship, confirm with
`list_semantic_model_relationships`; path is `relationshipNameOrId`.

Relationship delete has **no** `relationshipCascadeDelete` escape hatch —
direct dependents must be removed or repointed manually after the
`rawEdges: true` preflight. Calculations or metrics that only reference fields
on the joined objects depend on those **data objects**, not the join, and do
**not** block deleting the relationship.

### Preflight

Call `list_semantic_model_dependencies` with **`rawEdges: true`** before every
component delete. Default `rawEdges: false` is LOSSY — it collapses every edge
to the leaf data object, hiding calc-on-calc and metric-on-calc dependents. The
call still returns **200 OK with a plausible graph** (silent false negative).

Optional `types` is **TitleCase** (`CalculatedDimension`,
`CalculatedMeasurement`, `Metric`, `Relationship`, `LogicalView`), not
screaming-case. When omitted, defaults to CalculatedDimension and
CalculatedMeasurement **only** — Metric / Relationship / LogicalView are
omitted unless you ask.

The result is keyed by depender: `definitionApiName` + `dependencies[]`. With
`rawEdges: true`, dependency `definitionType` / `label` / `modelApiName` may be
null — rely on `apiName`. **Ignore `fieldApiName`** (null here). To find
dependents of X, scan entries whose `dependencies[]` contains apiName X. For a
data object, also scan child dimensions/measures. Scope is the current model
and its **base models** only — extending-model dependers are not returned.

### Operation ordering

Delete is **BLOCKED** if dependents exist. Delete **leaf dependents first**,
then re-query the graph, then delete this field.

| Flag | What it actually clears |
|---|---|
| `relationshipCascadeDelete: true` | Dependent **relationship rows** only — **not** calc / metric / LV / dimension dependents. Does **not** touch native columns |
| Metric delete | **No** cascade escape hatch — clear dependents manually. Does not delete the underlying calc/raw measure |
| Relationship delete | **No** `relationshipCascadeDelete` escape hatch — remove or repoint direct dependents manually. Calcs/metrics that only reference fields on the joined objects depend on those **data objects**, not the join, and do not block this delete |
| Data-object delete | Cascade flag auto-removes **joins** that reference the object; calc fields, metrics, and dimensions must be removed first |

Set `relationshipCascadeDelete: true` on LV / calc / data-object deletes unless
you are preserving orphaned relationship rows — still clear non-relationship
dependents first.

### Recovery

- **Multi-dependent errors concatenate entries WITHOUT a separator** (e.g.
  `...CALCULATED_DIMENSIONDependency API name: m_uses_dim...`). Do **not**
  string-parse the error — read dependents from the pre-flight.
- **Logical-view blocked delete is a different shape.** Calc/metric deletes
  return a clean "can't be deleted because it has dependent elements" message.
  A blocked LV delete currently surfaces as **HTTP 500 with a raw Java stack
  trace** whose root contains `VetoDataChangeException ... DEPENDENCY_EXISTS`
  ("This semantic definition is referenced elsewhere in Salesforce…"). Treat
  500 + `DEPENDENCY_EXISTS` as a **dependency block, NOT a transient failure —
  do not retry.** The stack does not name the blocker; use the pre-flight.
- Success is often HTTP 204: `defaultExc` is the literal string `"204"` (not
  JSON-parseable) — branch on `responseCode === 204`.

## Response double-wrap

Some tools (e.g. `add_semantic_model_dimension`, `run_query`,
`run_semantic_query`, `create_workspace`) wrap the body as
`{"defaultExc": "<stringified JSON>", "responseCode": <number>}`. Parse
`JSON.parse(response.defaultExc)` to read the result. Read tools like
`list_semantic_model_*` and `get_dashboard` are NOT wrapped — read fields
directly.
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall