preview_pull_request_comment

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

With no annotations provided, the description carries the full behavioral burden, yet it's quite thin. 'Issue a token' is a vague side effect—what token, what is it used for, is it destructive or reversible, does it require special permissions such as write access to comments? None of these are disclosed. The term 'token' may signal some read operation, but the ambiguity about what 'issue a token' does behaviorally is a significant gap.

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 a single concise sentence with no filler. It's appropriately brief, though slightly under-specified. Efficiency is good, but brevity borders on under-informative.

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 4-parameter tool with zero annotation coverage and zero schema description coverage, the description is incomplete. It doesn't explain the token mechanism, return values, prerequisites, or how the preview relates to an actual action. Even with an output schema present, the lack of guidance about token semantics and usage context makes this inadequate for a non-trivial 4-parameter tool.

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%, and the description adds essentially no parameter meaning. It doesn't explain what 'body' should contain, what 'owner' default means, or what 'pull_number' refers to. The description mentions 'the exact body' which loosely maps to the body parameter, but there's no format or semantic guidance beyond schema titles (Repo, Body, Owner, Pull Number).

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 the verb 'Preview' and resource 'PR timeline comment', but the phrase 'and issue a token for the exact body' is somewhat ambiguous—it doesn't clearly distinguish this from the sibling tool 'preview_pull_request'. While it's clear it previews a comment, the distinction from 'preview_pull_request' (which presumably previews the PR itself) is only implicit, not explicit.

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?

No guidance is given on when to use this tool versus its siblings. Among the many preview_* tools (preview_branch_name, preview_local_commit, preview_remote_branch, preview_pull_request), there's no differentiation or exclusion note. The description implies usage ('preview a comment') but provides no when/when-not guidance.

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