pbi_apply_design_system

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

Annotations already indicate a write operation (readOnlyHint=false), and the description reinforces this by stating 'Escribe el tema' (writes the theme) and 'Escribe en el informe (PBIR)' (writes to the PBIR report). It goes beyond annotations by specifying the exact side effects: modifying report.json, returning canvas/grid/typographic scale, and the recommendation to close the project. This gives the agent useful behavioral context about what changes and what to expect.

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 in three short paragraphs: the first gives the main action and output, the second details the write and return values, the third offers a practical warning. Every sentence adds value, there is no redundant or filler content, and the key information is front-loaded. It is concise without sacrificing necessary detail.

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 presence of an output schema means the description doesn't need to detail return types, but it still mentions the return values (canvas, grid, typographic scale) as added context. It covers the side effect (writing report.json) and a critical prerequisite (closing the project in Power BI Desktop). It does not mention error scenarios, prerequisites beyond the closed project, or how to obtain a valid system value, but given the tool complexity and schema richness, the description is reasonably 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?

The input schema has only two parameters (system, request_id) with zero descriptions, so the description must compensate. The name and description together make it clear that 'system' refers to the design system to apply, but the description does not define the expected format, where to obtain valid values, or any default behavior. It indirectly points to the existence of design systems (sibling pbi_list_design_systems), but this is not explicit. The semantics are inferable but not fully specified, meriting a mid-range score.

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 action: 'Aplica el sistema al informe' (applies the system to the report) and immediately mentions the output: 'devuelve su rejilla' (returns its grid). It also mentions writing the theme and declaring it in report.json, and it distinguishes itself from the similar sibling pbi_compose_page by noting that manually placed items should use the same guides. This is a specific verb+resource+output, fully differentiated from siblings.

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 practical context: it should be used before manually placing items, as it ensures consistency with pbi_compose_page. It also provides a concrete operational guideline: 'conviene tener el proyecto CERRADO en Power BI Desktop' (it is advisable to have the project closed in Power BI Desktop). While it doesn't explicitly say 'do not use when...', the reference to pbi_compose_page and the manual placement workflow imply the intended moment of use, making the guidance clear but not exhaustive.

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