pbi_audit_project

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

With no annotations, the description must disclose behavior itself. It reveals that requesting `formats` writes markdown/html reports into `outputs/` and returns their paths, and it enumerates the analysis payload. It does not state whether the audit is strictly read-only or which project scope is required.

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?

Three short, dense lines front-loaded with the main purpose; no filler. Every sentence adds useful information.

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 an output schema and many siblings, the description covers purpose, scoping parameters, and the file-writing side effect. It would benefit from stating prerequisites such as an open PBIP project or selected model, but it is otherwise reasonably complete.

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 provides no descriptions (0% coverage), so the description's mention of `formats`, `rules`, and `min_severity` adds necessary meaning. It tells the agent that formats triggers file output and that rules/min_severity constrain the audit, though it omits possible values for `min_severity` and exact rule identifiers.

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 identifies a comprehensive audit covering 'modelo semantico + informe + layout' and lists concrete deliverables (global/per-domain scores, executive summary, prioritized findings, autofixable rules). This clearly differentiates it from sibling tools like pbi_audit_model or pbi_audit_report_only.

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?

It implies usage when a whole-project audit is needed, and mentions that `rules` and `min_severity` can scope the audit. However, it does not explicitly state when to prefer it over alternatives or provide when-not-to-use guidance.

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