pbi_validate_page_spec

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

With no annotations, the description carries the safety burden and explicitly states 'No escribe nada' (does not write), disclosing the read-only nature. It also adds behavioral context that errors include JSON paths for easy correction. While it does not cover all possible side effects or prerequisites, the provided transparency exceeds the typical baseline.

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 compact and front-loaded: purpose first, then error-path behavior, then a critical safety note. Every sentence adds distinct value without repetition or filler.

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?

An output schema exists, so return values are covered elsewhere. The description includes the essential non-writing guarantee and error reporting, but misses usage context (when to call before/after other tools) and does not mention dependencies like an active model or project. Overall adequate but with notable gaps for a validation tool.

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?

Schema description coverage is 0%, so the description must compensate. It clarifies what the spec parameter is validated against (schema, model references, geometry), giving semantic meaning beyond the bare 'spec' object in the schema. However, it does not explain the expected structure or format of the spec object, leaving room for ambiguity.

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?

Description clearly states the specific verb 'Valida' and the resource 'spec', adding concrete details: schema validation, references against the model, and geometry. This differentiates it from siblings like pbi_validate_pbip_project or pbi_validate_tmdl, which target different artifacts.

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?

No guidance on when to use this tool versus alternatives like pbi_preview_page_spec or pbi_apply_page_spec. The 'No escribe nada' note hints at safe validation but does not explain the intended workflow or prerequisites. Usage context is only implied by the tool's name and validation scope.

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