Connect to a Power BI target and initialize an orchestrator session.

Use this tool when the user asks to:

• Connect to a Power BI Desktop session, Fabric workspace, PBIP folder, or PBIX file.

• Start an interactive session to inspect or modify Power BI assets.

Args: target_type: One of "pbi_desktop", "fabric_workspace", "pbip_folder", "pbix_file". target_ref: Reference path (for PBIP/PBIX) or workspace UUID (for Fabric). auth_mode: "interactive" (browser login) or "service_principal". When omitted, PBI_AUTH_MODE is used, falling back to "interactive". tenant_id: Azure AD tenant ID (required when auth_mode is service_principal).

Returns: ConnectResult with session_id, engines_available status, and any diagnostic warnings.

Create a versionable, multi-step execution plan from an intent template.

Use this tool when the user asks to:

• Plan a complex or risky operation requiring atomic execution or rollback capability.

• Safely rename a table or column across both model and visual bindings (intent="safe_rename").

• Plan an audit, deployment, or DAX regression run.

Args: intent: One of the supported templates ("safe_rename", "audit", "deploy", "dax_regression"). options: Template-specific arguments (e.g. for safe_rename: old_path, new_path, scope). May also contain PlanOptions fields (auto_rollback, max_impact_threshold, dry_run_first).

Returns: PlanResult with plan_id, plan_yaml, steps, risk_score, estimated_changes.

Execute an approved plan with automatic rollback on step failure.

Use this tool when the user asks to:

• Execute or apply an approved plan created by plan_change.

• Run plan steps in dry-run mode before modifying actual files.

• Approve each step individually before it runs.

Args: plan_id: ID of the plan previously created by plan_change. dry_run: If True (DEFAULT), simulate execution without modifying files or cloud resources. Pass dry_run=False explicitly to apply for real. confirm_each_step: If True, ask the user to approve every step before it runs. Declining (or having no interactive client) stops execution and reports the remaining steps as not run.

Returns: ApplyResult with execution status, executed steps, and rollback details if needed.

Composite quality and compliance audit on a Power BI project (PBIP).

Use this tool when the user asks to:

• Audit, inspect, or validate a Power BI project (.pbip) or semantic model.

• Check Best Practice Analyzer (BPA) rules, DAX code quality, or naming conventions.

• Validate WCAG 2.1 accessibility (contrast, missing alt text, chart readability).

Args: pbip_path: Path to the root .pbip directory or folder. bpa_ruleset: Best practice ruleset to run ("default", "strict", "lenient"). dax_measures_json: Optional JSON string or dictionary mapping measure names to DAX expressions. bpa: Whether to execute Tabular BPA checks. dax_lint: Whether to execute static DAX linting checks. accessibility: Whether to audit WCAG 2.1 accessibility on report pages. naming: Whether to validate column, measure, and table naming conventions.

Returns: Dict with overall score (0-100), pass/fail status, and categorized findings.

Deploy a PBIP project to a Fabric/Power BI workspace with pre-deploy gates.

Use this tool when the user asks to:

• Deploy, publish, or release a Power BI project (.pbip) to Microsoft Fabric or Power BI Service.

• Run pre-deployment quality gates before publishing.

• Schedule automatic daily dataset refreshes upon publication.

Args: pbip_path: Local filesystem path to the root .pbip directory. workspace_id: Target Fabric / Power BI workspace ID (UUID). refresh_daily_hour: Daily UTC hour (0-23) for scheduled refresh (default: 6 AM UTC). findings_json: Optional list or JSON string of pre-existing audit findings to evaluate. gate_profile: Quality gate profile ("strict", "standard", "lenient"). auth_mode: "interactive" (browser login) or "service_principal". When omitted, PBI_AUTH_MODE is used, falling back to "interactive". tenant_id: Azure AD tenant ID. client_id: Azure AD client ID. dry_run: When True (default) evaluates the gate and reports the planned operations WITHOUT calling any Fabric API. Pass dry_run=False to actually publish. mock: If True, simulate deployment without calling external APIs.

Returns: Dict with deployment status, gate evaluation results, published item IDs, and refresh configuration.

Trigger, monitor, and optionally wait for a Power BI dataset refresh.

Use this tool when the user asks to:

• Refresh data in a published Power BI semantic model.

• Check the completion status of a refresh operation.

• Perform full, automatic, or data-only refreshes.

Args: workspace_id: Fabric / Power BI workspace ID (UUID). dataset_id: Dataset / semantic model ID (UUID). refresh_type: "full", "automatic", "data_only", "calculate", or "clearValues". wait: Whether to poll and wait for the refresh to complete before returning. timeout_s: Maximum wait time in seconds (default: 1800). auth_mode: "interactive" or "service_principal". When omitted, PBI_AUTH_MODE is used, falling back to "interactive". tenant_id: Azure AD tenant ID. client_id: Azure AD client ID. dry_run: When True (default) no refresh is triggered and status is "DryRun". Pass dry_run=False to actually refresh.

Returns: Dict with refresh status, duration, error details, and rollback status if applicable.

Run DAX queries against a baseline and assert regression tolerance.

Use this tool when the user asks to:

• Verify that measures or models return consistent results across changes.

• Compare live DAX calculation outputs against a golden baseline file.

• Check numerical tolerances on calculation outputs during CI/CD.

Args: baseline_path: Path to the JSON baseline file containing expected results. queries_json: Optional list or JSON string of DAX queries to execute. tolerance_pct: Maximum allowed percentage difference between actual and expected numeric values (default: 0.1%). workspace_id: Fabric / Power BI workspace ID holding the dataset. dataset_id: Published semantic model / dataset ID to query. auth_mode: "interactive" or "service_principal". tenant_id: Azure AD tenant ID. client_id: Azure AD client ID. fabric_client: Optional injected FabricClient instance (for testing).

Returns: Dict containing diff summary, passed/failed queries, and variance details. executed=False means no query ran and no verdict is available.

Execute a DAX query against a published Power BI semantic model / Fabric dataset.

Use this tool when the user asks to:

• Run, evaluate, or test a DAX query against a live dataset in Power BI or Fabric.

• Inspect actual business data, measure outputs, KPI calculations, or table rows.

• Verify Row-Level Security (RLS) filters by simulating a specific user principal name.

Args: workspace_id: Fabric / Power BI workspace ID (UUID). dataset_id: Published semantic model / dataset ID (UUID). dax_query: The DAX query expression (e.g. "EVALUATE TOPN(10, 'Sales')" or "EVALUATE ROW("Total", [Total Sales])"). impersonated_user_name: Optional User Principal Name (UPN) to test RLS rules as that user. auth_mode: "interactive" (default, browser login) or "service_principal". tenant_id: Azure AD tenant ID (required for service_principal). client_id: Azure AD client ID (for service_principal). max_rows: Maximum number of rows returned to the caller (default 1000, hard ceiling 10000). Prevents bulk extraction of business records into the model context. fabric_client: Optional injected FabricClient instance (for testing).

Returns: Dict containing query execution results with tabular rows, columns, and execution metadata.

Compare two semantic models and report structural differences.

Use this tool when the user asks to:

• Compare two versions of a Power BI model or PBIP directory.

• See what tables, columns, measures, or relationships changed between branches or releases.

Args: before: Path to the baseline PBIP directory. after: Path to the target PBIP directory.

Returns: Dict detailing added, removed, and modified tables, columns, measures, and relationships.

Evaluate audit findings against a pre-deployment quality gate profile.

Use this tool when the user asks to:

• Check whether audit findings block deployment or meet quality criteria.

• Validate findings against 'strict', 'standard', or 'lenient' governance gates.

Args: findings_json: List or JSON string of audit findings to evaluate. profile: Gate profile to evaluate against ("strict", "standard", "lenient").

Returns: Dict with gate decision (passed=True/False), blocking findings, and warnings.

Generate Markdown documentation and Mermaid ER diagram for a semantic model.

Use this tool when the user asks to:

• Document a Power BI dataset or semantic model.

• Generate a data dictionary listing all tables, columns, types, and descriptions.

• Create a Mermaid entity-relationship (ER) diagram of the model.

Args: pbip_path: Path to the .pbip directory. output_path: Optional file path to save the generated Markdown. inspector: Optional model inspector.

Returns: Dict with data dictionary markdown content, table count, measure count, and output path.

Apply a colorblind-safe theme, backfill visual alt text, and re-audit WCAG.

Use this tool when the user asks to:

• Make a report accessible and WCAG 2.1 compliant.

• Apply a colorblind-safe palette (e.g. Okabe-Ito, ColorBrewer).

• Automatically generate informative alt text for visuals lacking descriptions.

Args: pbip_path: Path to the .pbip directory. palette: Colorblind-safe palette name ("okabe_ito", "colorbrewer"). auto_backfill_alt_text: Whether to generate missing alt text on visuals. alt_text_template: Format template for generated alt text.

Returns: Dict with updated WCAG score, modified visual count, and theme update details.

Add a DAX measure to a semantic model with automated linting and validation.

Use this tool when the user asks to:

• Create or add a new DAX measure to a Power BI model.

• Validate DAX syntax and best practices (preventing division by zero, unformatted measures, etc.).

• Dry-run a measure to check for lint issues before committing to TMDL.

Args: target: Target PBIP directory or TMDL path. measure_name: Name of the measure to create. table: Target table where the measure will reside. expression: DAX formula for the measure (e.g. "DIVIDE([Total Sales], [Units], 0)"). format_string: Format string (e.g. "$#,##0.00", "0.0%"). description: Measure documentation or business description. is_hidden: Whether the measure should be hidden in report view. fail_on_severity: Minimum lint severity that blocks creation ("error", "warning", "info"). dry_run: If True (DEFAULT), validate lint rules without writing to disk. Pass dry_run=False explicitly to persist the measure. runtime_check: Whether to execute the measure against an active engine if connected. measure_writer: Optional custom measure writer callable. Not reachable from an MCP client — the server wires the modeling engine instead.

Returns: Dict with success status, lint findings, and modified file paths.

Rewrite a DAX expression in its shorter, equivalent form.

Use this tool when the user asks to:

• Simplify, tidy or shorten a DAX measure.

• Find the measures in a model that are written the long way.

• Replace a hand-rolled blank check, error check or IF chain with the function that already does it.

Args: expression: The DAX expression to simplify. Mutually exclusive with pbip_path. pbip_path: A PBIP project to read the measures from. measure: The measure to simplify. Requires pbip_path. all_measures: Simplify every measure in the project and report which ones could be written shorter. Requires pbip_path. apply_lint: Include the linter verdict before and after, so a rewrite that silences a finding — or creates one — is visible.

Returns: Dict with the simplified expression and the rewrites that produced it. The equivalence is structural: the expression is never evaluated against data, so the rewrite changes the shape and not the meaning, and a reader can check it. An expression that could not be parsed comes back unchanged, with the reason.

This tool writes nothing. To apply the result, pass the
simplified expression to add_measure_with_validation.

Find the logic that is written more than once in a semantic model.

Use this tool when the user asks to:

• Find duplicated or copy-pasted logic across measures.

• Know which measures compute the same thing and could share one.

• Find the measures that differ only in a number or a column, which is what a calculation group is for.

Args: pbip_path: Path to the root .pbip directory. table: Only look at the measures of this table. min_group_size: How many measures have to share a shape before it is reported. Two is the minimum.

Returns: Dict with the groups found and, for each, what the duplication looks like: which measures share it and where exactly they differ.

It does not write anything and does not apply the abstraction. A
Tabular measure cannot take a parameter, so the answer is a
calculation group, a helper table or a rewrite in place — and
which one is right depends on the model.

Propose shorter names for the measures and columns that need them.

Use this tool when the user asks to:

• Shorten, abbreviate or tidy up measure and column names.

• Find the names that have grown too long to read.

• Prepare a batch of renames before applying them.

Args: pbip_path: Path to the root .pbip directory. kind: "measures", "columns" or "both". max_length: Above this length, a name is a candidate. abbreviate_words: Shorten the words that have a standard abbreviation ("Amount" to "Amt", "Quantity" to "Qty"). drop_filler_words: Drop the words that carry no meaning ("of", "the", "in").

Returns: Dict with the proposals and a rename map ready for plan_change(intent="safe_rename").

It does not rename anything. A name that cannot be shortened
without changing what it says is reported as needing a name by
hand, and a proposal that would collide with an existing name
is adjusted.

Scaffold a PBIR report folder and layout from an existing semantic model.

Use this tool when the user asks to:

• Create a new report (.Report folder) for an existing dataset.

• Generate starter report pages with cards, charts, and an accessible theme.

Args: pbip_path: Path to the .pbip directory containing the dataset. page_name: Name of the initial report page (default: "Overview"). visual_count: Number of starter visuals to generate. theme: Theme name to apply (default: "okabe_ito"). include_card: Whether to generate a top-line KPI card visual. inspector: Optional model inspector.

Returns: Dict with created page path, visual IDs, and scaffolded report files.

Modify a visualContainer in a PBIR report page (type, fields, formatting, layout).

Use this tool when the user asks to:

• Edit, reformat, or resize a specific chart/visual on a report page.

• Change visual fields, bindings, alt text, or visibility.

Args: pbip_path: Path to the root .pbip directory. page_name: Name of the page containing the visual. visual_id: Unique ID of the visualContainer to edit. type: New visual type if changing (e.g. "barChart", "lineChart", "card"). fields_json: Optional dict or JSON string specifying field bindings to update. format_json: Optional dict or JSON string specifying formatting options. position_json: Optional dict or JSON string with x, y, width, height layout. alt_text: New alt text for accessibility. is_hidden: Whether to hide the visualContainer.

Returns: Dict with success status, changes applied, and page path.

Consolidate repetitive measures (e.g. YTD, QTD, PY) into calculation groups.

Use this tool when the user asks to:

• Refactor or clean up redundant DAX measures using calculation groups.

• Reduce model complexity and standardize time intelligence calculations.

Args: target: Target PBIP directory or TMDL path. min_candidates: Minimum measure patterns needed to trigger consolidation. reconcile_strategy: "strict" or "lenient". preserve_originals: Whether to keep original measures alongside the calculation group. auto_apply: If True, write calculation items immediately; if False, return proposed refactoring plan. inspector: Optional model inspector. measure_writer: Optional measure writer callable.

Returns: Dict with proposed or applied calculation items, candidate measures, and impact assessment.

Recommend optimal visual types and chart configurations for given KPIs.

Use this tool when the user asks to:

• Choose the best charts or visual types for a specific set of KPIs or metrics.

• Tailor visual recommendations to an audience ('executive', 'analytical', 'operational').

• Get primary and alternative chart suggestions with rationale based on data types.

Args: kpis_json: List of KPIs or JSON string (each with name, semantic_type, fields, etc.). audience: Target persona ("executive", "analytical", "operational"). max_results: Maximum number of alternative visual recommendations per KPI. inspector: Optional model inspector providing column cardinality and schema info.

Returns: Dict with recommended primary visual, alternatives, and rationale for each KPI.

Synthesize a complete PBIR report page layout from a natural language brief.

Use this tool when the user asks to:

• Design or generate a new Power BI report page based on business requirements.

• Automatically select, size, position, and format visuals matching an analytical goal.

• Apply professional color schemes and visual hierarchy to a page.

Args: pbip_path: Path to the target .pbip directory. brief: Natural language description of what the report page should convey. page_name: Display name for the newly created report page (default: "Overview"). audience: Target audience ("executive", "analytical", "operational"). palette: Color palette name (default: "okabe_ito"). inspector: Optional model inspector for schema context.

Returns: Dict containing synthesized visual containers, positions, and page metadata.

Analyze PBIR report pages for visual performance bottlenecks and anti-patterns.

Use this tool when the user asks to:

• Diagnose slow-loading report pages or improve visual performance.

• Identify excessive visual density, expensive custom visuals, or unoptimized filters.

Args: pbip_path: Path to the .pbip directory. target_load_ms: Desired maximum page load latency in milliseconds (default: 5000 ms).

Returns: Dict with performance score (0-100), estimated load time, and actionable recommendations.

Evaluate report storytelling, visual hierarchy, cognitive load, and UX design.

Use this tool when the user asks to:

• Audit report design quality, narrative flow, or visual hierarchy.

• Check if a report follows dashboard best practices for a specific audience.

Args: pbip_path: Path to the .pbip directory. page_name: Optional specific page name to audit; audits all pages if omitted. audience_assumed: Target audience ("executive", "analytical", "operational"). strictness: Scoring strictness ("lenient", "standard", "strict").

Returns: Dict with UX score (0-100), category breakdowns (hierarchy, density, narrative), and suggestions.

Capture screenshots or structural wireframes of Power BI report pages.

Use this tool when the user asks to:

• Visually inspect or capture report pages for reviews or regression diffs.

• Generate SVG wireframes or image snapshots of PBIR layouts.

Args: pbip_path: Path to the .pbip directory. pages: Optional list of specific page names to capture. format: Output format ("png", "svg", "pdf"). resolution: Target resolution ("desktop", "mobile", "tablet"). output_dir: Directory where captured images are written. wait_ms: Time in ms to wait for visual rendering.

Returns: Dict with output image paths, warnings, and rendering metadata.

Generate a TMDL semantic model and PBIP project from a declarative schema spec.

Use this tool when the user asks to:

• Create, scaffold, or generate a new Power BI semantic model from scratch.

• Define tables, columns, data types, relationships, and hierarchies declaratively.

Args: spec_yaml: YAML specification of tables, columns, types, and relationships. spec_json: JSON specification (either as a string or a structured object/dict). output_pbip_path: Target directory to write the generated .pbip project. dry_run: If True, validate specification without writing files to disk.

Returns: Dict with tables created, relationships created, hierarchies created, and validation status.

Configure Row-Level Security (RLS) roles and validation rules in a TMDL model.

Use this tool when the user asks to:

• Set up, add, or configure RLS roles and DAX table filter expressions.

• Test and validate security rules against sample queries.

Args: target: Target PBIP directory or TMDL path. spec_yaml: YAML specification of security roles, members, and DAX filters. spec_json: JSON specification (either as a string or a structured object/dict). dry_run: If True, validate role specification without writing to disk. rollback_on_test_failure: Whether to revert modifications if test queries fail.

Returns: Dict with roles created, test query outcomes, and rollback status if applicable.

Promote artifacts across Microsoft Fabric Deployment Pipeline stages.

Use this tool when the user asks to:

• Promote or move items between Fabric deployment stages (e.g. dev to test, test to prod).

• Run pre-promotion quality gates before moving items.

Args: pipeline_id: Fabric deployment pipeline ID (UUID). source_stage: Source stage ("dev", "test", "prod"). target_stage: Target stage ("test", "prod"). items: Optional list of specific item IDs to promote. Promotes all if omitted. dry_run: If True (DEFAULT), validate stages and gate checks without triggering actual promotion. Pass dry_run=False explicitly to promote for real — this moves live artifacts between stages.

Returns: Dict with promotion status, gate outcomes, and affected items.

Export and commit a Fabric workspace into a local Git repository.

Use this tool when the user asks to:

• Back up or version-control a Fabric workspace into Git.

• Snapshot reports and semantic models into local PBIP files with Git commits.

Args: workspace_id: Source Fabric workspace ID (UUID). output_repo_path: Local path to destination Git repository. branch: Git branch to commit into. commit_message: Commit message describing the snapshot. exclude_items: Optional list of item IDs to exclude. dry_run: If True, inspect items without creating git commits.

Returns: Dict with committed items, commit SHA, and repository status.

Deploy a local Git repository with PBIP projects to a Fabric workspace.

Use this tool when the user asks to:

• Synchronize or publish a local Git repository or branch to a Fabric workspace.

• Update workspace items based on version-controlled PBIP files.

Args: repo_path: Path to the local Git repository. workspace_id: Target Fabric workspace ID (UUID). branch_or_commit: Git ref to sync (default: "HEAD"). conflict_resolution: Conflict handling strategy ("manual", etc.). dry_run: If True, calculate changes without publishing.

Returns: Dict with synchronized items, skipped items, and deployment results.

Apply Microsoft Purview information protection sensitivity labels to items.

Use this tool when the user asks to:

• Classify or protect Power BI items (reports, semantic models, dashboards).

• Set Purview sensitivity labels (Confidential, General, Highly Confidential).

Args: items: List of dicts specifying item IDs and types (e.g. [{"id": "...", "type": "Report"}]). label_id: Microsoft Purview label GUID. label_name: Display name of the sensitivity label. admin_scopes: Optional list of administrative authorization scopes. redact_names: Whether to redact item names in returned logs for security. dry_run: If True, validate permissions without applying labels.

Returns: Dict with updated items, failed items, and compliance status.

Diagnose orchestrator health, detected modeling engines, and storage readiness.

Use this tool when the user asks to:

• Check if the Power BI MCP orchestrator is running properly.

• See which external tools/engines are installed (Tabular Editor, DAX optimizer, etc.).

• Get installation or setup instructions for missing components.

Args: include_engine_details: Whether to return full diagnostic info and remediation tips for each engine.

Returns: Dict with system status, engine availability matrix, active store counts, and remediation advice.