propose_change

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.

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.

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.

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.

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.

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.