comment_pull_request

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

Annotations are present (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lowered. The description does add useful behavioral context beyond annotations by disclosing that the comment body is sent via stdin and that comments are not written to the audit log, which are genuinely non-obvious behaviors. However, it doesn't disclose other behaviors like whether the comment is appended vs replaces, authentication requirements, or rate limiting.

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?

Two sentences, both carrying meaningful information. No wasted words. The behavioral disclosures (stdin, no audit log) are integrated efficiently. Well front-loaded with the core purpose first.

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 mutation tool with no output schema and low parameter coverage, the description is adequate but not rich. It provides purpose plus two useful behavioral notes. It could further clarify return behavior (does it return the created comment?), edge cases, or permission requirements. The complexity is moderate given 5 params and no nested objects, so a 3 is appropriate.

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 only 20%, meaning most parameters (account, hostname, pullRequestNumber, body) lack descriptions in the schema. The description adds some value by noting the body is passed via stdin and is a 'conversation comment,' but it does not clarify the format or constraints of the body parameter (e.g., Markdown support) or explain the distinction between account/hostname. It partially compensates but leaves significant gaps.

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 states a specific action ('Add a top-level conversation comment to a pull request') with a clear verb and resource. However, it does not explicitly distinguish itself from sibling tools like comment_issue, create_pull_request_review_comment, or reply_pull_request_review_comment. The distinction between a top-level comment vs review comments is implied but not named.

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 conveys the primary use case (adding a top-level conversation comment) but does not explicitly state when NOT to use this tool versus alternatives like create_pull_request_review_comment (which targets specific diff lines) or comment_issue. The differentiation is implied through the phrase 'top-level conversation comment' but no sibling tools are named as exclusions.

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