p6_list_projects

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds real behavioral context beyond that: the exact response envelope, per-row fields including baseline_of, the rule that EPS nodes are never returned, and the condition under which baselines appear. It could add a bit more on paging termination, but this is well past the annotation 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?

Three tight, front-loaded sentences with no filler, and the response-shape detail is placed first where it is most needed given there is no output schema. Every clause carries 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?

With no output schema, the description usefully documents the return structure and row fields, and with zero required parameters the risk of misuse is low. It is nearly complete for a simple read/list tool; only paging mechanics and sibling routing are left implicit.

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 coverage is 67%; limit and offset are described in the schema, but include_baselines has no schema description. The description compensates by explaining that baselines are only listed when include_baselines=True and that baseline_of is then set, and by tying offset to next_offset. That covers the one undocumented parameter.

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?

States the resource (projects) and the exact page envelope {total, offset, returned, next_offset, rows} plus row fields, so an agent knows precisely what it gets back. Scope exclusions (EPS nodes never listed; baselines only with include_baselines) further sharpen it. It does not explicitly contrast itself with p6_list_wbs or p6_project_summary, so it stops short of a 5.

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?

Usage is implied by the content: a paginated project listing with an opt-in flag for baselines. There is no explicit when-to-use-vs-alternatives statement (e.g. versus p6_list_wbs or p6_project_summary), and no guidance on how to page other than the passing mention of next_offset.

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