swsd_list_record_comments

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered elsewhere. The description's only added behavioral detail is the returned field list, which duplicates the output schema and says nothing about ordering, pagination behavior, or private-comment visibility beyond the is_private field name.

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 sentences, front-loaded with purpose, then return fields, then the related write tool. No filler or redundancy in phrasing.

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 full schema coverage, an output schema, and rich annotations, the description covers what an agent needs to select and call this tool. The only gap is the lack of any note on pagination strategy or result ordering, which the schema bounds alone do not convey.

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 100%, so both required parameters and the page/per_page bounds are already documented. The description's mention of 'problem, change, or release' loosely mirrors the record_type enum but adds no format, default, or interaction detail beyond the schema.

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 and resource ('List comments') and pins the scope to three named record types (problem, change, release), which cleanly separates it from the sibling swsd_list_incident_comments and swsd_list_record_tasks.

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 routes the agent to swsd_add_record_comment for the write case, which is useful, but gives no guidance on when to prefer this over the incident-comment sibling or when listing comments is appropriate. Usage is implied rather than stated.

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