repopilot_publish_review_comment

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

While annotations already provide idempotentHint=true and destructiveHint=false, the description adds meaningful behavioral context beyond that: it is a single managed comment tied to a specific head SHA, it only publishes findings, and it explicitly states it never approves, requests changes, modifies code, or merges. This goes beyond the binary annotation flags and helps the agent anticipate side effects. There is no contradiction with annotations (readOnlyHint=false correctly reflects the write operation).

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 sentences with zero fluff. It front-loads the core action and scope, then provides usage timing and limitations in the same breath. Every sentence earns its place, and the structure is easy to parse.

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 tool with 7 required parameters, a detailed schema, and no output schema, the description covers everything an agent needs to decide when to call it and what to expect. It specifies prerequisites (after reading diffs/checks), operational context (active review run), and behavioral constraints. The description does not need to repeat schema details; it complements them perfectly.

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 coverage is 100%, so all seven parameters have detailed descriptions. The description adds no additional parameter-specific meaning beyond what the schema already provides (e.g., headSha's SHA binding description matching the schema's note about rejection on head change). With full schema coverage, the baseline of 3 is appropriate; the description's value here is behavioral, not parameter-oriented.

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 ('Create or update one managed GitHub review summary comment') with precise scope ('for the exact pull request head SHA bound to an active read-only review run'). It clearly differentiates from siblings by explicitly excluding approvals, change requests, code modification, and merging, and implies a specialized review-comment tool rather than generic GitHub comment/PR tools.

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 gives explicit when-to-use guidance: 'Call after reading all relevant diff pages and checks, while the Reviewer Step is running.' It also provides strong exclusions ('never approves, requests changes, modifies code, or merges') that help an agent route to the correct sibling (e.g., github_merge_pull_request for merges, github_create_pull_request for PR creation). No alternative is named, but the conditions are clear enough.

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