pbi_start_here

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

Annotations already declare readOnlyHint=true, but the description adds meaningful context: 'No escribe nada' confirms read-only behavior, and it explains the decision logic (checks whether Power BI Desktop has the project open, which impedes writing TMDL). It also mentions returning `common_tasks` as an additional output. This goes beyond the annotation and gives the agent a clear behavioral model, though it doesn't cover error cases or detailed state inspection semantics.

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 'Por donde empezar.' It uses a brief metaphor about 127 tools to justify the tool's existence, then explains the output and conditions. Every sentence contributes to purpose, usage, or behavior. It is slightly longer than necessary, but for an entry-point tool that must explain a complex decision process, the length is reasonable.

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 tool's simplicity (no required parameters, read-only, output schema present), the description is largely complete. It explains what the tool does, when to use it, and the logic it applies. The only gap is the undocumented request_id parameter, which is minor since it's optional. The output schema covers return values, so the description needn't explain them in detail.

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 one optional parameter, request_id, with 0% schema description coverage. The description does not mention or explain this parameter at all. With such low coverage, the description should compensate, but it fails to add any meaning to the parameter. The parameter's name ('request_id') and default hint at a correlation ID, but the description leaves this entirely to the agent's inference.

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: 'Mira el estado real y dice los siguientes pasos' (looks at the real state and says next steps). It explicitly distinguishes itself from the 127 sibling tools by positioning itself as the answer to '¿y ahora que?' and directs users to 'Empieza por aqui cuando no sepas que sigue.' This is a specific verb+resource with clear differentiation.

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 explicitly tells when to use the tool: 'Empieza por aqui cuando no sepas que sigue' (Start here when you don't know what's next). It also gives context on what conditions it checks (active project, model vs report, Desktop open) to decide next steps. However, it doesn't name specific alternative tools or explicitly state when not to use it, though the 'start here' framing implies it.

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