MCP tool reference

Call this first.

ONE round-trip, token-budgeted (≤~2k tokens), giving the whole map: connection state · entitlement tier · model overview (name/source/table-measure counts/unsaved-changes) · AI-readiness grade + category scores + finding counts · structural graph (relationship counts, disconnected visible tables) · in-flight work (active workflow runs, a loaded change-plan, a loaded spec) · the last few experience-log entries for continuity · deterministic suggestedNextActions. Each section names its DRILL-DOWN op: connection_status · get_entitlement · ai_readiness_scan (findings) · get_model_graph (full ER) · get_workflow_run · get_plan · get_spec · list_calendars. Deliberately OMITS the full findings list, per-object detail, and DAX bodies – fetch those with the named ops. Sections are null/omitted when they don't apply (no connection, no in-flight work, no log).

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 any ref (table/column/measure/relationship/function). 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.

Searches tables, measures, columns (incl. calculated), hierarchies, calculation items, functions, roles, and perspectives. Returns each hit's ref (so you can act on it), kind, owning table, which field matched, and a short snippet. Use it to locate a measure by a word in its formula, find every object referencing a column, or audit naming. `max` caps the results (default 100); Truncated tells you if there were more.

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.

Use one with connect_local.

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.

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.

newName optional (auto-named if omitted). 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.)

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

Deterministic, undoable.

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.

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.

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[]}.

One undoable batch; fully tracked – structural changes (adding a measure/calculated column inside a table) surface, and the apply is undoable. Edits EXISTING top-level objects (you can add child measures/columns); a brand-new table is skipped and reported (create it with create_table first). 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.

PREREQUISITES (validated, refused if missing): two M parameters named exactly RangeStart and RangeEnd, and a partition whose M filters the date column on them. Metadata only – does NOT trigger a data refresh. Deterministic, undoable. On an EXISTING policy, omitted fields are PRESERVED (so you can change one knob); the defaults (store 5 Year, refresh 10 Day, offset 0, Import) apply only when first creating one.

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

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.

Read-only.

Accepts a table name or a 'table:Name' ref. Read-only; requires a live connection.

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.

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.

Use it to find what to drop/hide/optimize. 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. Pro; 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). The verdict (safe/impact) is recorded in the Verified Edits audit trail. Pro; needs the live connection the baseline came from.

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.

ALWAYS run this (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.

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.

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.

Call once before set_synonyms. Pass null culture for the default (en-US).

Auto-enables the linguistic schema if needed. Helps Copilot/Q&A map natural language to the right field.

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).

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.

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.

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'). 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' (renames stay 'proposed' – they need an explicit approve because they're riskier). 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.

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.

DRY RUN by default (commit=false reports what WOULD apply). Pass commit=true to write the target file. selectedRefs limits to specific object refs (e.g. ['measure:Sales/Total']); omit to apply all differences.

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.

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.

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 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.

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.

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, 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. 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).

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.

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.

DRY RUN by default: commit=false returns the exact request and changes NOTHING; commit=true publishes.

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). Free alternative: assemble the datasource.json by hand and call update_data_agent.

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; structural changes (new tables/data columns/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.

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.

Switching changes the on-disk model files – reopen the model afterward (the result flags modelReloadNeeded).

Changes the on-disk model files – reopen the model afterward (modelReloadNeeded).

Changes the on-disk model files – reopen afterward (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.

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.