pbi_document_model

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

With no annotations, the description carries the full burden. It discloses that the tool saves a file to outputs/ and includes certain sections, but it does not explain prerequisites (e.g., connected model), side effects (e.g., overwriting files), or the exact return structure beyond the file creation. It doesn't contradict any annotations since none exist.

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 two sentences, front-loaded with the main purpose, and lists the key inclusions and output location. No extraneous content.

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 tool has moderate complexity with multiple output sections and an output schema. The description lists what's included but lacks guidance on model selection, the difference between source options, and how the output integrates with other tools. It is adequate but not fully complete for an autonomous agent.

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 schema provides two parameters with no descriptions, and the description has 0% coverage of schema details. The description only indirectly hints at include_quality through 'advertencias de calidad' but does not explain the source parameter or its possible values. This leaves the agent guessing about parameter semantics.

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 generates complete model documentation in Markdown, specifying the resource (model) and output format. It lists the included sections (summary, tables, columns, measures, relationships, hierarchies, roles, quality warnings), distinguishing it from more focused tools like pbi_model_summary or pbi_analyze_model_quality.

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 implies when to use it: when comprehensive model documentation is needed, including all schema elements and quality warnings. However, it does not explicitly mention alternatives or when not to use it, such as when only a summary or audit is needed, which are provided by sibling tools.

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