contribos_review

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: comments are classified and replies are only *drafted*, not posted. However, it omits auth expectations, whether the operation is read-only, what happens with partial input, and any failure/rate-limit behavior for the API-backed path.

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?

A single front-loaded sentence identifies the tool as a 'Review coach for an open PR' and then lists its outputs after a colon. Every clause earns its place and there is no filler or repetition of structured fields.

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 zero-annotation, no-output-schema tool with three optional inputs and nested objects, the description covers the high-level outputs but leaves the input-mode contract, error handling, and return shape unexplained. It is adequate but leaves the agent to infer how to call it correctly.

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 100%, so the schema already explains data, path, and pr_url, including that the API path 'needs API access'. The description adds only the indirect hint that these are alternative review sources and does not state mutual exclusivity or which combination is required.

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 names a specific verb (review) and resource (an open PR's reviewer comments) and enumerates four concrete capabilities: classify comments, show the pointed-at code, draft replies, and list comments awaiting the author. It is clear what the tool does, but it never differentiates itself from siblings like contribos_check or contribos_tone, which plausibly overlap in the review workflow.

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?

'for an open PR' implies the usage context, and 'waiting on the author' hints at the triage scenario, but there is no explicit when-to-use vs when-not, no routing to a sibling tool, and no statement about which of the three input modes (pr_url, path, saved data) to prefer or whether they combine.

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