Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-powerBI-to-report get the full catalog of workspaces and semantic models"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude-compatible MCP server for discovering Fabric/Power BI workspaces, querying semantic models, and returning executive answers as both text and self-contained HTML reports.
This repo wraps Microsoft's official powerbi-modeling-mcp. It relies entirely on the XMLA/TOM authentication path provided by that official tool.
list_semantic_models_in_workspace
get_known_workspace_catalog
plan_multi_semantic_report
execute_multi_semantic_report
execute_dax_query
execute_dax_report_query
execute_dax_dashboard_query (compatibility alias)
Related MCP server: Microsoft Fabric MCP Server
Use these commands for a one-time setup on a new device.
The setup installs production npm dependencies, uses the prebuilt dist/server.js, writes .env, updates Claude Desktop mcpServers, and writes the resolved absolute Node.js command into Claude config. On Windows it configures the Microsoft Modeling MCP command in this order:
native .exe -> local node_modules\.bin\powerbi-modeling-mcp.cmd -> npx fallbackIt also enforces:
Node.js >= 18
npm >= 9and configures:
POWERBI_MODELING_MCP_ARGS=--start --authmode=interactiveThis project does not use REST catalog login or device-login auth.
curl -fsSL https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/setup-claude-desktop.sh | bash -s -- --workspace "GSM - MKP Data & Reporting"The macOS setup resolves node with command -v node and writes that absolute path, for example /opt/homebrew/bin/node, into claude_desktop_config.json.
Use this when the MCP was already installed on the Mac and you want to remove the old Claude Desktop entry plus the old local repo, then install the latest version from main.
osascript -e 'quit app "Claude"' 2>/dev/null || true; CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"; if [ -f "$CONFIG" ]; then cp "$CONFIG" "$CONFIG.bak.$(date +%Y%m%d%H%M%S)"; node -e 'const fs=require("fs"); const p=process.argv[1]; const raw=fs.existsSync(p)?fs.readFileSync(p,"utf8").trim():"{}"; const cfg=raw?JSON.parse(raw):{}; if(cfg.mcpServers){ delete cfg.mcpServers["mcp-powerBI-to-report"]; } fs.writeFileSync(p, JSON.stringify(cfg,null,2));' "$CONFIG"; fi; rm -rf "$HOME/mcp-powerBI-to-report"; curl -fsSL https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/setup-claude-desktop.sh | bash -s -- --workspace "GSM - MKP Data & Reporting"This command creates a timestamped backup of claude_desktop_config.json before removing only mcpServers.mcp-powerBI-to-report.
if ! command -v brew >/dev/null 2>&1; then /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"; fi; eval "$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv 2>/dev/null || true)"; brew install git node; curl -fsSL https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/setup-claude-desktop.sh | bash -s -- --workspace "GSM - MKP Data & Reporting"Use this command first on company Windows devices. It uses node, npm, and git already available on PATH, validates Node.js 18+/npm 9+, clones or fast-forwards the repo, installs dependencies, writes Claude Desktop config, and exits with a clear error if the repo has local changes.
$ErrorActionPreference="Stop"; Set-Location $HOME; Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -like "Claude*" } | Stop-Process -Force; if ($env:NODE_PORTABLE_HOME -and (Test-Path (Join-Path $env:NODE_PORTABLE_HOME "node.exe"))) { $env:Path="$env:NODE_PORTABLE_HOME;$env:Path" }; $dir=Join-Path $HOME "mcp-powerBI-to-report"; $nodeCmd=Get-Command node.exe -ErrorAction SilentlyContinue; if (-not $nodeCmd) { $nodeCmd=Get-Command node -ErrorAction SilentlyContinue }; if (-not $nodeCmd) { throw "Node.js 18+ is required but node was not found on PATH" }; $npmCmd=Get-Command npm.cmd -ErrorAction SilentlyContinue; if (-not $npmCmd) { $npmCmd=Get-Command npm -ErrorAction SilentlyContinue }; if (-not $npmCmd) { throw "npm 9+ is required but npm was not found on PATH" }; $gitCmd=Get-Command git.exe -ErrorAction SilentlyContinue; if (-not $gitCmd) { $gitCmd=Get-Command git -ErrorAction SilentlyContinue }; if (-not $gitCmd) { throw "Git is required but git was not found on PATH" }; $nodeExe=$nodeCmd.Source; $nodeVersionText=(& $nodeExe -v).Trim(); if ($LASTEXITCODE -ne 0) { throw "node failed" }; $nodeMajor=[int]($nodeVersionText.TrimStart([char]"v").Split(".")[0]); if ($nodeMajor -lt 18) { throw "Node.js 18 or newer is required. Current: $nodeVersionText at $nodeExe" }; $npmVersionText=(& $npmCmd.Source -v).Trim(); if ($LASTEXITCODE -ne 0) { throw "npm failed" }; $npmMajor=[int]($npmVersionText.Split(".")[0]); if ($npmMajor -lt 9) { throw "npm 9 or newer is required. Current: $npmVersionText" }; Write-Host "Using Node: $nodeExe ($nodeVersionText)"; Write-Host "Using npm: $($npmCmd.Source) ($npmVersionText)"; if (-not (Test-Path "$dir\.git")) { git clone "https://github.com/nguyenanhducdeveloper86/mcp-powerBI-to-report.git" $dir; if ($LASTEXITCODE -ne 0) { throw "git clone failed" } } else { Set-Location $dir; git pull --ff-only; if ($LASTEXITCODE -ne 0) { throw "git pull failed. Resolve local changes before continuing." } }; Set-Location $dir; & $npmCmd.Source install --omit=dev --include=optional; if ($LASTEXITCODE -ne 0) { throw "npm install failed" }; powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\setup-claude-desktop.ps1" -Workspace "GSM_MCP_POC_WORKSPACE" -NodeCommand $nodeExe -SkipInstall; if ($LASTEXITCODE -ne 0) { throw "Claude Desktop setup failed" }; Write-Host "Installation completed successfully. Start Claude Desktop again."This is the normal Windows setup command. Do not use the corporate npm command below unless npm fails because of corporate certificate/proxy behavior.
The setup script writes the resolved absolute node.exe path into claude_desktop_config.json, so Claude Desktop uses the same Node runtime later.
Portable Node.js is optional. If a device needs it, set NODE_PORTABLE_HOME first, then run the standard command:
$env:NODE_PORTABLE_HOME="D:\ApprovedTools\node-v22.12.0-win-x64"Expected success output includes:
Claude Desktop config updated: C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json
Local env written: C:\Users\<you>\mcp-powerBI-to-report\.env
Start Claude Desktop again, then use MCP server: mcp-powerBI-to-reportClose Claude Desktop completely before running setup. Use Quit from the system tray, not just the window close button, so Claude does not overwrite claude_desktop_config.json while setup is editing it.
The Windows setup script also stops running Claude Desktop processes before writing config, backs up the existing config, recovers from the latest valid backup if the current config is invalid JSON, writes through a temp file, then validates JSON before and after replacing the live config.
Use this only when the normal command fails because the company network requires temporary npm SSL compatibility. It still requires node, npm, and git on PATH.
$dir="$HOME\mcp-powerBI-to-report"; if (!(Test-Path "$dir\.git")) { git clone https://github.com/nguyenanhducdeveloper86/mcp-powerBI-to-report.git $dir }; cd $dir; powershell -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1 -Workspace "GSM_MCP_POC_WORKSPACE" -CorporateNpm -Clean-CorporateNpm is a temporary compatibility mode for approved test environments. It only sets npm_config_strict_ssl=false inside the installer process, cleans npm cache, then removes that override in finally. It does not bypass gateway blocks such as 403 MediaTypeBlocked. The preferred enterprise path is still:
internal npm registry
trusted Root CA via npm cafile / NODE_EXTRA_CA_CERTS
gateway whitelist
approved offline provisioning of the Microsoft binary
Use this if the repo is already cloned, the working tree is dirty, or you want to skip git pull.
$ErrorActionPreference="Stop"; Set-Location $HOME; if ($env:NODE_PORTABLE_HOME -and (Test-Path (Join-Path $env:NODE_PORTABLE_HOME "node.exe"))) { $env:Path="$env:NODE_PORTABLE_HOME;$env:Path" }; $dir=Join-Path $HOME "mcp-powerBI-to-report"; if (-not (Test-Path "$dir\.git")) { throw "Repository not found: $dir" }; $nodeCmd=Get-Command node.exe -ErrorAction SilentlyContinue; if (-not $nodeCmd) { $nodeCmd=Get-Command node -ErrorAction SilentlyContinue }; if (-not $nodeCmd) { throw "Node.js 18+ is required but node was not found on PATH" }; $npmCmd=Get-Command npm.cmd -ErrorAction SilentlyContinue; if (-not $npmCmd) { $npmCmd=Get-Command npm -ErrorAction SilentlyContinue }; if (-not $npmCmd) { throw "npm 9+ is required but npm was not found on PATH" }; $nodeExe=$nodeCmd.Source; $nodeVersionText=(& $nodeExe -v).Trim(); $nodeMajor=[int]($nodeVersionText.TrimStart([char]"v").Split(".")[0]); if ($nodeMajor -lt 18) { throw "Node.js 18 or newer is required. Current: $nodeVersionText at $nodeExe" }; $npmVersionText=(& $npmCmd.Source -v).Trim(); $npmMajor=[int]($npmVersionText.Split(".")[0]); if ($npmMajor -lt 9) { throw "npm 9 or newer is required. Current: $npmVersionText" }; Set-Location $dir; & $npmCmd.Source install --omit=dev --include=optional; if ($LASTEXITCODE -ne 0) { throw "npm install failed" }; powershell -ExecutionPolicy Bypass -File scripts\setup-claude-desktop.ps1 -Workspace "GSM_MCP_POC_WORKSPACE" -NodeCommand $nodeExe -SkipInstall; if ($LASTEXITCODE -ne 0) { throw "Claude Desktop setup failed" }; Write-Host "Installation completed successfully. Start Claude Desktop again."Use this only when raw.githubusercontent.com is allowed and you want to run only the installer script directly.
iwr -UseBasicParsing "https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/install-windows.ps1" -OutFile "$env:TEMP\install-powerbi-mcp.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-powerbi-mcp.ps1" -Workspace "GSM_MCP_POC_WORKSPACE"If company policy blocks Homebrew, winget, or app installation, ask IT to install:
Git
Node.js LTS, which includes npm
Claude Desktop
Then run the matching setup command above again.
After setup, start Claude Desktop again and test:
Use mcp-powerBI-to-report to diagnose the local Power BI MCP setup.Then test Power BI access:
Use mcp-powerBI-to-report to list semantic models in workspace GSM - MKP Data & Reporting.Prerequisites:
Node.js 18 or newer
git
git clone https://github.com/nguyenanhducdeveloper86/mcp-powerBI-to-report.git
cd mcp-powerBI-to-report
npm install --omit=dev --include=optional
npm run setupOn macOS, npm install --omit=dev --include=optional also ad-hoc signs the Microsoft native Modeling MCP binary so Claude can launch it without the unsigned-binary failure.
On Windows, npm run setup and the PowerShell installer resolve the Modeling MCP command in this order:
node_modules\@microsoft\powerbi-modeling-mcp-win32-x64\dist\powerbi-modeling-mcp.exe
node_modules\.bin\powerbi-modeling-mcp.cmd
npxnpm run setup asks for:
Microsoft powerbi-modeling-mcp command and args
Known workspace names
Default CEO workspace
Optional default semantic model fallback
Optional HTML report output folder
It writes a local .env file with mode 0600. The MCP server loads this file automatically on start.
The fastest path is the bundled Claude Desktop setup script. It detects macOS vs Windows shells, installs dependencies, uses the prebuilt dist/server.js, writes .env, backs up Claude Desktop config, and merges the MCP server into mcpServers. On Windows it prefers the native Microsoft Modeling MCP .exe, then the local .cmd shim, then npx.
From an existing clone:
bash scripts/setup-claude-desktop.sh --workspace "GSM - MKP Data & Reporting"From a fresh machine:
git clone https://github.com/nguyenanhducdeveloper86/mcp-powerBI-to-report.git
cd mcp-powerBI-to-report
bash scripts/setup-claude-desktop.sh --workspace "GSM - MKP Data & Reporting"Or one command that clones to ~/mcp-powerBI-to-report when needed:
curl -fsSL https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/setup-claude-desktop.sh | bash -s -- --workspace "GSM - MKP Data & Reporting"Windows should run the same command from Git Bash. The script writes Windows-native paths into Claude Desktop config and prefers:
node_modules\@microsoft\powerbi-modeling-mcp-win32-x64\dist\powerbi-modeling-mcp.exeIf that binary is missing, it uses:
node_modules\.bin\powerbi-modeling-mcp.cmdIf both local commands are missing, it falls back to:
npx -y @microsoft/powerbi-modeling-mcp@latest --start --authmode=interactivePowerShell users should use the native PowerShell setup script, not curl -fsSL:
cd C:\Users\<you>\mcp-powerBI-to-report
powershell -ExecutionPolicy Bypass -File scripts\setup-claude-desktop.ps1 -Workspace GSM_MCP_POC_WORKSPACEIf downloading from GitHub in PowerShell, use Invoke-WebRequest:
iwr -UseBasicParsing "https://raw.githubusercontent.com/nguyenanhducdeveloper86/mcp-powerBI-to-report/main/scripts/setup-claude-desktop.ps1" -OutFile setup-claude-desktop.ps1
powershell -ExecutionPolicy Bypass -File .\setup-claude-desktop.ps1 -Workspace GSM_MCP_POC_WORKSPACEOptional npm alias:
npm run setup:claude-desktop -- --workspace "GSM - MKP Data & Reporting"PowerShell npm alias:
npm run setup:claude-desktop:powershell -- -Workspace GSM_MCP_POC_WORKSPACEAfter the script finishes, restart Claude Desktop completely.
OS | Path |
macOS |
|
Windows (standard) |
|
Windows (Store/MSIX) |
|
Important: Close Claude Desktop completely before editing the config file. Otherwise Claude can overwrite the file and remove
mcpServers.
Minimal config (uses env vars from the .env file written by npm run setup):
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "node",
"args": ["/absolute/path/to/mcp-powerBI-to-report/dist/server.js"]
}
}
}Full config with explicit env overrides:
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "node",
"args": ["/absolute/path/to/mcp-powerBI-to-report/dist/server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "/absolute/path/to/powerbi-modeling-mcp",
"POWERBI_MODELING_MCP_ARGS": "--start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "/absolute/path/to/powerbi-report-output"
}
}
}
}macOS example — Apple Silicon (M1/M2/M3):
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "/opt/homebrew/bin/node",
"args": ["/Users/<you>/mcp-powerBI-to-report/dist/server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "/Users/<you>/mcp-powerBI-to-report/node_modules/@microsoft/powerbi-modeling-mcp-darwin-arm64/dist/powerbi-modeling-mcp",
"POWERBI_MODELING_MCP_ARGS": "--start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "/Users/<you>/powerbi-report-output"
}
}
}
}macOS example — Intel (x64):
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "/usr/local/bin/node",
"args": ["/Users/<you>/mcp-powerBI-to-report/dist/server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "/Users/<you>/mcp-powerBI-to-report/node_modules/@microsoft/powerbi-modeling-mcp-darwin-x64/dist/powerbi-modeling-mcp",
"POWERBI_MODELING_MCP_ARGS": "--start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "/Users/<you>/powerbi-report-output"
}
}
}
}macOS note:
npm install --omit=dev --include=optionalautomatically ad-hoc signs the Microsoft native binary. If Claude Desktop shows an error launching the binary, run that command again from the project directory, then restart Claude Desktop.
Windows example with native .exe:
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "C:\\Users\\<you>\\Tools\\node-v22.12.0-win-x64\\node.exe",
"args": ["C:\\Users\\<you>\\mcp-powerBI-to-report\\dist\\server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "C:\\Users\\<you>\\mcp-powerBI-to-report\\node_modules\\@microsoft\\powerbi-modeling-mcp-win32-x64\\dist\\powerbi-modeling-mcp.exe",
"POWERBI_MODELING_MCP_ARGS": "--start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "C:\\Users\\<you>\\powerbi-report-output"
}
}
}
}Windows example with local .cmd shim:
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "C:\\Users\\<you>\\Tools\\node-v22.12.0-win-x64\\node.exe",
"args": ["C:\\Users\\<you>\\mcp-powerBI-to-report\\dist\\server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "C:\\Users\\<you>\\mcp-powerBI-to-report\\node_modules\\.bin\\powerbi-modeling-mcp.cmd",
"POWERBI_MODELING_MCP_ARGS": "--start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "C:\\Users\\<you>\\powerbi-report-output"
}
}
}
}Windows example with npx fallback:
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "C:\\Users\\<you>\\Tools\\node-v22.12.0-win-x64\\node.exe",
"args": ["C:\\Users\\<you>\\mcp-powerBI-to-report\\dist\\server.js"],
"env": {
"POWERBI_KNOWN_WORKSPACES": "your-workspace-name",
"POWERBI_DEFAULT_WORKSPACE": "your-workspace-name",
"POWERBI_DEFAULT_SEMANTIC_MODEL": "your-model-name",
"POWERBI_MODELING_MCP_COMMAND": "C:\\Program Files\\nodejs\\npx.cmd",
"POWERBI_MODELING_MCP_ARGS": "-y @microsoft/powerbi-modeling-mcp@latest --start --authmode=interactive",
"POWERBI_REPORT_OUTPUT_DIR": "C:\\Users\\<you>\\powerbi-report-output"
}
}
}
}Windows note: the bridge launches
.cmdcommands andnpxthrough the Windows shell. Without that behavior, Node can fail withspawn npx ENOENTon Windows.
A ready-to-edit example file is at docs/claude-desktop-config.example.json.
{
"mcpServers": {
"mcp-powerBI-to-report": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/mcp-powerBI-to-report/src/server.ts"]
}
}
}Claude agents can generate or write Claude Desktop configuration with:
npm run setup:agent -- --workspaces your-workspace-nameWrite directly to Claude Desktop config with an automatic backup:
npm run setup:agent -- --workspaces your-workspace-name --write-desktop-configThis MCP entirely delegates authentication to the underlying Microsoft @microsoft/powerbi-modeling-mcp tool.
It uses the Microsoft Modeling MCP interactive auth mode or explicit authentication arguments configured via POWERBI_MODELING_MCP_ARGS.
Ask Claude:
Use mcp-powerBI-to-report to diagnose the local Power BI MCP setup.If diagnostics are clean, ask Claude:
Use mcp-powerBI-to-report to list semantic models in workspace GSM - MKP Data & Reporting.The workspace name must be known and provided. If the workspace/model is not provided, Claude should ask the user for the workspace name instead of guessing.
For a CEO workflow, set:
POWERBI_KNOWN_WORKSPACES="GSM - MKP Data & Reporting"
POWERBI_DEFAULT_WORKSPACE="GSM - MKP Data & Reporting"
# Optional fallback only. Prefer letting Claude choose from workspace schema.
# POWERBI_DEFAULT_SEMANTIC_MODEL=hospital
# Optional folder for generated HTML reports.
# POWERBI_REPORT_OUTPUT_DIR=/path/to/powerbi-report-outputThen Claude can use get_known_workspace_catalog to list models from configured workspaces, choose the relevant semantic model from schema/context, and call execute_dax_report_query for follow-up business questions. The wrapper keeps the Microsoft Modeling MCP process alive, so repeated questions reuse the same process and reduce repeated login prompts.
execute_dax_report_query returns:
concise text summary for chat
insights for detected executive findings such as highest/lowest revenue month and returned data drivers
insightCards with structured what, why, soWhat, action, confidence, evidence, and missing-data notes
dataProfile with detected measures, dimensions, row/column counts, and gaps that limit deeper root-cause analysis
nextQuestions for CEO/MBA-style drill-down prompts
structuredContent with rows, columns, and generated HTML
embedded MCP text/html resource
reportPath and reportUri for opening the generated local .html file
Use execute_dax_query only when raw query output is enough.
One CEO question can require evidence from more than one semantic model. For example, revenue may live in sale_vehicle-vf, while campaign spend, leads, inventory, dealer coverage, or finance margin can live in separate semantic models.
Recommended agent flow:
question
→ get_known_workspace_catalog
→ plan_multi_semantic_report
→ write one DAX query per semantic model/evidence role
→ execute_multi_semantic_report
→ return text answer + HTML reportplan_multi_semantic_report helps the agent decide:
whether one or multiple semantic models are needed
decision intent such as variance_decomposition, opportunity_prioritization, portfolio_decision, or forecast_risk
required evidence
recommended model roles
join grain and join keys
dashboard blocks for the ReportSpec
warnings when evidence is missing or cannot prove causality
execute_multi_semantic_report accepts multiple DAX queries:
{
"question": "Doanh thu VF tháng nào cao nhất và tại sao?",
"grain": "Month x Province x Model",
"joinKeys": ["Month", "Province", "Model"],
"queries": [
{
"workspaceName": "GSM - MKP Data & Reporting",
"semanticModelName": "sale_vehicle-vf",
"evidenceRole": "sales",
"evidence": ["Revenue", "UnitsSold", "Model", "Province"],
"query": "EVALUATE ..."
},
{
"workspaceName": "GSM - MKP Data & Reporting",
"semanticModelName": "marketing-vf",
"evidenceRole": "marketing",
"evidence": ["CampaignSpend", "Leads", "ConversionRate"],
"query": "EVALUATE ..."
}
]
}The report tags rows with DataSource, WorkspaceName, SemanticModelName, and EvidenceRole. For audit compatibility, combined rows remain in structuredContent.rows, but the HTML report does not force all semantic models into one chart. It keeps each query result as a separate dataset, profiles the returned shape, and renders dataset-specific evidence blocks:
data sources and evidence quality
join grain, join keys, and confidence
validation warnings when semantic models are at different grains
dataset profiles with detected grain, metrics, dimensions, and visual shape
time-series blocks for time-grain datasets
ranking/contribution blocks for categorical datasets
cross-dimension pocket blocks when multiple dimensions are returned
metric scorecards or evidence tables when the query is too shallow for stronger visuals
an executive synthesis board showing what each semantic model can prove, what decision it supports, and what evidence is still missing
Important rule: if semantic models do not share the requested grain, the report should stay in source-separated evidence mode and describe cross-source findings as directional correlation, not proven causality. To compare or join models directly, the agent must aggregate each DAX query to the same joinKeys first, for example Month x Province x Model.
For questions like:
Tháng nào có doanh thu thấp nhất, cao nhất và tại sao?Prefer execute_dax_report_query and write DAX that returns:
a month/date period column
a numeric revenue/sales/doanh thu column
explanatory driver columns when the model has them, such as order count, customer count, average ticket, product/category, region, branch, or channel
The report generator automatically detects the month and revenue columns, aggregates revenue by month, and returns the highest and lowest months in summary and insights. For explanation questions (why, tại sao, vì sao, highest/lowest), it also runs an evidence sufficiency gate before rendering:
scan semantic model columns with INFO.COLUMNS()
infer available dimensions such as Region, Model, Province, Dealer, Campaign
infer drivers such as units, ASP, margin, discount, marketing, inventory, market share
infer the focus period from the question or returned rows
run slice gap queries by available dimensions and cross-dimensions
render an Evidence acquired before conclusion section showing what was queried and what schema is genuinely missing
The HTML report also adds an executive decision layer with What happened, Why it happened, So what, revenue bridge, driver tree, decision levers, run-rate read, and evidence tables. If the semantic model lacks fields such as Dealer, Campaign, Lead, or Conversion, the report marks those as missing only after schema scan.
Example DAX query shape:
EVALUATE
SUMMARIZECOLUMNS(
'Date'[YearMonth],
'Product'[Category],
'Region'[RegionName],
"Revenue", [Revenue],
"Orders", [Orders],
"Customers", [Customers],
"Average Ticket", DIVIDE([Revenue], [Orders])
)
ORDER BY 'Date'[YearMonth]For the simplest CEO experience:
Keep Claude Desktop and this MCP server running during the working session.
Avoid restarting Claude between related questions.
Configure POWERBI_DEFAULT_WORKSPACE and POWERBI_DEFAULT_SEMANTIC_MODEL.
Configure POWERBI_KNOWN_WORKSPACES and POWERBI_DEFAULT_WORKSPACE.
Treat POWERBI_DEFAULT_SEMANTIC_MODEL as an optional fallback, not a required CEO input.
Ask business questions in plain language; Claude should generate DAX and call execute_dax_report_query.
The first query in a fresh session can still trigger Microsoft authentication. Follow-up queries in the same running MCP session reuse the existing Microsoft Modeling MCP process and connection.
Reports are generated as standalone HTML files with:
KPI cards for numeric measures
executive answer, driver tree, revenue bridge, decision levers, and run-rate read
executive insight layers: WHAT, WHY, SO WHAT, and NOW WHAT
contribution analysis across detected dimensions
native self-contained SVG chart formats selected from returned data shape: line chart, combo bar+line chart, pie chart, donut chart, scatter plot, and map chart
cross-dimension pockets such as Province x Model, Region x Model, or any dimension pair returned by the query
risk/opportunity watch based on returned operational drivers such as margin, discount, inventory, marketing, and market share
multi-semantic dataset blocks that choose chart/layout from the returned data shape instead of a fixed template
chart governance rules closer to Power BI reporting practice: line for time series, ranked bar for larger category sets, donut only for small part-to-whole mixes, heatmap for cross-dimension pockets, scatter only for sufficient numeric observations, and map only for true geography fields
next-best business questions for CEO drill-down
question, workspace, semantic model, and DAX query context
Raw returned rows remain available in MCP structuredContent.rows for audit/debug. Multi-semantic runs also expose structuredContent.datasets and structuredContent.datasetProfiles so agents can inspect why a specific dashboard block was chosen. The HTML report is designed as a decision brief rather than a raw data table.
Files are written to POWERBI_REPORT_OUTPUT_DIR when set, then POWERBI_DASHBOARD_OUTPUT_DIR for compatibility, otherwise ./powerbi-report-output from the MCP process working directory.
Copy .env.example for local shell usage:
cp .env.example .envThen export values before running:
set -a
source .env
set +a
npm run devThe Microsoft Modeling MCP bridge uses npx -y @microsoft/powerbi-modeling-mcp@latest --start by default. Override with POWERBI_MODELING_MCP_COMMAND and POWERBI_MODELING_MCP_ARGS if you have a signed local binary.
Local verification notes are in docs/verification.md.
Show which Power BI authentication mode is configured without exposing tokens.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that tokens are not exposed, a key safety trait. However, with no annotations, it lacks details on prerequisites (e.g., requires prior authentication) or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and key constraint, no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete enough for a simple parameterless tool. Minor gap: does not specify the output format (e.g., string, structured data), but the purpose is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and full schema coverage, the description adds context about the tool's purpose. Baseline is 4 for no-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows the authentication mode without exposing tokens. The title and description align, and the tool is distinct from siblings like login flows and queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied (checking auth status before other operations), but no explicit guidance on when to use or alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll Microsoft for the pending device-code login and cache the token when authorization is complete.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions polling and caching but lacks details on retries, timeouts, or side effects (e.g., overwriting existing tokens).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence of 15 words, efficiently stating the tool's action without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple poll-and-cache tool with no parameters or output schema, but it could add context that it should be called after start_device_login and that it blocks until complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema coverage is 100%. The description adds no parameter info, but the baseline is 4 since no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool polls for pending device-code login and caches the token, clearly distinguishing it from siblings like start_device_login (which initiates) and auth_status (which checks status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after start_device_login but provides no explicit guidance on when to use this tool versus alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Alias for execute_dax_report_query kept for compatibility with earlier dashboard workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | DAX query text, for example EVALUATE ROW("Revenue", SUM(Visits[TreatmentCost])). | |
| title | No | Optional dashboard title. Defaults to the question. | |
| maxRows | No | ||
| question | Yes | The business question from the executive user. | |
| workspaceName | No | Power BI workspace name. Defaults to POWERBI_DEFAULT_WORKSPACE. | |
| timeoutSeconds | No | ||
| semanticModelName | No | Semantic model name. Defaults to POWERBI_DEFAULT_SEMANTIC_MODEL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only labels it as an alias without disclosing any behavioral traits (e.g., side effects, data modification, permission requirements). This is insufficient for a mutation-capable tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys the essential information without unnecessary words. It is well-structured and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is a simple alias, the description does not explain its behavior or return values. Given the lack of output schema and moderate parameter count, the description is minimally adequate but could provide more context by referencing execute_dax_report_query's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 71% schema description coverage, the schema already explains most parameters. The description adds no additional parameter information, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it is an alias for execute_dax_report_query, clearly identifying its purpose and distinguishing it from siblings by naming the specific tool it replaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is for compatibility with earlier dashboard workflows, implying when to use (backward compatibility). It names the sibling it aliases, providing an alternative for new workflows, but lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a DAX query against a Power BI semantic model using default workspace/model when omitted. This keeps the Microsoft Modeling MCP process alive to reduce repeated login prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | DAX query text, for example EVALUATE ROW("Revenue", SUM(Visits[TreatmentCost])). | |
| maxRows | No | ||
| workspaceName | No | Power BI workspace name. Defaults to POWERBI_DEFAULT_WORKSPACE. | |
| timeoutSeconds | No | ||
| semanticModelName | No | Semantic model name. Defaults to POWERBI_DEFAULT_SEMANTIC_MODEL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It adds the behavioral note about keeping the Microsoft Modeling MCP process alive to reduce login prompts, but omits details on side effects, idempotency, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that front-load the main purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description does not explain the return format, error handling, or any post-execution behavior. The description is too brief to be considered complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, and the description does not add extra meaning beyond the schema's parameter descriptions. The mention of 'using default workspace/model when omitted' relates to default behavior rather than parameter semantics, so it provides minimal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Execute a DAX query) and the resource (Power BI semantic model), and mentions default workspace/model behavior, which distinguishes it from sibling tools like execute_dax_dashboard_query or execute_dax_report_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general DAX queries and mentions a keep-alive benefit, but does not explicitly state when to use this tool versus the dashboard or report query variants, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a DAX query against a Power BI semantic model and return both a concise text answer and a self-contained HTML dashboard/report for executive review. Prefer this tool for boss/CEO business questions.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | DAX query text, for example EVALUATE ROW("Revenue", SUM(Visits[TreatmentCost])). | |
| title | No | Optional report title. Defaults to the question. | |
| maxRows | No | ||
| question | Yes | The business question from the executive user. | |
| workspaceName | No | Power BI workspace name. Defaults to POWERBI_DEFAULT_WORKSPACE. | |
| timeoutSeconds | No | ||
| semanticModelName | No | Semantic model name. Defaults to POWERBI_DEFAULT_SEMANTIC_MODEL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry full behavioral disclosure. It mentions the output format but does not reveal side effects, authorization requirements, rate limits, error handling, or whether the operation is read-only. This is a significant gap for a tool that executes queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core action and output. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations exist. The description does not explain return values, error states, or prerequisites like Power BI access. For a tool with 7 parameters, more context is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 71% (5 of 7 parameters have descriptions in the schema). The description adds no additional meaning beyond what the schema provides, such as usage tips or format details. Baseline 3 is appropriate given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Execute', the resource 'DAX query against a Power BI semantic model', and the dual output 'concise text answer and self-contained HTML dashboard/report'. It also explicitly targets 'executive review' and 'boss/CEO business questions', distinguishing it from sibling tools like execute_dax_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Prefer this tool for boss/CEO business questions', providing clear context for when to use it. However, it does not explicitly exclude alternatives or state when not to use it, leaving some ambiguity relative to sibling tools like execute_dax_dashboard_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all visible workspaces and semantic models via Power BI REST API. This is the preferred tool for open-ended questions such as 'which model should I use?' or 'what workspaces can I access?'.
| Name | Required | Description | Default |
|---|---|---|---|
| includeMyWorkspace | No | Include My workspace datasets. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions it uses the Power BI REST API without disclosing behavioral traits like safety, side effects, or rate limits. It doesn't confirm it is read-only or describe any potential blocking or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences: one stating the action and resource, the other providing usage context. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description covers its purpose and usage context well. However, it doesn't describe the output structure, which could be helpful for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single boolean parameter fully. The description adds no additional meaning about the parameter beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns 'all visible workspaces and semantic models' and provides specific usage examples like 'which model should I use?' Distinguishes from siblings like list_workspaces which returns only workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies this as the 'preferred tool for open-ended questions' and gives example queries. While it doesn't explicitly exclude specific scenarios, the context is clear about its intended use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List semantic models for manually configured POWERBI_KNOWN_WORKSPACES using Microsoft Modeling MCP. Use this for CEO workflows when REST workspace discovery is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceNames | No | Optional workspace names. Defaults to POWERBI_KNOWN_WORKSPACES, then POWERBI_DEFAULT_WORKSPACE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as read-only nature, authentication requirements, or side effects. The operation is implicitly read-only, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key information without any superfluous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description covers the essential purpose, when to use, and the parameter behavior. It lacks details on potential errors or output format, but these are not critical given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter 'workspaceNames' is adequately described in the schema. The tool description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (list), resource (semantic models), and specific context (manually configured POWERBI_KNOWN_WORKSPACES using Microsoft Modeling MCP). It distinguishes from sibling tools by referencing the specific method and use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this for CEO workflows when REST workspace discovery is unavailable.' This indicates when to use and implies when not to, differentiating from REST-based alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List semantic models in My workspace or in a specific workspace by id. Use list_workspaces first to resolve workspace ids. If workspace discovery is not authenticated and the user did not name a workspace, ask the user which workspace to use.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace/group id. Omit for My workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavior fully. It only mentions listing models and workspace selection, but omits details about permissions, rate limits, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main purpose. It uses two sentences effectively without redundancy, but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the core functionality, usage prerequisites, and a fallback instruction. It is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the workspaceId parameter described adequately in the schema. The description adds contextual advice but does not significantly enhance parameter understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists semantic models in My workspace or a specific workspace by id. It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like list_semantic_models_in_workspace_via_modeling_mcp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to use list_workspaces first to resolve workspace ids and instructions for handling authentication and user input. Lacks explicit exclusion of when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use Microsoft powerbi-modeling-mcp/XMLA auth to list semantic models inside a known workspace name. This is a fallback when REST workspace discovery auth is unavailable. The workspace name must be explicit; if it is missing, ask the user instead of guessing.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceName | Yes | Exact Fabric/Power BI workspace name, for example 'test-mcp'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adds value by disclosing the authentication method (XMLA) and the fallback nature. It does not describe side effects or failure modes, but for a read-only list operation, the behavioral context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste: first sentence states action and auth, second gives fallback context, third gives parameter instruction. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter, the description covers purpose, usage context, and parameter guidance. It does not explain the return format, but given no output schema, this is acceptable. The description is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter with description. The description reinforces the requirement for an explicit workspace name and provides guidance on handling missing values, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action: list semantic models in a known workspace using XMLA auth, and distinguishes it as a fallback from REST-based tools. This clearly identifies the tool's purpose and separates it from siblings like 'list_semantic_models'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this tool is a fallback when REST workspace discovery auth is unavailable, providing clear when-to-use guidance. It also instructs to ask the user if workspace name is missing instead of guessing, offering a usage best practice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Fabric/Power BI workspaces visible to the authenticated account through the Power BI REST API. Use this first when the user does not provide a workspace name or id.
| Name | Required | Description | Default |
|---|---|---|---|
| includeMyWorkspace | No | Include the personal 'My workspace' pseudo-workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only mentions 'authenticated account' but lacks details like authentication requirements, rate limits, or behavior when no workspaces exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the purpose and immediately follows with usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description does not mention what is returned (e.g., list of workspace objects with properties). For a simple tool, it is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (parameter is described in schema). The main description does not add parameter details beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists all workspaces visible to the authenticated account via the Power BI REST API, which is a specific verb+resource combination. It distinguishes from siblings like list_semantic_models which list models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use this first when the user does not provide a workspace name or id,' giving explicit guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start delegated user device-code login for Power BI REST API. Use only for one-time local setup; service principal is recommended for production.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It does not disclose what the tool returns (e.g., a user code), how it behaves (blocking vs. async), or prerequisites, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by usage guidance. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the flow involving complete_device_login and auth_status, the description lacks context about the login process, expected output, or next steps, making it incomplete for an autonomous agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline score of 4 applies. Description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (start) and resource (delegated user device-code login for Power BI REST API), and distinguishes from siblings like complete_device_login by specifying it's for starting the login process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (one-time local setup) and recommends an alternative (service principal for production), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0auth_statuscomplete_device_loginexecute_dax_dashboard_queryexecute_dax_queryexecute_dax_report_queryget_catalogget_known_workspace_cataloglist_semantic_modelslist_semantic_models_in_workspace_via_modeling_mcplist_workspacesstart_device_loginScored across 11 tools
Most tools have distinct purposes, but `execute_dax_dashboard_query` is an explicit alias for `execute_dax_report_query`, creating redundancy. Additionally, multiple tools list semantic models via different methods (`list_semantic_models`, `list_semantic_models_in_workspace_via_modeling_mcp`, `get_catalog`), which could confuse an agent if descriptions are skimmed. However, the descriptions clearly indicate when each is appropriate, so ambiguity is minimal.
All tool names follow a consistent `verb_noun` pattern using snake_case. Verbs like `auth`, `complete`, `execute`, `get`, `list`, and `start` are clear and predictable. Even lengthy names like `list_semantic_models_in_workspace_via_modeling_mcp` adhere to the pattern. No mixing of naming conventions.
With 11 tools, the count is within the typical well-scoped range. However, there is some redundancy: three authentication tools and four listing tools, with an alias that could be merged. Slightly more than necessary for the domain, but justified by different authentication methods and fallback scenarios.
The tool set covers the full workflow for Power BI reporting: authentication, workspace discovery, semantic model listing, and DAX query execution that returns a report. Minor gaps exist, such as no direct tool to list reports or manage models, but the primary purpose of querying and generating reports is well-covered.
Governed BI MCP. Ask questions of live company data and list workspace sources via OAuth.
List datasets, schemas, run APL queries, and use prompts for exploration, anomalies, and monitoring.
Search, access, and get insights on your Amplitude data
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu