Comment on Merge Request

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

No annotations are provided, so the description carries the full burden. It adds useful details like Markdown support and the return confirmation message, and it implies a non-destructive post operation. However, it lacks explicit information about permissions, side effects (e.g., notifications), or any limitations, which would be valuable for a write operation without annotation support.

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 concise and well-structured: a clear opening sentence, a compact Arg list with examples, and a Returns line. Every sentence earns its place with no redundancy or fluff.

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 the tool's simplicity (3 required parameters, no nested objects, and an output schema), the description is complete. It covers all parameters, explains the return value, and the purpose is clear. The presence of sibling tools does not require additional context because the scope is well-defined.

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?

The schema has 0% description coverage, and the description compensates well by adding examples (project: 'ij'), clarifying that review_id can be an MR number or internal ID, and noting Markdown support for text. This adds meaning beyond the bare schema. It does not explain optionality or validation, but all parameters are required and the descriptions are adequate.

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 'Post a general comment on a merge request,' which is a specific verb and resource. The 'general' qualifier distinguishes it from sibling tools like post_code_discussion and post_reply_to_code_discussion, making the purpose unambiguous.

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 provides clear context that this tool is for posting general comments, which implies when to use it. It does not explicitly name alternatives or exclusions, but the context is sufficient for a straightforward operation. The sibling tools further clarify the distinction, though the description itself could have been more explicit.

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