pbi_reflow_pages

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

Beyond the annotations, the description discloses key behaviors: it rescales proportionally, bounds out-of-fit visuals, recalculates text colors, does NOT recompose, supports a dry-run mode that writes nothing, and writes to the report (PBIR). It explains the reasoning behind the 'no recompose' limitation. The annotations (readOnlyHint=false, destructiveHint=false) are consistent with the description; no contradiction.

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 well-structured and front-loaded with the main action. It uses three clear paragraphs: core functionality, limitation/alternative, and parameter notes. Every sentence contributes value, and the length is appropriate for the complexity described.

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 complexity (write operation with dry-run, out-of-bounds handling, color recalculation) and the presence of an output schema, the description is quite complete. It covers the why, what, limitations, parameter behavior, and operational requirement (project closed). The only minor omission is explicit documentation of `system`, but the context makes it inferable.

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 does explain `pages` (optional subset, default all) and `dry_run` (default true, returns plan without writing), which is helpful. However, the required `system` parameter is only indirectly referenced (as the destination system) but never explicitly tied to the parameter, and `request_id` is not mentioned at all. This partial coverage leaves meaning gaps.

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's function: 'Reescala las paginas ya escritas al lienzo de otro sistema.' It explains it rescales visuals and recalculates text colors, and explicitly contrasts with pbi_compose_page ('No recompone'), distinguishing it from siblings. The verb is specific and the scope is 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 sets the context ('El camino de vuelta que faltaba'), explains when this tool is needed (after applying a system to composed pages), and provides an explicit alternative: 'Si una pagina necesita otra estructura, recomponla con pbi_compose_page.' It also mentions the prerequisite of having the project closed in Desktop, which is important usage guidance.

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