powerbi-orchestrator-mcp

Overview Schema Source Related Servers Discussions Admin

create_semantic_model_from_schema

Generate a Power BI semantic model and PBIP project from a YAML or JSON schema spec defining tables, columns, relationships, and hierarchies.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`dry_run`	No
`spec_json`	No
`spec_yaml`	No
`output_pbip_path`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.11.0Oct 2, 2026
- removedInput schema / properties / spec_json / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
First observedv0.1.0Sep 10, 2026

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does disclose that dry_run validates without writing files and that output lands as a .pbip project on disk, but it says nothing about overwrite behavior when output_pbip_path already contains a project, required permissions, or the odd empty-string default of output_pbip_path (where does it write then?).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence, then a bulleted trigger list, then Args/Returns. Given 0% schema coverage the Args block earns its space; nothing is redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the Returns text is a redundant but harmless convenience. The description is nearly complete for a file-writing generator: params are fully explained. The residual gap is mutation safety semantics (overwrite/merge behavior) which is material for a tool that writes a project directory.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by documenting all four parameters: spec_yaml, spec_json (string or structured object), output_pbip_path, and dry_run semantics. It omits the key relationship between spec_yaml and spec_json (mutual exclusivity / precedence) and does not flag that dry_run defaults to true, leaving the agent to infer it from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generate a TMDL semantic model and PBIP project') plus the input modality ('from a declarative schema spec'). The 'from scratch' framing distinguishes it from sibling mutation tools like refactor_to_calculation_groups or create_report_from_dataset, which operate on existing artifacts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use triggers ('Create, scaffold, or generate a new Power BI semantic model from scratch') and enumerates the declarative constructs it handles. It never names an alternative tool or states when NOT to use it (e.g., modifying an existing model), so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.