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

Annotations indicate this is a write operation (readOnlyHint: false) with no special safety flags. The description adds one useful behavioral limitation: 'File attachments are not supported via MCP.' However, it does not disclose whether both file_id and item_id can be provided, whether comments are appended or replaced, or any authentication requirements, so behavioral disclosure is minimal.

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 description is two short sentences totaling 27 words. The first sentence is front-loaded with the action and target, and the second sentence provides a key limitation. No waste.

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?

The tool has 4 parameters, no output schema, and minimal annotations, so the description must carry the burden. It covers the basic purpose and one limitation but does not explain parameter relationships, required fields, or return values. For a tool with this complexity, the description leaves significant ambiguities that could lead to incorrect invocations.

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?

With schema description coverage at 0%, the description must clarify the parameters. It partially does so: 'general or feedback' suggests values for 'type', and 'queue item or user file' identifies the targets for 'item_id' and 'file_id'. However, it does not explicitly map parameters to these concepts, nor does it explain the 'comment' field or whether targets are mutually exclusive, leaving ambiguity for a 4-parameter tool.

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 clearly states the tool's function: 'Add a comment (general or feedback) to a queue item or user file.' The verb 'Add' and the target resources distinguish it from sibling tools like update_queue_comment, delete_queue_comment, and list_queue_comments. The mention of 'general or feedback' also indicates comment types, adding specificity.

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 implies usage for adding comments but provides no explicit guidance on when to use this tool versus updating or deleting comments, nor does it name alternatives. The lack of exclusions or prerequisites is a clear gap, though the context of 'queue item or user file' gives some situational context.

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