list_project_audits

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

Annotations already declare the operation is read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful behavioral context: result cap, newest-first ordering, and summary content. However, it omits pagination behavior, what 'retained' means, and how the stated 'up to 100' relates to the limit parameter (default 30).

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?

A single front-loaded sentence with no filler. It efficiently conveys scope, ordering, and output content, though it could have used a second clause for parameter guidance without becoming bloated.

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?

For a simple list tool with rich annotations, the description adequately covers return characteristics. But with 0% schema description coverage and no output schema, the agent gets no explanation of the required project_id or the limit parameter, leaving a meaningful gap.

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% for both parameters, so the description must carry parameter semantics. It never mentions project_id (required) or limit. The phrase 'up to 100' vaguely hints at a maximum but does not document the limit parameter or explain what project_id identifies.

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 a specific verb (List) and resource (retained snapshots / project audits), plus scope (up to 100), ordering (newest first), and returned content (coverage and issue summaries). It clearly distinguishes this from a detail-fetching tool like get_project_audit, though it does not explicitly name alternatives.

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 says what the tool returns but offers no guidance on when to use it versus alternatives such as get_project_audit, list_audit_projects, or compare_project_audits. No prerequisites or exclusions are mentioned.

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