pbi_hide_columns

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

With no annotations, the description fully carries the burden of disclosure. It details atomic validation ('si alguna tabla o columna no existe, no se modifica nada'), single-transaction writes (TMDL and SaveChanges), the meaning of count vs results, and the mode='both' behavioral restriction. This goes well beyond a minimal statement.

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 a single paragraph plus one bullet-style line for the parameter, but every sentence carries meaningful information. It is not excessively long, though it could be split into clearer sections. The front-loaded purpose sentence is effective.

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 presence of an output schema and the description's own coverage of count/results, returns are adequately addressed. The description covers validation, transactionality, mode restrictions, and parameter format, making it sufficiently complete for a tool of this complexity.

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?

Input schema coverage is 0%, but the description documents the crucial `columns` parameter format (list of {"table": ..., "column": ...}) and explains the mode='both' restriction. It does not explain `hidden` or `request_id`, but hidden is self-explanatory and request_id likely internal, so the description substantially compensates for the lack of schema descriptions.

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 a clear verb: 'Oculta/muestra VARIAS columnas como un solo lote' (hide/show multiple columns as a single batch), specifying the resource (columns) and the batch operation. This distinguishes it from sibling pbi_set_column_visibility, which presumably operates on a single column.

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 explains the batch nature and gives important constraints: validation before writing, the transactionality, and the temporary disablement of mode='both' with instructions to choose 'live' or 'pbip'. However, it does not explicitly mention alternatives for single-column operations, so it lacks explicit differential guidance.

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