Telemetry — MANDATORY. Every

api.fabric.microsoft.com

call must carry

x-ms-fabric-skill: semantic-model-authoring

(

az rest

:

--headers "x-ms-fabric-skill=semantic-model-authoring"

), including every LRO poll,

fabric_lro

and retry. Snippets omit it — add it anyway.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
3. Always consider the Tool selection priority when choosing which tool to use for each operation. Do not default to TMDL edits or

   az rest

   if MCP is available and connected to the target model.

1. Tier 1 —

   powerbi-modeling-mcp

   MCP is registered -> Use MCP for authoring (new or edit) operations against the model from any source: Power BI Desktop, Fabric workspace, or local PBIP folder. MCP is the most reliable and full-featured way to edit semantic models, with immediate effect on the live model and no risk of TMDL desync.
   Important: In case of dynamic search tools is available (e.g.

   tool_search_tool_regex

   ) search for an available MCP server matching the pattern

   powerbi-modeling-mcp

   .
   This includes BOTH writes AND reads/inspection.
   • To inspect or verify changes -> use the corresponding MCP operations (List / Get).
   • Anti-pattern: opening,

     view

     -ing,

     glob

     -ing or otherwise reading TMDL files (

     *.tmdl

     ) while MCP is connected. The MCP-loaded model is the source of truth - the on-disk TMDL is stale. The only exceptions is when the user explicitly asks to work with the TMDL files.
2. Tier 2 — MCP not registered + PBIP folder or Fabric workspace -> Edit TMDL files directly. Load tmdl-guidelines.md and pbip.md. When the source is a Fabric workspace, use

   az rest

   to round-trip the TMDL (load semantic-model-rest-api.md):

   getDefinition

   -> edit TMDL locally ->

   updateDefinition

   .

powerbi-modeling-mcp

All workflows below are tool-agnostic. Workflow steps describe the intent (connect, create, edit, save, deploy, refresh). The tool used to perform each step is determined here. Always select the highest-priority tool available for the current environment; do not mix tools when a higher-priority option works. Some workflows OVERRIDE this default priority, always check the workflow's own tool-selection rules before defaulting to Tier 1.

• Power BI Desktop: Locate the running Power BI Desktop instance and connect to its local model.
• Fabric workspace: First, find the workspace and semantic model using the Finding Workspaces and Items pattern: list workspaces to resolve the workspace ID by name, then list items of type

  SemanticModel

  in that workspace to resolve the model ID by name. Then connect to the model (live) or export its TMDL definition for local editing.
• PBIP project: Connect to the

  [Name].SemanticModel/definition

  folder. Load pbip.md to understand the PBIP folder structure - only load the

  [Name].SemanticModel/definition

  folder that includes the TMDL code.

• Changes are applied immediately as each operation executes against the live model. No explicit save step is needed.
• PBIP project (live via MCP): Serialize the model back to the

  [Name].SemanticModel/definition

  folder at the end of the session. If the PBIP folder does not exist yet, follow Export to PBIP to create the full structure first.

az rest

• PBIP project: Changes are already written to the TMDL files during editing. No additional save step is needed.
• Fabric workspace: Changes were made to local TMDL files exported from the service. Re-deploy the model (load semantic-model-rest-api.md for the

  updateDefinition

  flow) to push changes back to the workspace.

1. Gather requirements - interview the user until both reach a shared understanding of: purpose of the model, data source connection details and schemas, and key business entities/facts. If data source information is not available, STOP and use

   ask_user

   . Do not guess or fabricate.
2. Determine storage mode - data source is Fabric OneLake -> Direct Lake; otherwise default to Import. Only use DirectQuery when the user explicitly asks for it.
3. Design star schema - identify fact and dimension tables and relationship keys.
   • If fact table includes date field(s), create a separate date dimension table and link it to the fact with a relationship. If not explicitly requested, use PowerQuery/M partition instead of DAX calculated table.
4. Load applicable guidelines - MANDATORY: load modeling-guidelines.md before building any object (including the Tier 1 MCP path below); also load direct-lake-guidelines.md if Direct Lake. Don't build from memory.
5. Build - follow Tool Selection Priority: prefer the modeling MCP to build the whole model when one is available; otherwise use the TMDL code-edit path. Create an empty database (compatibility level 1702+), then for each table follow the execution order from Modify an Existing Model (partitions -> columns -> relationships -> measures). Storage-mode specifics:
   • Import / DirectQuery - create M parameters for the data source (

     Server

     ,

     Database

     , ...) and reference them in partition M code; ensure proper

     dataType

     and

     sourceColumn

     mapping on columns.
   • Direct Lake - create a shared named expression for the Direct Lake connection using the

     AzureStorage.DataLake

     connector; use

     EntityPartitionSource

     with

     directLake

     mode mapped to the lakehouse table columns.

   Build the whole model in one pass, then deploy once. Add every table, column, relationship and measure before deploying - don't deploy a partial model and edit-redeploy. On the MCP path, keep the model in the session end to end.

6. Deploy or save - Fabric workspace available -> Deploy to Fabric; otherwise -> Export to PBIP. See Saving Changes to a Semantic Model. Deploy through the same path you built with.
7. Validate - run Validation Checklist.

1. powerbi-modeling-mcp

   TOM inspection (List / Get) - the default when

   powerbi-modeling-mcp

   is registered and connected to the target model with Write access. It returns the structured object model directly and stays in sync with pending edits, so it is preferred while authoring.
2. DAX

   INFO.VIEW

   functions - query the model's

   INFO.VIEW.*

   metadata rowsets. MANDATORY: before writing or running ANY

   INFO

   -function DAX, you MUST load metadata-discovery.md first. Do NOT compose

   INFO

   queries from memory; load the reference and use its patterns. Prioritize this method when any of the following is true:
   • You lack Write permission on the model.

     powerbi-modeling-mcp

     List / Get operations require Write; with Build access, use

     INFO.VIEW

     functions executed via the

     dax_query_operations

     tool.

   • powerbi-modeling-mcp

     is not registered or not available. Use Tier 2: export the model definition (

     getDefinition

     ) and inspect the

     .tmdl

     files for schema metadata.

INFO.VIEW.*

1. Connect & discover - per Connecting to a Semantic Model and Discover Semantic Model Metadata. List tables, relationships, existing measures, and identify storage mode (it dictates which guidelines apply).
2. Load applicable guidelines - modeling-guidelines.md always; direct-lake-guidelines.md if Direct Lake; tmdl-guidelines.md when editing TMDL directly; dax-guidelines.md for any DAX changes (includes UDF refactoring).
3. Plan changes - identify exactly what to add, modify, or remove. Check for naming conflicts and duplicates.
4. Execute in correct order:
   • Adding tables - partitions -> columns -> relationships -> measures.
   • Adding relationships - ensure key columns exist on both sides with matching data types;
   • Adding measures - verify referenced columns/tables exist;
5. Save & validate - per Saving Changes to a Semantic Model and Validation Checklist.

1. Connect & discover - per Connecting to a Semantic Model. Detect any existing field parameter (a column carrying

   ParameterMetadata

   "kind": 2

   ) before creating a duplicate.
2. Route to the matching sub-workflow in field-parameters.md:
   • Create a new parameter -> Workflow: Create a field parameter (

     table_operations

     CreateFieldParameter

     at Tier 1).
   • Edit an existing parameter (add / remove / reorder / relabel fields) -> Workflow: Edit a field parameter (partition rewrite via

     partition_operations

     ; there is no

     UpdateFieldParameter

     operation).
   • Rename or delete -> Workflow: Rename or delete a field parameter.
3. Save & validate - per Saving Changes to a Semantic Model and Validation Checklist. Confirm the three columns and

   ParameterMetadata

   "kind": 2

   are intact so Desktop recognizes the table as a field parameter.

Hard requirement: Requires a trace-capable client (MCP preferred))

1. Tier model for categorizing optimization effort
2. Trace diagnostics to identify bottlenecks
3. Pattern catalog with candidate optimization techniques to test and validate

1. Connect & inventory - per Connecting to a Semantic Model and Discover Semantic Model Metadata. Capture all tables, columns, relationships, measures, and storage mode.
2. Load applicable guidelines - modeling-guidelines.md always; direct-lake-guidelines.md if Direct Lake; naming-conventions.md when assessing naming; dax-guidelines.md when assessing DAX.
3. Evaluate - compare the model against the loaded guidelines (star schema, naming, relationship cardinality and cross-filter, explicit measures with

   formatString

   , column data types and

   sourceColumn

   , hidden FK columns, calculated-column-vs-measure choices, Direct Lake constraints, etc.).
4. Present findings grouped by severity (critical, recommended, optional). For each item state the rule violated and the proposed fix. Wait for user approval.
5. Apply approved fixes via Modify an Existing Model.
6. Save & validate - per Saving Changes to a Semantic Model and Validation Checklist.

1. Confirm scope & gather context - via

   ask_user

   , confirm consumption mode (reports only / conversational BI / both) and model stability per the When to Apply section. Collect business context (process, key metrics, common natural-language questions, vocabulary). Do not invent.
2. Connect & inventory - per Connecting to a Semantic Model. Capture model contents and the source location (PBIP / Fabric workspace / Desktop-only).
3. Evaluate & route - walk the Readiness Checklist in order; for each gap, classify the fix per Supported Editing Routes (agent-editable TOM metadata vs AI-specific artifacts the user configures in the Power BI "Prep data for AI" UI).
4. Present findings grouped by severity, each tagged with routing (agent-applicable vs user-action-required). Wait for approval.
5. Apply approved changes - apply TOM metadata fixes via Modify an Existing Model; for AI instructions, AI Data Schema, and Verified Answers, instruct the user to configure them in the Power BI "Prep data for AI" UI and, only if the user agrees, offer suggestions per the readiness reference; Desktop-only PBIX -> instruct user.
6. Save, validate, recommend live testing - per Saving Changes to a Semantic Model and Validation Checklist; advise the user to test representative natural-language prompts in Copilot or the Data Agent and iterate.

Key fact: Exporting a model only produces the TMDL definition files. It does NOT create the surrounding PBIP folder structure (Report folder,

definition.pbism

,

definition.pbir

,

.pbip

entry point). The agent must scaffold these before exporting, otherwise the result cannot be opened in Power BI Desktop.

1. Determine target - via

   ask_user

   , get the target folder path and the semantic model name. If only a folder is provided, use the model's database name as the semantic model folder name.
2. Scaffold the PBIP structure - per pbip.md, ensure

   <Name>.SemanticModel/

   (with

   definition/

   and

   definition.pbism

   ),

   <Name>.Report/

   (with

   definition/

   and

   definition.pbir

   using a

   byPath

   reference), and

   <Name>.pbip

   exist. Create any missing piece.
3. Export TMDL into

   <Name>.SemanticModel/definition/

   , per Tool Selection Priority:
   • Tier 1 (MCP) - use the MCP export/save operation against the live model.
   • Tier 2 (Fabric workspace, no MCP) - call

     getDefinition

     (load semantic-model-rest-api.md) and write the returned parts.
   • Local TMDL files already on disk - copy or move them into the

     definition/

     folder.
4. Validate - confirm the

   definition/

   folder contains at minimum

   model.tmdl

   and table

   .tmdl

   files; confirm

   definition.pbism

   ,

   <Name>.Report/definition.pbir

   (with correct

   byPath

   to

   ../<Name>.SemanticModel

   ), and

   <Name>.pbip

   exist and reference each other correctly.

Hard rule — this workflow OVERRIDES the default Tool Selection Priority. Do not default to MCP just because it is available. The deployment path is determined by the source of the model, not by which tools are connected. If the source is PBIP/TMDL files on disk, you MUST use the Fabric REST API even when an MCP session is active.

1. Are there PBIP / TMDL files on disk that need to be deployed? -> YES — use Fabric REST API. Call

   az rest

   with

   createItemWithDefinition

   (new model) or

   updateDefinition

   (existing model). Load semantic-model-rest-api.md.
   • Rationale: deploying TMDL files directly via the Fabric API is more reliable, faster, and avoids unnecessarily loading the model into MCP only to push it back out.
   • Do NOT open the PBIP in MCP first and then deploy via MCP. That is an explicit anti-pattern for this workflow.
2. Is the model already loaded in a live MCP session (e.g., just built in-memory, or currently being edited via MCP) with no PBIP/TMDL files involved? -> Use MCP tool to deploy with the target workspace and semantic model name.
3. Is the model live in Power BI Desktop with no PBIP saved? -> Use MCP Deploy if MCP is connected to Desktop. If MCP is not available, instruct the user to save as PBIP first, then restart this workflow at step 1.

SemanticModel

Deploy exactly once; the deploy is NOT idempotent. A retried deploy creates a second model with the same name, after which the deploy fails with

There are multiple datasets named '<name>'

. If you hit that error, do NOT retry blindly: list the workspace's semantic models, delete every duplicate with that name, then deploy once from the clean state. If deploying a model that may already exist, delete the existing same-named model(s) before the single deploy.

• Power BI Desktop: Tier 1 (MCP) only — use the MCP Refresh operation.
• Fabric Service: Tier 1 (MCP Refresh operation) or fallback to the Power BI Enhanced Refresh API (load semantic-model-rest-api.md).

Hard rule — this workflow OVERRIDES the default Tool Selection Priority. Do not default to MCP (Tier 1) prefer using

az rest

and REST APIs.

bindConnection

connectivityType

• Use the Fabric Bind Semantic Model Connection REST API (supersedes the legacy Power BI

  BindToGateway

  ).
• One bind request per data source reference - the API does not support bulk binding.
• Discover the model's data source references via

  List Item Connections

  , then match

  connectionDetails

  against

  List Connections

  to find the target

  id

  . Create a connection first if no match exists.
• Validate by re-listing item connections and triggering a refresh.

1. Check the PBIP structure - if the model is sourced from a PBIP folder, ensure the folder structure and files are correct (see pbip.md).
2. Verify against modeling guidelines - re-check every change against modeling-guidelines.md (and direct-lake-guidelines.md for Direct Lake models).

1. Test new measures - for each new measure, run a simple DAX query to validate it returns expected results (e.g.,

   EVALUATE { [Measure Name] }

   ). Skip this step when working with local TMDL/PBIP files only.
2. Test table refresh - when new tables were created, trigger a refresh to verify that partitions, data source expressions, and column mappings are correct. A failed refresh typically indicates mismatched

   sourceColumn

   names, invalid M expressions, or incorrect Direct Lake entity references. Skip this step when working with local TMDL/PBIP files only.

• Understand the data source schema before starting - analyze source tables, columns, and data types before designing or modifying the model.
• Follow modeling guidelines - load modeling-guidelines.md before creating or editing any model; apply star schema design, naming conventions, and column/measure rules
• Follow Tool Selection Priority - always pick the highest-priority tool tier available for the current environment; do not mix tiers when a higher-priority option works

• Star schema over snowflake or flat tables - denormalized dimensions with single-column relationship keys
• Consistency with existing model patterns - when editing an existing model, match its naming conventions and structure rather than imposing new ones
• TMDL format over TMSL - text-based, diff-friendly, preferred for Fabric
• Validate after changes - use Workflow: Discover Semantic Model Metadata to confirm objects landed.

• Hardcoded workspace/item IDs - resolve dynamically via API
• Reading TMDL files when MCP is connected -

  view

  /

  glob

  on

  *.tmdl

  while a Tier 1 MCP session is live is an anti-pattern (see Tool Selection Priority).
• Hand-authoring TMDL files when MCP is registered - using

  create

  /

  edit

  /file-write tools to scaffold

  model.tmdl

  ,

  database.tmdl

  ,

  relationships.tmdl

  , or

  tables/*.tmdl

  is a Tier 1 anti-pattern, including for brand-new models. Build and export via MCP tools.

• Manage RLS/OLS role membership - do not propose REST calls,

  az rest

  URLs, MCP operations, or TMDL changes to add/remove users or groups from a security role. Refuse the request as out-of-scope here and redirect the user to the Power BI portal.

Scope note — examples use

az rest

for discovery to resolve ID's and discover Fabric metadata (see COMMON-CLI.md § Finding Workspaces and Items). Authoring of the semantic model definition is routed through Tool Selection Priority: Tier 1 MCP

powerbi-modeling-mcp

when available, Tier 2 TMDL editing via

getDefinition

/

updateDefinition

otherwise.

1. Discover IDs via

   az rest

   .
2. Connect to the model per Connecting to a Semantic Model and Tool Selection Priority. With

   powerbi-modeling-mcp

   registered, connect MCP directly to the Fabric workspace model (Tier 1). Otherwise fall back to Tier 2 (

   getDefinition

   -> edit TMDL locally).
3. Inspect & plan - list tables and columns via the active tool tier; identify aggregable columns (numeric, not foreign keys, not hidden surrogate IDs) and decide on

   SUM

   /

   AVERAGE

   /

   MIN

   /

   MAX

   per column following modeling-guidelines.md and naming-conventions.md. Load dax-guidelines.md before writing DAX.
4. Add measures per Workflow: Modify an Existing Model.
   • Tier 1 (MCP): call tool create for each new measure with

     expression

     ,

     formatString

     , and target table. Do not hand-author TMDL.
   • Tier 2 (no MCP): edit the table's

     .tmdl

     file directly and round-trip via

     updateDefinition

     REST API.
5. Save & validate per Saving Changes to a Semantic Model.

1. Discover workspace + lakehouse IDs via

   az rest

   .
2. Discover lakehouse schema - list tables and columns via the Lakehouse OneLake APIs or the SQL Endpoint of the lakehouse. Capture table names, column names, and data types - these drive semantic model table, column definitions and partition metadata.
3. Select tool tier per Tool Selection Priority: prefer Tier 1 (

   powerbi-modeling-mcp

   ) for the full build. Tier 2 (PBIP/TMDL scaffolding then deploy) only if MCP is not registered.
4. Build the model following Workflow: Create new Semantic Model - data source is OneLake so the storage mode is Direct Lake (load direct-lake-guidelines.md and modeling-guidelines.md). Design a star schema from the lakehouse tables, then:
   • Create the empty database.
   • Create one shared named expression for the lakehouse connection.
   • For each table: add

     EntityPartitionSource

     (mode

     directLake

     ) -> columns mapped to lakehouse columns -> relationships -> measures.
5. Deploy per Workflow: Deploy to Fabric:
6. Validate per the Validation Checklist - confirm the model appears in the workspace and trigger an initial refresh to verify Direct Lake column mappings resolve.

1. Discover workspace + model IDs via

   az rest

   .
2. Discover the target connection in Fabric by matching the server name:
   bash

   SERVER="sql-prod"
   CONN_ID=$(az rest --method get --resource "https://api.fabric.microsoft.com" \
     --url "https://api.fabric.microsoft.com/v1/connections" \
     --query "value[?connectionDetails.path | contains(@, '$SERVER')] | [0].id" -o tsv)

   If no connection matches, stop and instruct the user to create one first per connection-binding.md.
3. Execute the bind per Workflow: Manage Semantic Model in Fabric § Connection Binding - load connection-binding.md and follow the discover -> match -> bind -> validate flow:
   • List the model's data source references (

     List Item Connections

     ).
   • For each reference whose

     connectionDetails

     matches

     $CONN_ID

     , call the Fabric

     bindConnection

     endpoint one request per data source reference (no bulk binding).
4. Validate - re-list item connections to confirm the binding, prompt the user to trigger a refresh per Workflow: Refresh Semantic Model. Credential errors -> stop and direct the user to the Service portal (per TROUBLESHOOTING).