review_queue

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuine context beyond that: the grouping behavior (5 action classes), the two output forms, and a full enumeration of the returned dict keys, which matters since there is no output schema.

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?

Well front-loaded and cleanly sectioned into Args/Returns, with the core purpose stated first. The version tag '(v1.5.0)' is minor noise, but overall it is tight and earns its length.

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 moderately complex digest-builder with no output schema, the description supplies the return keys, the input field list, and the two output destinations. Missing only the specific 5 action classes and the precedence between prs and prs_file, which are minor gaps.

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%, so the description must carry the load and it largely does: it documents prs as a list of {repo, number, title, body, author, labels, star_count, repo_merge_rate} and prs_file as an alternative path to a JSON PR list. It does not specify the JSON file's expected shape or how the two inputs interact if both are supplied, but it compensates well for the empty schema.

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 opens with a specific verb+resource ('Build maintainer review queue digest from a list of PRs') and clarifies the mechanism (groups by maintainer action into 5 classes, emits markdown). It is clearly distinguishable from the per-PR sibling maintainer_view, but it never explicitly names or contrasts any sibling.

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?

Usage is only implied through the stated output targets ('suitable for Actions summary or git-trackable markdown file'). There is no explicit when-to-use vs. maintainer_view/analyze_pr/triage_pr guidance, no prerequisites, and no exclusions.

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