MCP tool reference

Call this first.

ONE round-trip, token-budgeted (≤~2k tokens), giving connection state · entitlement · model overview · a compact excerpt from the model's declared Primer · AI-readiness · structural graph · in-flight work · recent activity · deterministic next actions. Drill down with get_model_primer, connection_status, get_entitlement, ai_readiness_scan, get_model_graph, get_workflow_run, get_plan, get_spec and list_calendars. It omits full findings, object detail and DAX bodies.

Table/relationship counts, tables by type (date/calculated/hidden), relationship breakdown (many-to-many, bidirectional, inactive counts), and the names of DISCONNECTED visible tables (in no relationship – the key star-schema smell) – without the full per-table/per-relationship detail. Call get_model_graph for the full graph when you need it.

Use it to reason about the star schema, find isolated tables, or audit bidirectional/inactive relationships. On a LARGE model, model_graph_summary is the cheaper first call.

Each: name, displayName, category, kind (string/bool/number/enum), current value, enum options, read-only. Pass 'model:' for model-level settings, or any table/column/measure/relationship/function ref. Pair with set_property.

Pass an empty/null parentRef to list tables; pass a table ref (e.g. 'table:Sales') to list its measures and columns.

One call to audit smells like a visible key column, a key with SummarizeBy != None, or a missing description/format.

One call to audit naming/folders/formats/descriptions across all measures (e.g. find measures missing a description or a format string).

Each has a ref like 'function:MyFunc' – read its body with get_dax, edit with update_measure, rename with rename_object.

Backs the Advanced-Modelling object browser (perspective/field-parameter/RLS pickers). Prefer this over separate list_measures + list_columns when you need the WHOLE object surface at once (it also carries hierarchies, which those omit). Read-only metadata; works offline.

Default (no filters): case-insensitive substring over object names, descriptions, and DAX expressions – the classic behaviour. Optional modes: caseSensitive, wholeWord, regex (validated, with a timeout guard). Optional filters: kinds[] (measure/column/table/hierarchy/calcitem/function/role/perspective/partition), fields[] (name, description, expression, displayFolder, formatString, rlsFilter, mExpression, synonyms – pass fields to widen BEYOND the default name+description+expression), and scope ('table:Name' or 'folder:Name'). Each hit carries ref, kind, table, the field matched, a snippet, raw-offset spans[], and – key for replace – a matchClass (ObjectName | PlainText | DaxReference | DaxLiteral | DaxComment | DaxCode | MExpression) with replaceable + replaceHint. matchClass tells you how to change it safely: ObjectName → rename_object (references auto-update); DaxReference/DaxCode → NOT text-replaceable (rename the object); DaxLiteral/DaxComment/PlainText/MExpression → replace_in_object. Results carry byField/byMatchClass/byKind facet counts and paging (offset). An invalid regex is reported in .Error (not thrown).

Returns basic counts.

Localhost uses integrated Windows auth – no token. Leave dataSource empty to auto-pick the running instance, or pass 'localhost:51234' (see list_local_instances).

Unlike connect_xmla (which only enables read-only DAX/DMV), this loads the model's metadata via TOM, exactly as Tabular Editor attaches to a deployed model. Edits stay IN-MEMORY and undoable; push them back with deploy_live (the write half – dry-run by default) or persist to a TMDL folder with save_model for review/deployment. endpoint e.g. 'powerbi://api.powerbi.com/v1.0/myorg/<Workspace>'. Leave database empty to load the workspace's only/first dataset. authMode: interactive (browser/MFA via Azure.Identity) | serviceprincipal (AZURE_*/FABRIC_* env – most reliable for Fabric) | azcli (default) | devicecode. tenantId optional – target a specific Entra tenant when your `az login` is a different tenant than the model's.

Default compatibility level 1604 (Direct-Lake-capable, Power BI mode). The model is UNSAVED – the first save_model MUST be given a path. Build it with create_data_source / create_named_expression / create_import_table / create_directlake_table / create_column / create_measure / create_relationship, etc. Returns the new session.

Pass a target folder path (TMDL) or null to overwrite the source. format defaults to TMDL.

Pass a Data Source like 'localhost:51234', or leave it empty to auto-pick the running Power BI Desktop instance.

endpoint e.g. 'powerbi://api.powerbi.com/v1.0/myorg/<Workspace>'. authMode: azcli (default, uses your `az login`), interactive (browser), or devicecode. tenantId optional – target a specific Entra tenant when your `az login` is a different tenant than the model's (same as open_live). The result's account field names the identity signed in, when known.

Use one with connect_local.

Use this INSTEAD of asking the user to retype an endpoint. Each record carries endpoint, dataset, auth mode, model name, last-used, and the user's target label. Holds NO secrets: authMode is a mode NAME, never a token. 'label' is what the USER declared the environment to be (local | dev | uat | prod); an EMPTY label means the target is treated as PRODUCTION, the strictest reading and the only inference ever made. NEVER guess a label from an endpoint's name. 'workingFolder' is a durable local copy made from that source. 'publishConnectionId' is the separate final XMLA destination when one is linked; a local source does not become a published destination by implication. Existing user-owned local files remain valid sources even though they are not live-connection records. Read-only and free. Next: connection_context for the active edit/query/publish identities, or prepare_working_copy to preview a local workflow.

REFUSED FROM THIS DOOR. A label is a governance statement and the agent's own permissions are gated on it, so an agent that could relabel prod as dev would have defeated the matrix that restrains it. This tool exists so you can EXPLAIN the refusal, not work around it: when an operation is blocked because a target is unlabelled (and therefore treated as production), name the endpoint that needs labelling and ask the user to set it. Read current labels with list_connections.

Does not disconnect anything and does not touch the model – it only forgets the endpoint, its auth mode, its target label and its working folder. Re-connecting to the same endpoint records it again, UNLABELLED, which means it will be treated as production until the user labels it.

They may deliberately be two copies: for example, a safe local working copy for edits while the published model answers real-data queries. Returns relationship=sameInstance only when that is proven; workingCopyAndPublished and twoModels explicitly mean two model contexts are in play. Read this before comparing, testing, or deploying so you never assume the query target is the write target. Holds no credentials. Read-only and free. Next: list_connections to choose a remembered model, connect_xmla/connect_local to change only the query model, or open_live/open_local to edit and query one live model.

The source may be XMLA or a local running model. Default commit=false is read-only: it names the local folder, explains which model will answer tests/queries, names the separate XMLA publish destination when one is selected, and refuses any non-empty folder not proven to belong to that source. commit=true creates or opens the durable local model, then attaches the optional queryConnectionId. Omit queryConnectionId to query the source. For a local source, publishConnectionId is optional and must name an XMLA connection; for an XMLA source it defaults to the source. Local files alone cannot execute DAX. Reopening NEVER refreshes or overwrites local edits, and this operation NEVER pushes changes. Use list_connections for the ids. Next: read connection_context, edit and test locally, then review changes before an explicit push to the linked published model.

Stores endpoint, optional model name and auth MODE only; never a token or secret. New records are unlabelled and therefore treated as production until the human labels them. Use this only when the endpoint is already known, then list_connections to retrieve its id. This does not open, query, edit, or publish a model.

Works for Semanticus-created working copies and existing user-owned local files, including files in source control. Writes only machine-local connection metadata: it never edits model/repository files and never deploys. Use list_connections for the XMLA connection id. The actual push remains a separate preview + confirmation through apply_model_diff. Next: connection_context to verify Editing and Publish to before reviewing changes.

Optionally filter to ONE connection id (from list_connections). Each event carries the WHERE (endpoint/dataset), the account UPN in play when known, the outcome (ok – a failed open that changed nothing is still recorded), a short detail note, and a UTC timestamp. Holds NO credentials – never a token or secret. Use it to see who last connected where, or to confirm an account switch actually took effect. Read-only and free. Next: probe_connection_accounts for who the NEXT open will sign in as; list_connections for the target list.

A sign-in is remembered per tenant and credential family (interactive / device-code), so 'account' is that identity, which may differ from a target's own last-used one. 'account' is null when it is genuinely UNKNOWN – no saved MSAL record for that tenant and family (for example azcli / service-principal keep none); a null account is unknown, never signed-out. 'previousAccount' surfaces the target's last-used account as provenance ('was' / 'last opened as') – both when a different current account supersedes it AND when the current account is unknown, so a prediction is never invented from the last-used hint. Holds no credential. Use it to show 'as <account>' before connecting, or to confirm which identity a switch left in place. Read-only and free. Next: list_connections for the full target list; list_connection_history for the timeline.

Add columns with create_column/create_calculated_column; it needs a partition before it can be deployed/refreshed. Returns the new ref ('table:Name'). Undoable.

dataType: String|Int64|Decimal|Double|DateTime|Boolean (default String). sourceColumn is the underlying physical column name (defaults to the column name). Returns the new ref ('column:Table/Name'). Undoable.

Returns the new ref ('column:Table/Name'). Undoable.

Returns the table ref ('table:Name'). Undoable.

Returns the new object ref. Undoable. Pass displayFolder to create it already filed ('Parent\Child' nests) – create + folder is ONE undo step.

The expression is a lambda, e.g. '(x: INT64, y: INT64) => x + y'. Names cannot contain spaces. Requires model compatibility level >= 1702 (call set_compatibility_level first if needed). Returns the new ref ('function:Name'). Undoable.

calculated tables / field parameters), or calculation group (a deep clone). newName optional (collision-safe auto-name if omitted). targetRef optional: a 'table:' ref to clone a MEASURE onto another table, or a calc group's 'table:' ref to clone a CALCULATION ITEM onto another group – columns/hierarchies stay on their own table; tables duplicate at model scope. Returns the new ref. Undoable.

Deleting an absent ref is a net-zero no-op. DAX references to a deleted object are NOT auto-rewritten – they will error; check dependents first. Undoable.

ALL DAX references to it are automatically rewritten (safe rename). Returns the new ref. Undoable. (Report-layer bindings outside the model can't be updated – review for renames used in reports.)

name → a reference-aware RENAME (FormulaFixup rewrites every DAX/RLS reference); description/displayFolder/formatString → plain-text set; expression → replaces text INSIDE a DAX string-literal or comment only (validated for syntax); mExpression → literal M edit (with a warning – M is not reference-fixed); synonyms → updates the linguistic terms. HARD-BLOCKED: a match on a DAX identifier/reference or on DAX code – it returns the 'rename the object instead' hint rather than corrupting the formula. RLS filters are rename-only. This is a single, free, undoable edit. Pass spanStart/spanLen (from a hit's spans[]) to change ONLY that one occurrence; omit them to replace every occurrence in the field. preview=true rehearses: returns the same before/after + warnings (+ .references blast radius for a rename) WITHOUT mutating, and reports a safety refusal in .blocked instead of throwing. Returns before/after, the (possibly new) ref, and any warnings (e.g. M references the old name). For MANY matches at once, use propose_replace + apply_plan instead.

The change is applied to the live shared session, appears immediately in the VS Code UI, and is a single undoable step.

Deterministic, undoable. For a DYNAMIC (per-filter-context) format that switches by magnitude/sign/currency, use set_measure_format_expression. Browse curated strings with list_format_templates.

This is how magnitude-adaptive scaling (500->'500', 5e6->'5M'), per-currency, per-selected-measure, and duration/bps formats work on a plain measure (a static string can't). Pass an empty string to clear it (the measure falls back to its static/model format). A non-blank expression AUTO-CLEARS any static format string. Requires model compatibility level 1601+. Undoable. (For a static literal use set_measure_format; browse ready-made expressions with list_format_templates.)

Each has an id, category, name, kind ('static' literal | 'dynamic' DAX expression), the format string, a sampleInput->exampleOutput, a 'common' flag (~20 pinned), and any credit/pack. Apply a STATIC template with set_measure_format (measure) or set_calc_item_format_string (a quoted literal on a calc item); apply a DYNAMIC one with set_measure_format_expression (measure) or set_calc_item_format_string (raw expression on a calc item). Read-only; works with no model open. Use this instead of guessing glyphs / scaling-commas.

Only applies to physical/source columns (a calculated column derives its type from its DAX). Undoable.

Use None for keys/years/codes. Deterministic, undoable.

Helps Copilot/maps. Deterministic, undoable.

Deterministic, undoable.

Keep it <=200 chars and front-loaded – Copilot truncates. Applies as a reviewable, undoable change tagged as the agent. Use after get_grounding.

Hidden columns are excluded from Copilot/Q&A/data-agent grounding – hide technical/key/FK columns. Deterministic, undoable.

A display folder is just the DisplayFolder string on each member ('Parent\Child' nests) – it has no existence of its own, so an EMPTY folder cannot persist: create one by moving/creating a member into it. All-or-nothing: any bad ref rolls the whole batch back. For a single object set_property(DisplayFolder) works too; this op keeps a multi-object gesture to one undo step.

toPath may be nested ('Parent\Child') to move the folder; empty toPath removes the folder level (members are promoted). Fails with a teaching message if no member is in fromPath (folders exist only through their members).

value is the string form: 'true'/'false' for bool, the enum NAME for enum, the number for numeric. Setting 'Name' renames (DAX refs auto-rewritten). Undoable.

Same value encoding as set_property. ALL-OR-NOTHING: if any object lacks the property or the value is invalid, NOTHING changes and the error names the object; one undo reverts the whole batch. Use set_property for a single object.

format: 'dax' (annotated expressions for measures/calc columns/calc tables/calc items/UDFs), 'tmdl' (per-object TMDL – the model's native, readable on-disk format; the preferred export), or 'tmsl' (createOrReplace JSON; TMSL's unit is the table/role, so a child object scripts its containing table – deduped to containers). Pass several refs to capture a whole batch (e.g. all of a table's measures) in one document. Unresolvable refs are skipped.

Lets you bulk-edit many measures/calc columns/calc items in one document and commit together. Refs that don't resolve or aren't DAX-expression objects are skipped and reported. Returns {applied[], skipped[]}.

Existing table/role documents and individually scripted measures round-trip through TOM's native partial-update path in ONE undoable batch. Measure ownership is pinned by the emitted // @object ref; changing its header/parent is refused (use rename_object/create_measure for structural changes). A brand-new top-level object is skipped (use its typed create op). Returns {applied[], skipped[]}.

crossFilter: OneDirection|BothDirections (optional). isActive optional. Returns the new ref ('relationship:Name'). Undoable.

Only ONE active relationship can exist on a given path between two tables – inactive ones are reached on demand via USERELATIONSHIP in DAX (e.g. role-playing date relationships like Order Date vs Ship Date). isActive=true activates it, false deactivates it. Deterministic, undoable.

fromCardinality is the FK/from side, toCardinality the lookup/to side; each is 'Many' or 'One' (a null/empty end is left unchanged). A normal star-schema relationship is Many→One. Use this to fix a mis-shaped relationship in place instead of deleting and recreating it. Deterministic, undoable.

Prefer OneDirection in a star schema – bidirectional can confuse AI filter context. Undoable.

Returns the new ref. Undoable.

Add members with set_perspective_member; delete with delete_object and rename with rename_object. Returns the new ref ('perspective:Name'). Undoable.

The object ref is a table/column/measure/hierarchy. Including a TABLE cascades to all its columns/measures/hierarchies. Undoable.

Read-only.

Add calculation items with create_calculation_item. Requires compatibility level >= 1470. Returns the new ref ('table:Name'). Undoable.

The expression typically uses SELECTEDMEASURE(), e.g. 'CALCULATE(SELECTEDMEASURE(), DATESYTD(...))'. Returns the new ref. Undoable.

Read-only – author with create_calculation_group / create_calculation_item / set_calc_group_precedence / set_calc_item_format_string.

Give each calc group a distinct precedence so their combination order is deterministic. Undoable.

Pass an empty string to clear it (the item falls back to the base/model format). Undoable.

Builds the full Power-BI-Desktop-identical structure (the 3 columns, the ParameterMetadata marker, sort-by, hidden plumbing columns, and the field-switch key). Items are measure/column refs in display order; each label defaults to the object's name. Requires a Power BI-mode model at compatibility level >= 1400. Returns the table ref ('table:Name'). Undoable.

Needs compatibility level >= 1400. Referenced by NAME from create_directlake_table or inside an M expression. Returns the data source name. Undoable. (Credentials are supplied out-of-band at refresh – none are stored here.)

Bundles the table + its M partition (no orphaned placeholder). Add columns with create_column. Returns the table ref ('table:Name'). Undoable.

Needs compatibility level >= 1604. Bind it to a source created first with create_named_expression (M to the SQL endpoint) OR create_data_source (structured), referenced by name. Returns the table ref ('table:Name'). Undoable.

Returns the expression name. Undoable.

Undoable.

RangeStart/RangeEnd parameters show here. Edit one with update_named_expression, create with create_named_expression.

Read a partition's M with get_partition_m, edit it with set_partition_m.

Errors if the partition is not an M source (e.g. a Direct Lake Entity or DAX calculated partition).

Use to add an incremental-refresh RangeStart/RangeEnd date filter, or to edit the query. Undoable.

Types: Full (reload + recalc, the default), DataOnly (reload, no recalc), Calculate (recalc only), ClearValues (empty it – destructive), Automatic (refresh only if stale), Add (append rows). LIVE DATA WRITE against the Analysis Services engine – runs as a DRY RUN by default (reports what would run, connects to nothing); pass commit=true to actually execute. Leave endpoint EMPTY to target the live model this session was opened from (open_live/open_local binds it); a file model has nothing to refresh. See list_refresh_types for full explanations.

Read-only – use it to pick a type for refresh_partition.

Returns enabled=false if no policy is defined. Read-only.

Set autoWire=true to create or repair RangeStart/RangeEnd and append the required half-open date filter without replacing existing M steps. Leave it false to validate and refuse when prerequisites are missing. Metadata only; it does not refresh data. Deterministic and undoable. Existing-policy fields are preserved when omitted.

Leaves RangeStart/RangeEnd and the partition M intact. Deterministic, undoable.

Returns the source columns mapped to TOM types (String|Int64|Decimal|Double|DateTime|Boolean). Needs a reachable source: for an OFFLINE snapshot, a non-SQL source, or a native-query partition it returns Reachable=false with a clear message (never throws). Use diff_schema to compare against the model.

Each item carries a stable id for per-item selection. By default it probes the live source (like get_source_schema); pass sourceColumns to diff a SUPPLIED/synthesized schema instead (the offline/manual path – no connection needed). Calculated columns are never flagged (they're DAX-derived, not source-driven). Returns Reachable=false + a message when the live source can't be read. Feed the accepted items to apply_schema_update.

Each item: {change: Added|Removed|TypeChanged, column, dataType? (TOM type, for Added/TypeChanged), sourceColumn? (physical name for Added, defaults to column)}. Items that can't apply (a calculated column, a name clash, an unknown column) are SKIPPED with a reason – the accepted changes still commit atomically. Returns per-kind counts + the applied/skipped lists.

Enables calendar-aware DAX: TOTALYTD(expr, '<calendar>'). A table can hold several calendars (Gregorian + Fiscal + ISO…) over the same columns. One undoable step; persist with save_model. Requires CL 1701+ (set_compatibility_level).

Templates: gregorian (Year/Quarter/Month/Day + name-by-number sort pairing) · fiscal (fiscalStartMonth, FY labeled by ENDING year) · iso (ISO-8601 weeks, Thursday rule) · 445 (4-4-5 retail periods over ISO weeks) · 13period (13 four-week periods). Targets an existing table with a date column (dateColumn, auto-detected when unambiguous), or creates a fresh CALENDAR() calculated table when tableName doesn't exist. The week-based templates (iso/445/13period) share ISO scaffolding columns so they coexist on one table. Requires CL 1701+.

Undoable.

Pure offline metadata read – no connection needed. Also reports whether the model's compatibility level supports calendars at all.

Undoable.

For calendar-based time intelligence (CL 1701+, the modern approach with calendar-aware DAX like TOTALYTD(expr, 'Fiscal')), prefer define_calendar_from_template. Defaults: name 'Date', range 5 years back to end of this year. Columns materialize on deploy/process. Undoable.

Default suite: YTD, QTD, MTD, PY (prior year), YoY, YoYPct. Additional opt-in variants (pass in 'variants'): ROLL12/R3M/R6M (rolling 12/3/6-month windows), SPLY (same period last year), PYTD (prior-year YTD), PM (prior month), MoM + MoM% (month-over-month delta and %). Undoable.

Required for good time-intelligence and Copilot date handling. Deterministic, undoable.

modelPermission defaults to None (Read is auto-applied once you add an RLS filter). Then use set_table_permission to add per-table row filters and set_role_member to add members. Undoable.

Undoable.

RLS gates what data a Copilot / data-agent persona can see, so it matters for AI grounding.

add=true adds, add=false removes. NOTE: adding members is blocked on a governed Power BI model (V3Restricted) – members are then managed in the Power BI service; removing/listing always works. Undoable.

Undoable.

Pass an empty filter to remove it. Setting a filter auto-promotes the role's permission from None to Read – the result echoes the resulting ModelPermission and a Promoted flag so the elevation is explicit. RLS row-filters cannot target a calculation group. The filter is a DAX expression and participates in rename fixup. Undoable.

'None' hides the column from the role; 'Read' grants it; 'Default' removes the override (visible). Requires model compatibility level >= 1400 (errors clearly below). Surfaced via list_roles → ObjectPermissions[].Columns. Undoable.

'None' hides the table's metadata + data from the role; 'Read' grants it; 'Default' removes the override (visible). Requires model compatibility level >= 1400 (errors clearly below). A calculation group cannot carry OLS. Surfaced via list_roles → ObjectPermissions. Undoable.

Returns {error} if not connected or the query fails. Read-only. A ROW-returning query (`EVALUATE <table>`, SUMMARIZECOLUMNS, FILTER, VALUES, TOPN, …) reads source rows, so the agent policy's QueryData rule applies to the connected target – an Ask refusal names the approval to request; a Deny means the target's policy forbids it (a human can run it or change the policy). A scalar probe (EVALUATE ROW(...) / EVALUATE { … }) is a calculation and is never gated.

Read-only.

Accepts a table name or a 'table:Name' ref. Requires a live connection. Reads DATA rows, so the agent policy's QueryData rule applies to the connected target – an Ask refusal names the approval to request; a Deny means the target's policy forbids it (a human can run it or change the policy).

Catches unbalanced brackets (error) and unknown table/column/measure references (warning), with line:column. Offline/read-only – no live engine needed. Valid=false only on a structural error.

With an open session the table-identity rules activate (bare-table filter). Token-based, so comments / strings / [bracketed names] never false-fire. Read-only, free, advisory per-expression – the model-scored layer is the AI-readiness BestPractice category (ai_readiness_scan). Run it on a rewrite before applying.

Use it to measure a query/measure BEFORE and AFTER an optimization to prove the rewrite is actually faster. Read-only.

This is the way to prove an optimization helps the worst case. Needs a local Power BI Desktop or admin XMLA endpoint for the cold runs + SE split; on a shared/cloud endpoint pass confirm=true to allow clearing (it affects all users) or it degrades to warm-only. Read-only.

Use it to understand WHY a query is slow (FE-bound vs SE-bound) when optimizing. Needs a local Power BI Desktop or an admin XMLA endpoint; falls back to wall-clock only otherwise. Read-only.

Use it alongside profile_dax when a query is FE-bound (a tall physical plan / huge intermediate records points at the costly operators). Needs a local Power BI Desktop or an admin XMLA endpoint; degrades to 'unavailable' otherwise. Read-only.

NON-DESTRUCTIVE: it only evicts the cache (the engine rebuilds it on the next query); no data or metadata changes. SAFETY: on a SHARED/cloud endpoint this evicts the cache for ALL users (their next queries run cold), so it is REFUSED there unless you pass confirm=true. Needs a local Power BI Desktop or an admin XMLA endpoint.

Wrap the sub-expressions you want to inspect in EVALUATEANDLOG to see what they actually evaluate to. Needs a local Power BI Desktop or admin XMLA. Read-only. The logged intermediates can include row samples of any table, so the agent policy's QueryData rule applies to EVERY call on the connected target (regardless of the outer query shape) – an Ask refusal names the approval to request; a Deny means the target's policy forbids it (a human can run it or change the policy).

Returns long-form rows the caller pivots into a row x column matrix. Use it to sanity-check a measure's values by category/date before trusting it. Read-only; requires a live connection. Returns rows of source grouping values, so the agent policy's QueryData rule applies to the connected target – an Ask refusal names the approval to request; a Deny means the target's policy forbids it (a human can run it or change the policy).

Returns observed column and table bytes, component bytes, encoding, an observed-denominator percentage, and an explicit storageMode. Import mode establishes complete model totals, directLake is resident-only, and unknown leaves completeness unconfirmed. Requires a live connection.

Writes the model METADATA (tables, columns, measures, relationships) – works offline. Storage statistics (column sizes / cardinality) require a processed/live model and are not included yet. Returns the path, table count, and a note; door-safe (a bad path returns .Error rather than throwing).

Freezes the MEASURED values of the object's blast radius – the lineage-downstream measures, evaluated BY REFERENCE over the SUMMARIZECOLUMNS(groupBy) grid you supply – into a session-held baseline, and returns a captureId. After the edit, compare_baseline re-evaluates the same grid and reports exactly which numbers moved. Pass representative groupBy columns: a grand-total-only baseline is thin evidence (disclosed in the result). Over-cap measures are listed in Skipped, never silently dropped. CERTIFIED TOTALS (month-end close): pass a `label` (the period, e.g. "close FY26 · July") to also PERSIST this capture beside the model as a certified baseline – one control total per call (objRef = the measure, filters = its stated context, includeDependents:false), all under the same label. That certified set survives the session, so a later refresh or edit that moves a signed-off number is caught by compare_baseline(label:…). Free; needs a live connection (a baseline is measured values, not metadata).

Safe=true only when everything is unchanged, nothing is missing/errored, AND coverage wasn't truncated – honesty first. IMPORTANT: it reads the LIVE model, so run it AFTER the edit is deployed (deploy_live) – an undeployed local edit is not validated (the result discloses session edits since capture). CERTIFIED TOTALS (month-end close): pass a `label` instead of a captureId to re-check that period's PERSISTED certified figures – each is re-evaluated at ITS stated context and reported held / moved (old→new) / missing / not-checkable, so drift from what was signed off is named. Detection, not prevention: it cannot stop a refresh or an out-of-tool edit, only report what moved. The verdict is recorded in the Verified Edits audit trail. Free; needs the live connection.

DAX context-dependence bugs (missing time-intel guards, blanks, non-additivity) are INVISIBLE until you run the measure in different contexts. It replicates a real visual (SUMMARIZECOLUMNS with your filter args as the OUTER/slicer context + a group-by axis) so ALLSELECTED / SELECTEDVALUE / ISINSCOPE resolve correctly – a naive one-context test lies about those. Pass a primaryAxis to auto-generate grand/single/multi/empty/boundary scenarios, and/or scenarios[] for cross-filter cases (name columns + members; do NOT hand-write DAX). Reports BEHAVIOR across contexts, NEVER 'correct' – you judge it against intent. Read-only; needs a live connection.

The extra shapes matter: SUMMARIZECOLUMNS leaves pin every dimension, so a wrong-SCOPE rewrite (wrong denominator, collapsed context transition, over-broad ALL/ALLEXCEPT) can match at every leaf yet diverge at a subtotal or the grand total – this gate catches that. ALWAYS run it (over a representative group-by matrix) before replacing a measure with an optimized version. Read-only.

Give >=2 candidate DAX rewrites; the engine validates each, checks each returns identical values to the current body across the SUMMARIZECOLUMNS(verifyGroupBy) matrix YOU supply, benchmarks only the ones that matched (warm wall-clock over that same grid – not a server SE/FE trace), and applies the fastest that beats the current body beyond a measured noise band – recording the proof + benchmark as evidence. Equivalence is only as strong as verifyGroupBy: a grand-total-only match is downgraded to unverified (not accepted), so pass representative group-by columns. REFUSES to finalize without >=2 candidates, without a live connection, or with nothing proven (correctness always gates speed – a faster-but-wrong candidate can never win). Prefer this over update_measure for rewrites/optimization. Auto-apply is Pro; on free it returns the full evidence (paused) so you can apply the winner with update_measure. Needs a live connection (open_live / open_local).

Session-scoped (resets on reconnect). 'available' = whether the tier can turn it on (Pro). Check this so you know whether an edit will be gated.

When ON, single-edit DAX (set_dax + create measure/calc column/calc table/calc item/function) is strictly validated before it commits – invalid syntax or unknown table/column/measure refs refused (validity only, not an equivalence proof). This is the human's guarantee switch – turning it ON is a Pro feature (returns a Pro-required error on free); turning it OFF is always allowed. Prefer the human sets this; if you turn it off, do so deliberately.

Each record links the previous by hash, so the trail self-checks: ChainIntact=false (with FirstBrokenSeq) means a record was edited, removed, or reordered after it was written. Read-only, free.

Read-only. Pro.

HONESTY RULES: contributors ship ONLY when the parts provably sum to the total (distinct counts / ratios / min-max / semi-additive measures get an explicit refusal, never a misleading breakdown); RLS is listed as roles that WOULD filter these tables (the engine cannot impersonate a role, so never 'computed under role X'). Describe the cell with filterContext: Filters = column+members (a pivot cell's row/col keys are single-member filters), ExtraPredicates = raw DAX boolean lines (page-filter style). OFFLINE the dossier degrades to chain/lineage/RLS with Evidence.Available=false – connect (open_local / open_live) for the value, blank checks, and breakdown. Next steps: probe_measure to test the measure across MANY contexts; blame_value to ask what CHANGED a number over time. Free, read-only.

The engine ambiently snapshots the top measures' values + their whole DAX dependency-cone expressions at checkpoint moments (apply_plan / optimize_measure / deploy_live / save_model – Pro, automatic); this op finds the most recent movement of a measure (or since a given point) and attributes it HONESTLY: verdict 'attributed' when exactly ONE recorded edit sits in the window; 'interval' when several do – candidates come RANKED by dependency overlap (formula-changing edits first) and are a ranking, NEVER a causal claim; 'data-suspected' when every formula is identical but the value moved (data/refresh is the suspect – proving it needs a shadow pre-edit instance, which v1 does not keep); 'inconclusive' when the history can't answer. Formula-caused movement is proven by a deterministic expression diff of the dependency cone between the two points (ExprDiffs). Pro (soft: free tier gets Status='pro' + how to do it by hand for free). Read-only.

Points with a null value are honest gaps: the formulas were snapshotted but the number wasn't observed there (offline capture, or the edit's impact cone never reached the measure). Truncated=true means retention pruned older points (last 200 checkpoints / 20MB) or unreadable lines were skipped. Pro (soft: free tier gets Status='pro' + the manual free alternative). Read-only.

Each finding is tagged SafeFix (deterministic), AiContent (you generate it), or Proposal (human review). On a LARGE model call ai_readiness_summary first, then filter here. Optional filters: category (e.g. 'Naming','Descriptions','DataAgentConfig'), severityMin ('Info'|'Medium'|'High'|'Critical' – keep this severity and above), maxFindings (cap the returned findings; 0 = all, the default – capping is explicit so nothing is hidden silently). Scores/categories/counts are always for the FULL model; only the returned findings list is filtered.

Requires a live connection (connect_xmla / connect_local) – read-only. Use this instead of ai_readiness_scan when connected to grade scale/cardinality too.

Returns the A-F grade + 0-100 overall, per-category score/applicable/violations, coverage KPIs, gating reasons, the total finding count, and counts by severity / fix-kind / top rule – WITHOUT the (potentially large) findings list. Token-light regardless of model size. Then call ai_readiness_scan with a category or severityMin filter to pull only the findings you'll act on.

Iterate the queue: for each, author a description/name and call set_description (renames need review). Re-scan when done.

Supports VIS-FK (hide a foreign-key column), FMT-SUMMARIZE / SUMMARIZE-DIMENSION (SummarizeBy=None), CAT-GEO (geographic data category). For content findings use get_fix_prompt + the matching tool instead. Undoable.

No renames, no generated content.

Useful when iterating a scorecard's findings.

Uses the bundled Power BI standard ruleset merged with any rules embedded in the model (load your own with load_bpa_rules / clear them with reset_bpa_rules). Returns violations (rule, category, severity, object, message) flagged CanAutoFix (deterministic) or not. For AI-specific readiness use ai_readiness_scan instead. On a LARGE model call bpa_summary first, then filter here. Optional filters: category, ruleId, autoFixableOnly (true = only deterministically fixable), maxViolations (0 = all, the default; capping is explicit so nothing is hidden silently). RuleCount/ViolationCount/AutoFixable are always for the FULL model; only the returned violations list is filtered.

Rule count, total violation count, auto-fixable count, any rule errors, and violation COUNTS by category / rule / severity – WITHOUT the (potentially large) violations list. Then call bpa_scan with a category / ruleId / autoFixableOnly filter to pull only the violations you'll act on (or bpa_fix_all for all deterministic fixes).

For non-auto-fixable rules use bpa_get_fix_prompt. Undoable.

Does not touch content/naming rules (those need bpa_get_fix_prompt).

This is how Semanticus exceeds Tabular Editor: every rule is fixable – deterministically or by you.

They layer on TOP of the bundled Power BI standard ruleset and are persisted on the model (so they travel with it and are undoable). replace=false MERGES with any rules already on the model (by id); replace=true sets the model's custom rules to exactly this set. Use reset_bpa_rules to clear them. Returns the new active rule counts.

Undoable.

Schema: array of {ID, Name?, Category (an EXISTING readiness category: Naming|Descriptions|Synonyms|Relationships|Visibility|Formatting|CopilotLimits|DataAgentConfig|BestPractice), Severity? (Info|Medium|High|Critical, default Medium), Scope (same vocabulary as BPA rules, e.g. Measure/Column/Table), Expression (violation predicate – same expression language as BPA rules), AppliesTo? (population filter: Applicable = objects matching it; an EMPTY population leaves the rule dormant, never inflating its category), Message?, Description?, FixKind? (None|AiContent|Proposal – advisory; SafeFix is refused)}. Rules are validated strictly against the open model BEFORE anything is written (preview first with validate_rule). Merged by id with the model's existing custom rules (replace=true swaps them); a built-in rule id is refused – custom rules can never override built-ins or register hard gates. Findings from these rules are tagged custom:true; waivers work on them like any finding. reset_readiness_rules clears them.

Undoable.

kind='bpa' or 'readiness'; rules = inline JSON (one rule object or an array, the same schema the matching load op accepts). Per rule you get: compile errors from the real expression parser (with the failing position), the would-be Applicable population, the violation count, the first few flagged object names, and a dormant flag (empty population = the rule would never move a score). Save with load_bpa_rules / load_readiness_rules once valid.

Read-only; the manage view behind the Studio 'Custom rules' panels.

system: 'bpa' or 'air'. objRef set = waive THIS instance (free); objRef empty/'*' = waive the ENTIRE rule, every instance model-wide (the bulk lever – Pro). A reason is REQUIRED: a waiver is an audited decision (stored with who+when on the model), never a silent suppression – the finding is still surfaced (tagged 'waived' with its reason) and the scorecard reports a waived count, so the grade is honest. Hard gates (Q&A scale ceiling, >50% measures undescribed) are NOT lifted by waivers. Persisted on the model (undoable, travels with it); per-instance BPA waivers also write Tabular Editor's BestPracticeAnalyzer_IgnoreRules so TE3 honours them. Re-scan to see the score move.

system: 'bpa' or 'air'. objRef set = un-waive that instance; empty/'*' = remove the rule-level waiver. Never gated (it makes the model more compliant). Undoable; also clears Tabular Editor's ignore annotation for a per-instance BPA waiver.

The audit trail behind the scorecard's waived count.

Packs are BOUND to the model they were authored against, so `questions` is THIS model's pack only; `otherModelQuestions` and `unattributedQuestions` (legacy, saved before binding, in a shared store) are surfaced separately and are NOT run against the open model. The pack lives in plain JSONL (`.semanticus/interview/questions.jsonl` beside the model; '~/.semanticus/interview/' for scope 'global') – the user's own data. Reports the count of any corrupt lines it skipped (the store never bricks). Free, read-only.

HIGH PRECISION by design: offline, an erroring query, a truncated comparison, or a missing oracle all come back Unverified – never a fabricated pass, never a fabricated 'wrong'. Pass `questionId` (from list_interview_questions; the outcome is also recorded on the saved question) OR `inlineJson` (the same fields add_interview_question takes – a one-off, nothing persisted; this is the FREE path). An inline value-tier question MAY omit the oracle: it executes and comes back Unverified with the computed number in the detail – the confirm-and-record flow for seed candidates (confirm the number with the user, then add_interview_question with expectedValue; persistence still REQUIRES the oracle). Refusal tier: pass abstained=true if you (honestly) declined to answer, or attemptDax with the DAX you produced – producing any answer to an unanswerable question is the failure being caught. On SilentlyWrong the result carries fixRuleId + a plain fixHint naming the readiness fix that prevents it. Needs a live connection for the value/paraphrase tiers (open_live/open_local). A saved questionId that belongs to a DIFFERENT model (or is unattributed) is refused – its oracle was authored against another schema, so grading it here would be misleading.

One-off checks stay FREE – run_interview grades an inline question without saving. Fields by tier – 'value': `query` (a FULL EVALUATE, e.g. EVALUATE ROW("v", CALCULATE([Total Sales], 'Date'[Year]=2024))) + `expectedValue` (the trusted number, confirmed by the user or a verified answer) or `expectedMatrixJson` (rows, order-insensitive); 'paraphrase': `scalarExpr` + `paraphraseExpr` (the SAME question answered two ways as SCALAR expressions – not EVALUATE queries) with optional `groupBy`/`filters` for a per-context proof; 'refusal': just the question – it asserts the model CANNOT answer it, so an assistant that produces a number is confidently wrong. `fixRuleId` maps a failure to the AI-readiness rule that prevents it (a data-table fallback applies when omitted). `seedSource` records where the question came from ('user' | 'claude' | 'verified-answer'). Validation is fail-loud so a saved question is always runnable.

Use it to retire a question whose business definition changed. Free.

Pack templates bind ONLY to objects that exist (a marked date table, a measure to target, related dimensions...); every unbindable template is listed as skipped with the exact missing shape. NO candidate carries a trusted answer and none is fabricated: run the candidate's query, have the user confirm the number, then save it with add_interview_question (expectedValue = the confirmed number; the literal BLANK records a no-value answer; seedSource 'verified-answer' | 'hard-pack'). Free, read-only.

Call once before set_synonyms. Pass null culture for the default (en-US). On an existing schema it self-heals: entities bound to hidden or deleted objects are pruned, and any visible-name collisions Q&A can't distinguish are surfaced as a warning.

Auto-enables the linguistic schema if needed. Helps Copilot/Q&A map natural language to the right field. The linguistic schema requires conceptually UNIQUE names: hidden targets are refused, entities bound to hidden or deleted objects are pruned automatically, and a write that would collide two names under Q&A term matching fails with the objects named.

Pass empty/null to clear. Max 10,000 chars (the service ignores anything beyond; the call is rejected if over). Auto-enables the linguistic schema if needed; the write is round-trip verified, live in the shared session, and a single undoable step. CAVEAT: for a DEPLOYED model an LSDL edit syncs to the service only after a model refresh – it is not instant. Persist to disk with save_model.

Read-only. Call BEFORE editing instructions so an append/update doesn't clobber what's already there.

included=false EXCLUDES it (marks it Hidden in the LSDL); included=true restores it. Excluding noise (keys, sort/helper columns, intermediate measures) sharpens AI answers without hiding the field from report authors. Auto-enables the linguistic schema if needed; round-trip verified, live, a single undoable step. CAVEAT: for a DEPLOYED model the LSDL edit syncs only after a model refresh. Persist with save_model.

Call this before set_description.

Use it to trace where a field comes from and what flows from it. NOTE (Phase 1): model-only – published-report field usage is not yet included (see .Caveat).

Returns the impacted set with BFS depth + counts by kind. Call BEFORE editing or deleting a measure/column. NOTE (Phase 1): downstream published reports/visuals are not yet included (see .Caveat).

direction='dependsOn' (default) lists what its DAX consumes – check before editing; direction='dependents' lists what REFERENCES it – check before delete_object/rename_object to see what would dangle. Returns each ref/name/kind; empty when the object has no DAX edges.

CONSERVATIVE – a column used by a relationship, hierarchy, sort-by, or RLS is never listed. Tri-state verdict per item: 'safe' (nothing references it), 'usedByUnusedOnly' (referenced only by other unused/dead objects – surfaced with BlockedBy), 'caution' (report read failed – Phases 2-3). IMPORTANT (Phase 1): MODEL-ONLY – a field used ONLY by a published report (not by any model object) will still appear here; verify report usage before deleting (see .Caveat).

The safe set is RECOMPUTED server-side and each item RE-VERIFIED at apply time – an item whose status changed since your scan (something now references it) is SKIPPED with the reason, never deleted stale. refs (optional) narrows the sweep to those candidates from unused_objects/analyze_reports; omit to remove every currently-safe item. reportPaths (optional, local PBIR – same forms as analyze_reports) makes the verification report-aware, so a field a report displays is never removed. Returns removed[] / skipped[{ref,reason}] / count; writes ONE audit record with the evidence; undo_change reverses the whole sweep in one step. Removing MORE THAN ONE item at once is Pro – each item can be deleted one at a time free (delete_object).

This closes the model-only blind spot where a descriptive column a report displays – but no measure references – wrongly looks unused. Report field references are reconciled to the open model BY NAME (the model must be the one the reports bind to). Offline (local files); the cloud 'Get Report Definition' path will reuse the same parser. Legacy .pbix / RDL are not parsed yet (reported as unreadable → result stays model-only with a caveat).

Fetches each report's PBIR via the Fabric 'Get Report Definition' API, reconciles its field usage to the OPEN model BY NAME, and recomputes safe-to-remove EXCLUDING any field a report uses. reportIds empty = every non-paginated report in the workspace. Behaviour is READ-ONLY (Semanticus never modifies the report), BUT getDefinition requires a WRITE-CAPABLE Fabric scope (Item.ReadWrite.All / Report.ReadWrite.All) + the Contributor role – so you MUST pass consent=true to acknowledge that (tell the user first). Per-report failures (paginated/RDL, a report blocked by an encrypted sensitivity label, a download error) are reported as unreadable with a reason – never silently dropped, so 'safe' is never overstated. A model must be open and must be the one these reports bind to.

The datasetId tells you which reports bind to a given semantic model – match it to the open model to find the reports that use it. reportType 'PaginatedReport' = RDL (its field usage can't be parsed). Live read against api.powerbi.com using your Entra identity. Read-only. Pair with analyze_cloud_reports to close the safe-to-remove blind spot using real published-report usage.

Returns the transitive TOM blast radius, affected supplied PBIR reports/visuals, current-model saved Tests and Interview questions to replay, explicit coverage, unknowns, one five-word verdict, and the exact next op. scope='modelAndReports' is the honest default: without reportPaths it returns Unknown/NeedsReview, never green. scope='model' deliberately proves only model-internal impact. Free and read-only; it deliberately omits report contents and does not apply the change.

Review with get_plan, then apply_plan. scope null = whole model; 'table:Name' = just that table. This is the flagship: fix the whole model in one reviewed, undoable transaction.

Runs the same detailed search as search_model, then turns every replaceable match into the RIGHT KIND of plan item: name matches → 'rename' items (FormulaFixup rewrites every DAX/RLS reference at apply; renames are opt-in 'proposed'); description/displayFolder/formatString/synonyms → plain-text set items (pre-approved, safe); matches INSIDE DAX string literals/comments → 'set_dax' items spliced span-wise so reference spans are NEVER touched (opt-in – they change results; validated for syntax); M bodies → 'set_m' items (opt-in, literal, not reference-fixed). DAX-reference/DAX-code/RLS matches yield NO items – the view's .note reports them honestly (rename the referenced object instead). Items that cannot apply (name collisions, empty results) come back status='skipped' with the reason. REPLACES any current plan. Next: get_plan to review, set_plan_item to approve/reject, then apply_plan – one item is free; applying >1 at once is the Pro bulk primitive (the existing apply_plan gate).

Use it to see what still needs content (status 'needs_content') and what is approved/ready to apply.

kind is the operation: set_dax | set_description | set_measure_format | set_summarize_by | set_column_hidden | set_data_category | rename | set_synonyms | set_relationship_crossfilter | mark_date_table | set_ai_instructions (model-level: objRef is the model, after = the instructions text) | set_ai_data_schema (objRef a measure/column/table, after = 'Excluded' or 'Included') | delete (remove the object) | delete_if_unused (remove ONLY if unused_objects' safe verdict still holds at apply time – recomputed server-side, else the item is skipped with the reason). An identical pending item (same ref+kind+target+after) is deduped: the existing item is returned, not re-added. For a set_dax rewrite, ALWAYS pass verifyGroupBy so apply_plan PROVES equivalence (and skips it if results change). A set_dax item WITHOUT verifyGroupBy is added as 'proposed' (opt-in, like a rename) – it will NOT be applied unless you explicitly approve it via set_plan_item, and if applied it goes in UNVERIFIED. Nothing is mutated until apply_plan.

Authoring a value moves the item to 'approved' – EXCEPT the opt-in kinds (rename, set_dax without a non-empty verify matrix, set_m), which land on 'proposed' after ANY value revision (even one made after an approval – the consent covered the old value) and need an explicit approve. e.g. set_plan_item('ci-0007', after='Total revenue recognised in the period.'). Use get_plan to see item ids + grounding first.

Only approved items are applied – passing approvedIds narrows the approved set (it never applies rejected/proposed/needs_content items). DAX rewrites carrying a verify matrix are proven equivalent first and skipped if they'd change results or can't be proven; renames apply last. Returns a report: applied/skipped/failed counts + before→after BPA violations and AI-readiness grade. A single undo reverts everything; re-run propose_plan to iterate the tail.

Preview a create_measure / update_measure / rename_object / set_property / define_calendar before committing, or check whether an op WOULD fail – a rehearsal that finds the failure is still a SUCCESSFUL dry-run (WouldSucceed=false with the op's real teaching error). 'argsJson' is a JSON object of the op's arguments by name, e.g. {"tableRef":"table:Sales","name":"Margin","expression":"[Sales]-[Cost]"}. Entitlement gates stay ACTIVE (a Pro refusal is the real answer you'd get). DENIED (each refusal names the right path): external/system I/O + lifecycle (save_model/open_*/connect_*/refresh_partition/export_vpax/clear_cache/evaluate_and_log/benchmark_*), deploy/cloud/git/fabric/cicd/daxlib/data-agent (already commit-gated – run directly), the undo timeline (undo_change/redo_change), multi-mutate composites whose later steps read earlier writes (apply_plan/apply_safe_fixes/bpa_fix_all/make_model_ai_ready/apply_model_diff/cherry_pick/build_model_from_spec/apply_dax_script/apply_tmdl – use propose_plan / preview paths / apply one typed op), and workflow/knowledge/waiver bookkeeping. After a green rehearsal, run the op itself to apply.

A whole batch (apply_plan / bpa_fix_all / apply_safe_fixes / a generator) undoes as ONE step. The timeline is shared across both drivers, so this reverts the last change regardless of who made it (your edits or the human's in the VS Code UI). The revert is live – it broadcasts to the UI immediately. Returns CanUndo / CanRedo / AtCheckpoint. Use it to back out a change you just applied.

Live (broadcasts to the UI). Returns CanUndo / CanRedo / AtCheckpoint. Making a NEW edit after an undo clears the redo stack.

This is the same reference tree the VS Code compare/cherry-pick picker shows. Use it to enumerate the model's authorable objects in ONE call – to pick refs for model_diff / apply_model_diff / cherry_pick, or as a cheap structural map of what exists. Defaults to the OPEN model; pass sourceFile to read a model on disk instead. Read-only.

Returns an object-level diff (per table/column/measure/relationship/role/...: Create/Update/Delete) with each object's before/after text. Pass a different gitRef to compare against a branch/commit, or targetFile to compare against a model on disk, or sourceFile to compare two files. Read-only.

TARGET is either a model file on disk (targetFile) OR a PUBLISHED model on an XMLA endpoint (targetEndpoint + targetDatabase). SOURCE defaults to the open model; pass sourceFile or sourceGitRef to merge FROM elsewhere. DRY RUN by default (commit=false reports what WOULD apply – including any DELETES). Pass commit=true to write. selectedRefs limits to specific object refs (e.g. ['measure:Sales/Total']); omit to apply all differences. Preview and single-object commits are free; committing MORE than one object at once is Pro (same rule for every target). Pushing to a published model runs an ALWAYS-ON drift guard: if a target object changed since the diff, the push is REFUSED unless you pass overrideReason (recorded in the audit trail). Every committed push to a published model FIRST writes a restore point (returned as restorePointId) so it can be undone with rollback_push; if a push contains DELETES and the restore point cannot be written, the push is REFUSED. Next: run model_diff first to see the object refs; on a drift refusal, re-run model_diff to see the new state before overriding.

DRY RUN by default (commit=false reports what would copy, what already exists (would overwrite), and what can't). Pass commit=true to apply as ONE undoable batch. Source is a model on disk (sourceFile) or a git ref of the open model's repo (gitRef). refs are object refs like ['measure:Sales/Margin %']. Supported into the open model: measures, calculated columns, and calculation items (into an existing group). For a whole table or calculation group, use apply_model_diff to a file target instead.

Each entry shows step count, whether it is GATED (starting it needs Pro – enforcement is what's paid, reading is free) and any parse error (a malformed file is surfaced here, never hidden). Free, read-only.

Free: use it to follow a playbook manually, or to preview what start_workflow will enforce. To customise a stock workflow, copy it into `.semanticus/workflows/<name>.md` and edit – the user copy shadows the stock one.

Returns the run id plus step 1's full instructions and its gate questions – ask the USER those questions (do not invent answers), do the step's work with the normal tools, then submit_workflow_step. The engine – not you – evaluates each gate: required inputs must be answered or explicitly declined, and verify checks (probe / equivalence / BPA / readiness) run against the live model. Every transition broadcasts to the Studio UI; the finished run's full record (answers, declines, evidence) is appended to the experience log. Pro when any gate enforces; a workflow whose gates are all 'off' runs free.

Plus the CURRENT step's full instructions + unanswered questions. Omit runId for the most recent run. Free, read-only.

answers is a JSON object keyed by gate-input name: a value, or the explicit decline sentinel {"declined": true, "reason": "..."} (answer-or-decline inputs accept a reasoned decline; required ones do not). The ENGINE then runs the step's verify checks against the live model – a hard gate that fails blocks the step with the failure evidence (fix and re-submit, or skip_workflow_step with a reason); a warn gate records it and passes. Answers accumulate run-wide: a later step's probe can reference an input recorded earlier. On success you get the NEXT step's instructions.

The accountable-override shape: never a hard wall, never a silent bypass – the reason is recorded on the run and lands in the experience log with the terminal record. Prefer fixing and re-submitting over skipping a failed hard gate.

The partial record (steps passed, answers, declines, evidence so far) is preserved and appended to the experience log – an abandoned run is data, not a deletion.

The engine PARSE-VALIDATES FIRST: a file the parser refuses is never written and the parse error comes back verbatim – fix and retry. Saving a stock workflow's name creates your project's customised copy (it shadows the stock one). A workflow is a SKILL definition: gate-free = pure instructions (runs free); gates make it Pro-enforced. Free; broadcasts workflow/libraryDidChange so the Studio library updates live.

Stock workflows are read-only (deleting a customised copy reverts to the stock version). Free.

Parses the file (parse errors surface as usual), then statically resolves it against the live op surface and its own gate inputs: every triggers:/ops: entry must be a real op; every verify when/probe must name an input some gate collects; probe/equivalence (and object-scoped bpa_clean) verifies need a target objectRef input. Returns Ok plus info/warn findings (a distilled workflow's derived_from provenance surfaces as an info). Ok = parses AND no warn. Free, read-only.

Args come from the distilled workflow's `exemplar_answers` frontmatter (the L0 log has no op args; /distill-workflow embeds the exemplar). Each op is REHEARSED (dry_run ran – wouldSucceed + delta count, or the op's own error; the model is untouched, guaranteed rollback), SKIPPED-DENIED (deny-listed/unknown – not a failure), or SKIPPED-UNBINDABLE (a required param the exemplar can't supply – named). Returns Admissible = parses clean AND no rehearsed op would fail. Deliberately does NOT: execute live DAX probes (marked replayable – they need a connection), touch the model, or run sidecar/bookkeeping ops. No exemplar → replay is SKIPPED with an instructive note, never a failure. Free, read-only.

Free, read-only.

null mode = no override (each workflow's own strictness applies, engine default hard); 'off' = every gate is skipped (runs record no verified evidence and gated runs start without Pro); 'warn'/'hard' force that strictness everywhere. Free, read-only.

mode='off' disables every gate – for quick tasks where the user explicitly doesn't want enforced workflows; mode='default' (or null) restores per-definition strictness; 'hard'/'warn' force that level everywhere. Sits at the TOP of the strictness resolution (above per-gate and per-workflow overrides), is persisted in .semanticus/workflow-settings.json beside the model, and re-broadcasts the library so both doors see gated flags flip. Ask the user before turning enforcement off – it is their accountability lever, not yours.

Disabled = hidden from the run picker and refused by start_workflow, but STILL listed (marked enabled:false) so it can be re-enabled. Persisted in .semanticus/workflow-settings.json beside the model (git-tracked, so the curation travels with the repo) and re-broadcast to both doors. Orthogonal to strictness (how hard gates bite) and to whether a workflow is required for a task. Free – curating your menu is content.

require is the allowed workflow set (you pick among them by whenToUse); mode 'hard' REFUSES the bare op and steers you to start_workflow, 'warn' allows it but records a compliance advisory, 'off' (or an empty require) CLEARS the binding. The bare op is exempt only while an active run of a required workflow is AT a step that performs it (start-and-freestyle does not satisfy the mandate). Persisted in .semanticus/workflow-settings.json beside the model (git-tracked, so the mandate travels with the repo) and re-broadcast to both doors. Independent of the strictness kill-switch – a mandate is whether you must ENTER a run, not how hard its gates bite. Pro for 'hard'/'warn' (mandatory routing is the enforcement); clearing is free unless the binding is locked team policy. get_workflow_policy shows the current rules.

e.g. show 'deploy-freeze-guard' only during the month-end window, or 'prod-checklist' only on the prod workspace. `when` is a plain condition over facts the engine knows – date (date.monthEndOffset >= -3, date.dayOfMonth >= 28), connection (connection.workspace ~ '*prod*', connection.kind == 'xmla'), git (git.branch == 'main'), the model (model.tableCount > 50, model.hasRls == true, model.readinessGrade < 'B'), or the session (session.tier == 'pro') – joined with && / || (no parentheses; split into separate rules for grouping). set='on' shows it only when the condition holds; set='off' hides it then. Passing neither `when` nor `set` CLEARS the rule (it shows normally again). Activation CURATES the menu – it is NOT a lock: a hidden workflow is still startable on demand, and a workflow REQUIRED by a binding is always shown. Persisted in .semanticus/workflow-settings.json (git-tracked) and re-broadcast to both doors. Pro (writing a rule); reading the menu/policy is free. get_workflow_policy shows the current rules + any contradictions.

Token-lean (no step bodies): read it BEFORE authoring so you self-route into a required workflow instead of hitting a mandate by rejection. Free, read-only.

A profile is one reviewed bundle of menu, requirement and check-strength settings. Free, read-only. Use activate_workflow_profile to apply one atomically.

Solo analyst clears prior menu rules, requirements and automatic visibility rules. Team and Consulting profiles require Pro because they make workflows required. The settings remain source-controlled and any later manual policy edit marks the profile Custom.

Every step, instruction, declared action, answer or explicit decline, gate result, effective strictness, skip reason and abort reason is preserved. The run is bound to the model that owned it and is refused from a different model. Omit runId for the most recent run. Free, read-only; starting an enforced workflow remains the existing Pro boundary.

A template is NOT a runnable workflow: it has declared SLOTS you fill once (your KPI dictionary, your close checklist, your freeze window) and instantiate into a concrete workflow. Each entry shows the slot count + names and any parse error (surfaced, never hidden). Free, read-only. Next: get_workflow_template to read one, instantiate_workflow_template to fill it in.

Free, read-only. To fill it in, collect a value for each slot (ask the user the slot's question verbatim) and call instantiate_workflow_template.

valuesJson is a JSON object keyed by slot name (ask the user each slot's question – do not invent org process). The engine renders by DETERMINISTIC text substitution (no inference), then enforces the STRUCTURE-PRESERVING INVARIANT: it renders once with your values and once with dummy values, parses both, and REFUSES if your values changed anything the engine ENFORCES – a step, a gate, a check, strictness (slot values may change what a step SAYS and what a question ASKS, never what it enforces); the refusal names exactly what changed where. It then runs the same admission check a saved workflow gets, and saves the instance with provenance (template, version, date, slot values) so it can be re-instantiated later. FREE (authoring is content; the paid line is ENFORCING the instance via start_workflow). A missing required slot is refused with the slot's own question. Next: start_workflow(newName) to run it.

PARSE-VALIDATES FIRST (a file the parser refuses is never written; the error returns verbatim), and slot-validates: every {{ref}} must name a declared slot, and every slot needs an example (the trial instantiation renders with it). Saving a stock template's name creates your customised copy (it shadows the stock one). Free – authoring is content. Next: check_workflow(name) to trial-instantiate, then instantiate_workflow_template to fill it in.

Stock templates are read-only (deleting a customised copy reverts to the stock version). Free.

Definitions bind by LineageTag when present, or by a stable tests-sidecar identity for a valid tagless object. A vanished or ambiguous target reports MISSING on the next run, never a silent pass. Ambient checks are not listed here because they derive from the model on every run_tests. Unreadable lines are counted, never thrown. FREE, read-only.

kind='measureReconcile': paramsJson carries the ReconcileRequest (sql, groupBy, required blankPolicy, tolerances; see reconcile_measure, which is the same runner one-off). Pass targetRef; the engine binds by LineageTag when present and otherwise creates a stable tests-sidecar identity so valid tagless measures follow renames. The returned bindingWarning is non-null if a name fallback was unavoidable. GROUND TRUTH IS AI-DRAFTED, HUMAN-ACCEPTED: show the user the SQL and get acceptance before saving. A saved test is the user's suite, not the assistant's guess. Pro; running the ambient suite is free.

Returns false when the id wasn't present. Ambient checks cannot be deleted – they derive from the model; to clear a failing integrity check, fix the data it measured. FREE.

ZERO-SETUP AMBIENT CHECKS run on every model: per-relationship integrity (live: six data probes – orphaned foreign keys, duplicate/blank keys, row counts; an invalid relationship reparents orphans onto the hidden blank row so TOTALS STILL TIE while every per-member breakdown is silently wrong – any integrity Fail caps the grade at D) + per-role static security (a tautology filter like 1=1 restricts nothing). Saved definitions (list_tests) run too – measureReconcile defs execute the full SQL-vs-DAX reconciliation. Verdicts: Pass | Fail | Suspect (downstream of a sibling failure, its root cause named – not a second failure) | NotVerifiable (couldn't check: offline, refused, insufficient coverage – NEVER counted as a pass and NEVER graded). READ Health.Grade WITH Health.CoveragePct – the grade scores only what was decided; coverage says how much that was; RootFailures is the number that matters. Offline runs the static checks and reports the rest NotVerifiable – connect_xmla/connect_local for the full run. Agent-origin data probes are governed by the standard QueryData permission gate. FREE including all evidence; persist=true also appends the run to history (Pro). Read-only.

The drift-trend substrate: compare health across runs to see a suite degrade before a user does. Pro (run_tests itself is free and shows everything live); free callers get a teaching note, never an error. Read-only.

Returns {markdown, json, html, contentHash, note, error}; JSON is the record of truth, HTML is its deterministic human view, and contentHash detects any later change. The report includes model and environment context, grade WITH coverage, hard gates, root causes before detailed evidence, measure reconciliation rows only for failing measures, time-intelligence variant evidence, relationship counts and rates, and static security plus object visibility. It never exports a run from a different model: if no current-model run exists, call run_tests and retry. Pro with a soft gate: free callers receive a teaching note, not an exception. Read-only.

The engine runs the DAX side (SUMMARIZECOLUMNS over your groupBy + the measure, plus an independent grand-total query) over the live XMLA connection and runs YOUR supplied SQL over the Fabric SQL endpoint, full-outer-joins them by the composite grouping key, and judges every cell under an explicit tolerance + blank policy. The engine NEVER authors the SQL – you supply the ground truth. The SQL runs against the source endpoint as YOUR OWN identity (the engine holds no elevated credential – it can only read what you already can; the endpoint's nature + your warehouse permissions decide what is possible). Whether you (an agent) may run it is governed by the QueryData permission setting on the SQL target (the permissions tab – Ask/Deny/Allow), exactly like preview_table / run_dax. A human runs ungated. groupBy entries are resolved to real model columns (a 'column:Table/Column' ref or a plain 'Table'[Column]); an unresolved entry is refused (this prevents WRONG RESULTS, not writes). blankPolicy is REQUIRED ("zero"|"null"|"distinct"). Grade on `status` (Reconciled|Mismatch|InsufficientCoverage|NothingVerifiable|InputError), NOT `anyMismatch`; an uncaveated pass is Reconciled AND unverifiable==0 AND complete==true – and even then expected-member coverage is UNKNOWN (coverageKnown=false; it reconciles the members observed, not that none is missing). A total-only run is InsufficientCoverage by design (a matching total can hide the VertiPaq blank-row trap). Requires a live connection; reads source-row aggregates from BOTH the model and the SQL endpoint. Returns the status, summary, worst offender, coverage facts, per-side execution timestamps (independent connections may see different snapshots), snapshotNote, and the mismatching cells (capped).

Returns the detected endpoint/database plus every candidate model table with schema/entity, and echoes the effective endpoint after optional overrides. Detection follows the measure's dependency tables; multiple reachable SQL sources are reported AMBIGUOUS and never guessed. testConnection=true performs only SELECT 1 against the effective endpoint/database (it does NOT run or change the human-accepted SQL); agent calls use the standard QueryData approval gate. Suggested next action is returned on refusal/failure. FREE, read-only.

Each item includes type, producer, verdict with coverage, content signature, paths, and verification state. A changed or conflicted record remains listed as invalid and is never trusted or hidden. Free, read-only. Next: get_evidence(id) to review one; save_evidence(source) to explicitly retain the latest Test report or a terminal Workflow run.

The engine re-verifies the signature and HTML pairing before returning it; invalid evidence is refused with the exact reason. Free, read-only.

source='tests' saves the latest current-model Test report and keeps its existing soft Pro boundary; source='workflow' saves a terminal Workflow run (sourceId may be omitted for the latest). The engine regenerates and verifies the artifact itself, then atomically writes canonical JSON plus matching HTML under `.semanticus/evidence/<model-identity>`. Re-saving the same source is idempotent. Nothing is written by export alone.

It is plain Markdown in a .semanticus/primers sidecar – beside the model (travels in source control) for a disk model, or in the workspace for a live/local connection – and always uses six fixed sections: Overview, Business context, Gotchas, Patterns, Known issues, History. Read this before model work for the declared business context and known traps. Free, read-only.

The document must keep exactly six second-level sections in this order: Overview, Business context, Gotchas, Patterns, Known issues, History. Stored beside the model in .semanticus/primers so it travels in source control without changing the model definition. Manual writing is free. Show the user the proposed edit before writing; automated suggested-edit generation is a separate Pro capability.

Each proposal carries the source lesson id, capture time and source-run provenance. This never changes the Primer. Show the proposal to the user, then call accept_primer_suggestion only after explicit approval or reject_primer_suggestion to dismiss it. Free users can still edit the Primer manually.

Human approval is required before this call. The accepted source id is recorded so it cannot resurface. To write directly without suggestion automation, use set_model_primer (free).

The source learning remains in the hidden learning store, while this model records the rejection so the same suggestion does not keep resurfacing.

Insights are the USER'S OWN DATA: plain append-only JSONL (`.semanticus/knowledge/insights.jsonl` for project scope, `~/.semanticus/knowledge/` for global), readable without us, never rewritten. Give deterministic match keys (rule ids, gate signatures, error types, op names, domain tokens) so recall can find it. Write-gated (SSGM): it lands 'pending' until approve_insight, UNLESS the auto-approve setting is on – which DEFAULTS TO TRUE for single-user local mode (set knowledge-settings.json {"autoApprove": false} to force review). fingerprintScoped=true pins it to the CURRENT model's shape (needs an open model); false = a user-level lesson that travels across all models. Free.

Provide new text and/or keys; omit one to leave it unchanged. Free.

No-op-safe on an already-approved insight. Free.

An insight that keeps proving useful ranks higher and resists decay. Free.

When the score falls to 0 the insight is materialized OUT of the live set (the delta trail is kept – nothing is erased). Use it to retire a lesson that stopped applying. Free.

It vanishes from the live set and recall. Prefer downvote for a lesson that merely lost relevance. Free.

Filter by scope ('project'|'global'; omit for both) and/or status ('pending'|'approved'). Reports the count of any corrupt JSONL lines it skipped – the store never bricks. Free, read-only.

The engine computes the model's fingerprint, reads BOTH scopes' APPROVED insights, and returns a DETERMINISTICALLY-ranked candidate set (key-term overlap with your query + same-shape fingerprint bonus + importance score + temporal decay) – each with WHY it matched (matchedKeys). This is retrieval, not judgment: YOU do the semantic ranking over the candidates and decide what applies. Returns the fingerprint too, and says so plainly when there is no prior experience for this shape. Needs an open model. Free.

No inference, no embeddings. Use it to reason about 'have I seen a model like this before'. Needs an open model. Free, read-only.

DRY RUN by default: confirm=false returns how many live insights WOULD be erased and changes nothing; confirm=true appends a purge marker so everything before it in that scope becomes invisible on replay (the file is not rewritten). Free.

Use it to find where agents flail so you can fix TOOL ERGONOMICS (better error messages, terser results) – a permanent improvement, cheaper than learning machinery. Fail-soft: a missing/empty/corrupt log returns an empty report with a note, never an error. Does not mutate the model.

Anonymous + read-only; no model needs to be open. Omit 'text' to list all. Returns package summaries (id, latest version, description, authors, downloads). Then use daxlib_package_info to preview a package's functions, and daxlib_install to add them.

Anonymous + read-only.

Anonymous + read-only. Omit 'version' for the latest stable.

Free. By default existing functions of the same name are left untouched (reported as skipped); pass replaceExisting=true to overwrite. Provenance is recorded so daxlib_list_installed / daxlib_uninstall work. Undoable in one step.

Free.

Offline – no network.

Read-only. Use it to understand the whole model at once or to see what the built docs will contain.

Use this to discover WHERE to add business context for the exported documentation. The narrative is ADDITIONAL context for the docs – separate from each object's first-class Description (which you set with set_description).

objRef is 'model' for the model-wide narrative, or 'table:Name' / 'measure:Table/Name' (narrative is supported on the model, tables and measures). Common sectionKeys: 'overview', 'businessContext', 'notes' (per object); 'overview', 'glossary', 'methodology' (model). Returns null if empty.

objRef is 'model' or 'table:Name' / 'measure:Table/Name' (narrative is supported on the model, tables and measures; other refs are rejected). Common sectionKeys: 'overview', 'businessContext', 'notes' (per object); 'overview', 'glossary', 'methodology' (model). Set markdown to empty/null to clear the section. This is the collaborate-on-the-docs path: it's stored as a model annotation, broadcasts live to the human's Documentation tab, and is undoable.

The spec is an authoring artifact (NOT the model itself); build_model_from_spec materialises it. Returns { version, source, spec } (spec is null if none is loaded). Read-only.

Use this to author or refine the spec; it broadcasts live to the Spec tab. Shape: { name, compatibilityLevel, storageMode: 'import'|'directLake', source: { kind:'fabric-sql', server, database, schema }, tables: [{ name, role:'fact'|'dimension'|'date'|'calculated'|'isolated', entity, schema, mExpression, calculatedExpression, sourceName, columns: [{ name, dataType, sourceColumn, isKey, hidden, summarizeBy }] }], relationships: [{ fromTable, fromColumn, toTable, toColumn, cardinality:'manyToOne'(default)|'oneToOne'|'oneToMany'|'manyToMany', crossFilter, isActive }], measures: [{ table, name, dax, formatString, displayFolder }], timeIntelligence: ['YTD','PY',...], timeIntelligenceBaseMeasures: [...], dateTable: { name, startExpr, endExpr, markAsDate } }. Does NOT touch the model. Returns the new spec view.

Pass an absolute path, e.g. '.../model.spec.json'. Returns the spec view.

Broadcasts live to the Spec tab. Returns the loaded spec view.

Returns the empty spec view.

The autogen is a FIRST DRAFT – refine it (set_spec / the Spec tab), then build_model_from_spec. Returns the spec view.

Classifies fact/dimension from FK topology, maps SQL types to TOM types, hides key columns, and proposes additive measures + a time-intelligence set. storageMode 'import' (M) or 'directLake'. authMode: azcli (default) | serviceprincipal | interactive | devicecode. If the endpoint rejects the sign-in with an authentication error, the workspace is usually in a DIFFERENT tenant than your az login – pass tenantId. The result is a FIRST DRAFT – refine it, then create_model + build_model_from_spec. (Fabric often declares no enforced keys, so relationships may be empty – add them in the spec.) Returns the spec view.

Composes the authoring primitives in dependency order: data source + shared M -> tables (import/Direct Lake/calculated, with columns + data types + keys) -> relationships (FK->PK) -> date table -> measures -> time-intelligence. Existing objects are skipped (re-run safe); per-row failures are reported without aborting. Build INTO the current session – call create_model first for a from-scratch build. Returns a report (created/skipped/errors + before->after counts).

Create a new (empty draft) Fabric data agent – data_agent.json + a minimal draft stage_config with aiInstructions. DRY RUN by default: commit=false returns the exact request and changes NOTHING; commit=true creates it. aiInstructions capped at 15000 chars.

Live read; read-only.

Live read against api.fabric.microsoft.com with your Entra identity; read-only. [verify-at-build]: the item type string isn't documented yet, so this filters items whose type CONTAINS 'dataagent' (case-insensitive) – if none match, ObservedItemTypes lists every item type in the workspace so you can confirm the real one.

Update a data agent's DRAFT – replace only the parts you pass (null = keep). Read-modify-write: fetches the current definition and re-emits ALL existing parts plus your changes (never drops unknown parts). aiInstructions capped at 15000 chars. datasourceJson/fewshotsJson go under the draft/{datasourceFolder}/ folder (folder = 'semantic_model-<name>'). DRY RUN by default: commit=false returns the exact request and changes NOTHING.

Publish a data agent: copy every draft/* part to published/* and write publish_info.json with a description ([verify-at-build] – v1 publishes via the documented definition-write path). DRY RUN by default: commit=false returns the exact request and changes NOTHING; commit=true publishes.

Delete a Fabric data agent item. DRY RUN by default: commit=false returns the exact request and changes NOTHING; commit=true deletes it (irreversible).

Build a complete semantic_model datasource config FROM the open model in one shot – an element tree of every table/column/measure with model descriptions carried and is_selected honoring hidden objects + the Prep-for-AI AI-data-schema exclusions; aiInstructions seeded from the model's LSDL instructions. Returns the JSON for review (feed it to update_data_agent) – writes NOTHING. artifactId/workspaceId come back as placeholders (resolve the real Fabric ids first – see the Note). Like every data-agent write, Pro; list/get stay free.

This is the guardrail the deploy/publish actions check before a live write. Read-only. WAIVED BPA findings never block (they're audited acceptances – bpaWaivedBlocking counts them); readiness hard-gates ignore waivers by design.

Metadata only – names/descriptions/visibility/categories/format strings/folders/summarize-by, measure + calc-column DAX, partition sources (M / calc-table DAX / legacy), shared expressions, and the linguistic schema – via Model.SaveChanges(), matched by LineageTag so renames land on the right object. NO data refresh and NO deletes. A NEW CALCULATED table IS created (and Calculate-recalced on commit); other structural changes (new DATA/import tables, new data columns, new partitions, source-type or Direct Lake rebinds, incremental-refresh policy) are reported in Unmatched/LiveOnly, never silently dropped. Empty endpoint = deploy back to the model this session opened (the round-trip); or pass endpoint + database. DRY RUN by default – commit=true writes. Needs a Read-Write XMLA endpoint and a write principal (authMode=serviceprincipal is the reliable one).

Read-only – deploys nothing. ('Update' items may be identical; Different-vs-NoDifference is only known after a real deploy.)

DRY RUN by default (the New/Update preview + the readiness gate); commit=true deploys. An agent may deploy to NON-production stages only – promoting to PRODUCTION needs a human confirming from the Deploy tab with the confirmToken their own dry-run shows. A failing gate blocks unless forceOverride=true. items = source item ids (empty = all supported).

Read-only.

Needs an Admin role on the pipeline. Live read; read-only.

Needs Contributor on the stage workspace. Live read; read-only.

Use get_pipeline_stages then get_stage_items to drill into a pipeline's Dev/Test/Prod stages. Live read; read-only.

Live read against api.fabric.microsoft.com using your Entra identity. Read-only.

Pure file authoring – no Fabric call. Returns the contents; write=true also writes them into the repo.

DRY RUN by default (enumerates parts + target, writes nothing); the live publish (commit=true) is human-only from the Deploy tab – an agent's commit is refused, previewing is allowed.

DRY RUN by default (commit=false). Pass commit=true to connect. Needs workspace Admin. After connecting, initialize + fabric_git_update/commit to sync.

Read-only.

Read-only.

DRY RUN by default (commit=false reports the incoming change count + any conflicts). Pass commit=true to apply. conflictPolicy = PreferRemote (default) | PreferWorkspace; allowOverride=true permits overwriting items that have workspace changes.

DRY RUN by default (commit=false reports the pending change count; writes nothing). Pass commit=true to commit. items = item objectIds for a selective commit (empty = all).

DRY RUN by default (commit=false). Pass commit=true to disconnect. Needs workspace Admin.

Every committed apply_model_diff push to an XMLA endpoint writes one FIRST, so the push can be undone – this is the only way back from a live DELETE (a deploy re-creates measures, calculated columns, calculated tables and named expressions, but a relationship, role, perspective, hierarchy, partition, culture, datasource or data table removed from a published model is otherwise gone for good). Newest first. Only the newest 10 per target are kept. Filter by endpoint + database, or omit both for every target. Snapshots live in ~/.semanticus/restore and hold the target's full model METADATA (measures, M queries, role filters, connection strings – never row data) in clear text; purge_restore_points removes them. An integrityError means rollback is refused, while purge remains available through its validated storage path. Read-only and free. Next: rollback_push(id) to preview a restore.

DRY RUN by default: commit=false reports exactly what would be restored and – critically – what would be REMOVED, i.e. every object that exists on the target now but not in the snapshot. That includes anything the push added AND anything anyone else added since, so READ RemovedRefs before committing. Pass commit=true to write. Restores the object kinds a redeploy cannot: relationships, roles (RLS), perspectives, hierarchies, partitions, cultures, datasources and data tables. Resolution is by lineage identity, so an object republished under you is refused rather than overwritten. Recorded in the audit trail. FREE at both tiers – the undo for an irreversible write is never gated. Next: run list_restore_points to find the id; run rollback_push(id) to preview; then rollback_push(id, commit=true).

Choose exactly one selector: id removes one restore point, or olderThanDays selects every snapshot older than that non-negative age. DRY RUN by default: confirm=false returns the exact candidates and a token without deleting. After reviewing them, pass confirm=true with that exact confirmToken; a stale or changed candidate set is refused. Reports partial file-delete failures honestly. Use this to clear model metadata from disk only when you accept that the guarded live push can no longer be undone.

Returns the global on/off switch, the active preset, and the capability×label matrix. Labels are local | dev | uat | prod; an UNLABELLED target is treated as prod (the strictest). Actions are allow | ask | deny: 'ask' means a human must approve the specific action in the UI before you can do it (see list_pending_approvals – you request approval simply by attempting the action). Reading, and running a calculation, are never gated. Use this to know BEFORE you try: if pushing to a target is 'deny' or 'ask', tell the user rather than failing repeatedly. Only a human can change this policy or the labels it reads. Read-only and free.

Each entry is bound to the EXACT action (capability + target + intent); the human approves it in the UI, then you retry the SAME action and it proceeds once (a grant is one-shot and expires). Use this to see what you're waiting on. You cannot approve your own actions – that asymmetry is the point. Read-only and free.

A relative target stays inside the current workspace, and the target must not already exist. Returns the model path to open with open_model. Uses the user's git credential helper.

Also flags whether the open model has unsaved in-memory edits (git_commit saves them to disk first). Read-only.

Pass a file path to scope it; staged=true for the staged diff. Read-only.

Read-only.

To change state, pass a branch name and set create=true, checkout=true, or both. If switching changes the on-disk model, the result names the model path to reopen and flags modelReloadNeeded.

Refuses while the open model has unsaved edits. If the on-disk model changes, the result names the model path to reopen and flags modelReloadNeeded.

Refuses while the open model has unsaved edits. If the on-disk model changes, the result names the model path to reopen and flags modelReloadNeeded.

DRY RUN by default (commit=false returns the file set that WOULD be committed and whether the model needs saving first; nothing changes). Pass commit=true to actually commit – it SAVES the open model's unsaved edits to disk first, stages the model folder, then commits. Returns the commit hash + files.

DRY RUN by default (confirm=false reports what would push). Pass confirm=true to push. Uses the user's git credential helper – the engine never handles git credentials.

DRY RUN by default: commit=false reports the owned paths, changed files and whether the model will be saved. Pass commit=true after review. Refuses a detached branch, conflicts, or unrelated staged files instead of sweeping them into the commit. The result names the exact checkpoint hash; use restore_history_checkpoint to preview a restore.

Checkpoints are ordinary model-scoped commits, so they survive closing the session and cloning the repository. Returns supported=false for a model outside git; session undo remains the short-term alternative. Read-only.

DRY RUN by default: restore=false names the model paths and safety sequence. Pass restore=true only after review. The engine first commits the current model as a rescue checkpoint, restores the selected model paths, reopens the model, and commits the restored state. Returns all three hashes so the action stays reversible. Live published models use rollback_push and its restore points instead.

The free tier is fully usable one edit at a time; Pro unlocks the one-click BULK apply (apply_plan with >1 item, bpa_fix_all, apply_safe_fixes). Check this before attempting a bulk apply so you can fall back to applying items individually on free.

Returns only tables that HAVE a stored position – tables not listed are unplaced (auto-laid-out by the UI). Positions are engine-owned (a .semanticus/layout.json sidecar beside the model), keyed by a stable LineageTag so a position survives a table RENAME, and excluded from the model diff. Read it to render or reason about the table layout the human sees.

Identify each table by its `ref` (preferred) or `name`. MERGES with existing positions (tables you omit keep theirs; deleted tables are pruned) and the engine re-keys each by its stable LineageTag, so the layout survives renames. Writes the .semanticus/layout.json sidecar beside the model – this is NOT a model edit (it does not touch the model definition or its diff). The model must be saved on disk first; otherwise returns an Error.

Needed for newer features – DAX user-defined functions require 1702+. Refuses to lower it. Undoable within the session, but re-deploying an upgraded model to an older runtime may fail.