powerbi-desktop-mcp

propose_change

Destructive

Propose and validate an exact text replacement in a Power BI file copy and return a diff, affected objects, and risk for approval before editing.

Instructions

STEP 1 of any edit. Proposes replacing exact old_text with new_text in a file (.pbix .pbit .pbip .pbir .pbids .rdl .tmdl or PBIR .json). Changes NOTHING: validates the result and returns a diff, the affected objects and the risk. For .pbix/.pbit pass member. old_text must match exactly expected_count places. Show the user the diff verbatim and wait for explicit approval. Editing works only on COPIES inside the folder named by the PBI_MCP_EDIT_ROOT environment variable (off when unset); originals elsewhere are refused.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "old_text": "<old_text>",
      "new_text": "<new_text>",
      "reason": "<reason>"
    },
    "name": "propose_change"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`member`	No
`reason`	Yes
`new_text`	Yes
`old_text`	Yes
`expected_count`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 23, 2026

TDQS

A4.1/5.0

Behavior2/5

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

The description is behaviorally rich ('Changes NOTHING: validates the result and returns a diff, the affected objects and the risk', plus the env-var sandbox rule and member usage for .pbix/.pbit). But it directly conflicts with the declared destructiveHint=true: an agent cannot tell whether this call mutates state or not, and the reconciliation (that finish_change performs the write) is left implicit.

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

Conciseness4/5

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

Front-loaded with the step and the verb, then the no-mutation guarantee, then constraints. Six sentences is on the long side, but the approval workflow and sandbox rule are high-value and every sentence carries actionable information.

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 return-value detail is not required, and the description still names what comes back (diff, affected objects, risk). The sandbox and approval rules complete the operational picture; only the mutation-vs-destructiveHint ambiguity keeps it from being fully complete.

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% and all six parameters are bare titles, so the description must compensate; it does for the critical ones by defining exact-match semantics for old_text, the expected_count occurrence constraint, member for .pbix/.pbit, and implicitly the edit-root restriction on path. reason is never explained, which is the only meaningful gap.

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 ('proposes replacing exact old_text with new_text in a file') and enumerates the supported file types. The 'STEP 1 of any edit' framing distinguishes it cleanly from the sibling finish_change, which is obviously the later step.

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

Usage Guidelines5/5

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

Explicit routing: this is the mandatory first step of any edit, the diff must be shown verbatim and explicit approval obtained before proceeding. It also states the hard precondition that editing works only on copies under the PBI_MCP_EDIT_ROOT environment variable and that originals are refused, so the agent knows when a call will fail.

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