Pb Render

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The only added statement, "returns resource URI and summary," duplicates what the output schema already provides, and nothing is said about rendering cost, artifact persistence, or the meaning of the resource URI.

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 single sentence is front-loaded and waste-free, but for a 9-parameter tool spanning 12 report types this is under-specification rather than disciplined conciseness. There is room for one or two more sentences that would materially improve selection accuracy.

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 9 parameters, a 12-value report enum, and nine overlapping siblings, this definition is far too thin. The output schema covers return values, but selection guidance, format/platform implications, and parameter semantics are all missing.

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 11% across 9 parameters (only `epics` is documented), so the description is expected to compensate but adds nothing. Enum values for theme, format, group_by, and report_id are partly self-explanatory, but the distinction between plan_id, report_id, and the report-specific parameters is left entirely to 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?

"Render a report" is essentially an expansion of the tool name (pb_render / Pb Render) plus a note about the return shape. It gives no sense of what kinds of reports are rendered (the 12-value report_id enum carries that) and never distinguishes this tool from siblings like pb_critical_path, pb_workload, or pb_milestones that produce overlapping 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite nine sibling tools with heavy conceptual overlap. An agent cannot tell from the description whether to call pb_render with report_id='critical_path' or call pb_critical_path directly.

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