pbi_update_power_query

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

This is highly transparent: it discloses whole-query replacement, dry-run behavior, no backup/journal in dry-run mode, SHA-256 concurrency protection, TMDL write requirements, backup/journal/transaction/rollback, and the exact meaning of response flags like parse_checked and m_engine_checked. This goes far beyond the annotations.

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 dense but every sentence earns its place: core action first, then safety behavior, concurrency control, prerequisites, and response semantics. It is appropriately sized for a complex destructive-looking write operation.

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 covers safety, rollback, response semantics, and prerequisites very well. However, it omits the crucial mapping between kind/name/table and the partition or expression being edited, and request_id is never mentioned. With zero schema parameter descriptions, this is a meaningful completeness gap.

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%, so the description must compensate. It explains dry_run and expected_sha256 well, but m, kind, name, table, and request_id are left undocumented, and the description never explains how to target the partition or expression via parameters. An agent would struggle to construct a correct call for a specific object.

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 opens with 'Reemplaza ENTERA la consulta M de una particion o expresion', which names a specific verb, resource, and scope. It also differentiates itself from partial editing and references pbi_get_power_query, making its role in the sibling family clear.

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 gives clear operating context: it requires a .pbip project and Power BI Desktop closed, dry_run is active on first call, and expected_sha256 from pbi_get_power_query should be used to detect concurrent changes. It does not explicitly list when-not-to-use or name alternative tools for partial edits, but the guidance is strong.

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