pbi_add_table_from_source

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

This description goes far beyond the annotations (all false) by disclosing critical behavioral details: the credential workflow (first refresh must be completed by a human in Desktop), the fact that the table exists without data until then, that the server cannot verify the connection, and that TMDL requires a closed project. The transparency is exceptional and directly manages user expectations.

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: a one-line purpose, bullet-like breakdown by source type, a bolded key requirement, and a clear warning about credentials. It is compact for the complexity involved, uses formatting (backticks, bold) to aid scanning, and every section earns its place without fluff.

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?

For a tool with 14 parameters and no schema descriptions, this description is remarkably complete. It covers the main source types, parameter relationships, required fields, the credential caveat, and the TMDL dependency. Since an output schema exists, the lack of return-value explanation is acceptable. Only minor parameters like dry_run and overwrite are left undocumented, but the core behavior is fully covered.

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?

Despite the input schema having 0% description coverage, this description explains the meaning and constraints of many parameters: source values, server/database/schema/source_table/native_query for sql/postgres, odata URL pointing to entity set, web_json URL plus json_path, and the required columns array with its rationale. It does not cover dry_run, overwrite, request_id, or description, but the most operationally significant parameters are well documented.

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, specific statement: 'Crea una tabla apuntando a una BASE DE DATOS o API externa.' It names the action (create table) and the resource (external database or API), and then details supported source types, distinguishing it from sibling tools like pbi_add_table_from_file.

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 provides clear context for when to use the tool: when adding a table from a database or API. It also gives important usage prerequisites, such as 'columns is mandatory' and the TMDL requirement that the project be closed in Desktop. It doesn't explicitly name alternative tools or when not to use it, but the source-specific breakdown effectively communicates the intended use cases.

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