scan_repo

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

With no annotations provided, the description carries the full behavioral burden. It discloses result ordering ('GO first, then CAUTION, then TAKEN'), output structure ('recommendations lists just the GO targets; summary counts each verdict'), and the me-parameter side effect ('your own comments are ignored in the claimant scan'). It does not cover auth or rate limits, but it provides substantive behavioral context.

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 front-loaded with the purpose, then explains ordering and output fields, then gives a compact Args list. Each sentence adds useful information for selecting or invoking the tool, with no filler or tautology.

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?

Given there is no output schema and no annotations, the description does a good job explaining response content, ordering, defaults, and parameter semantics. It stops short of defining what makes an issue GO, CAUTION, or TAKEN, but an agent can still call the tool and interpret the returned verdicts.

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?

The Args block defines all five parameters and compensates for schema gaps by adding descriptions for owner ('repository owner login') and repo ('repository name'). It also adds behavioral nuance for me and makes limit/label meanings explicit, going beyond what the schema already provides.

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 and resource: 'Scan a repository's open issues and recommend the GO ones.' It clearly conveys the tool's main outcome, but it does not explicitly distinguish this tool from sibling tools like discover_candidates or check_issue.

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 phrase 'so the best candidates to volunteer for come first' implies the tool is meant for finding contribution opportunities. However, the description never explicitly states when to prefer scan_repo over discover_candidates or check_issue, nor does it provide exclusion guidance.

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