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

With no annotations, the description carries the whole burden and does so well: it enumerates the decision thresholds, the stale-claim decay defaults, the two extra payload markers, and a full error-to-code mapping (rate_limited, not_found, auth_failed, timeout, unknown). It never explicitly states the operation is read-only/no-side-effect or names auth requirements beyond the `gh auth token` hint, which keeps it from a 5.

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?

Purpose is front-loaded in one line, followed by logically grouped verdict, payload, error, and args sections; the error-code mapping is dense and useful rather than padding. Length is justified by the tool's complexity, though the arg list partially restates schema entries.

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 9-parameter tool with no output schema and no annotations, the description is notably complete: it describes the return verdict semantics, auxiliary payload fields, and error payload structure alongside every parameter. Missing pieces are rate-limit behavior and an explicit statement of read-only safety, which are minor gaps at this complexity.

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 only 56%, so the description must compensate, and it largely does: it lists all nine args and adds genuine meaning for `me` ('your own comments are ignored') and for the three decay thresholds, which are otherwise opaque. The owner/repo/issue_number entries are trivial restatements, but the non-obvious parameters are explained.

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?

States a specific verb and resource ('Check whether a GitHub issue is already taken') plus a three-value verdict taxonomy (GO/TAKEN/CAUTION) that pins down exactly what the tool answers. The remark that it returns the same markers as `scan_repo` implicitly frames it as the per-issue counterpart to the repo-level sibling, so an agent can separate them.

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: a GO verdict maps naturally to 'free to volunteer', which hints at the pre-contribution workflow, but the description never states when to call this versus `scan_repo` or `discover_candidates`, nor any prerequisites or exclusions. The sibling names appear only as a reference for shared output markers, not as routing alternatives.

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

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

With no annotations, the description carries the full burden and does substantial work: it enumerates error codes (rate_limited, not_found, auth_failed, timeout, unknown) with the underlying failure types, and explains the stale-claim decay semantics. It stops short of stating that this is a read-only operation with no side effects on GitHub, which would round out the safety profile.

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 purpose is front-loaded and the error-code mapping is usefully compact, but the Args section duplicates parameter documentation that already exists verbatim in the schema at 100% coverage, adding length without new information.

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?

There is no output schema, so the description must explain return values, and it does: results carry friendly_labels and welcoming, and error payloads carry error plus error_code. It leaves the ranking methodology and the meaning of the TAKEN/CAUTION verdicts somewhat implicit, but the essential call-and-response contract is present.

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 documents all eight parameters including defaults, and the baseline is 3. The Args block largely restates the schema, adding only marginal value (e.g. clarifying that the user's own comments are ignored in the claimant scan), so it does not exceed the schema's contribution.

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 verb and resource ('Discover top open-source contribution candidates') and details the mechanism (GitHub search plus taken's full verification, returning ranked candidates). It is clear on what the tool does, but never distinguishes itself from its siblings check_issue and scan_repo, leaving the agent to infer which tool to reach for.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the sibling tools check_issue or scan_repo as alternatives. The description explains what happens internally but gives the agent no criteria for selecting this tool over the others.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it documents result ordering (GO/CAUTION/TAKEN), the meaning of `recommendations` and `summary`, the semantics of `friendly_labels` and `welcoming`, and a full error-code mapping (rate_limited, not_found, auth_failed, timeout, unknown). The auth_failed mapping implicitly signals authentication requirements, though permissions and rate-limit behavior themselves are not spelled out.

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 core purpose is front-loaded, and the results and error sections are high-value content. The trailing Args block duplicates the schema descriptions with only slight added nuance, which is the one bit of low-yield text, but the description is otherwise tight and well-ordered.

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?

There is no output schema, so the description must describe the return shape — and it does, covering ordering, `recommendations`, `summary`, `friendly_labels`, `welcoming`, and the error payload contract. For an 8-parameter, no-annotation tool it is close to complete; only explicit auth/permission prerequisites are missing.

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 75% and the description documents all eight arguments, adding meaning beyond the schema in places (e.g. `me` scopes the claimant scan, `pr_idle_days` and the two silence thresholds are framed as stale-claim decay knobs). The Args block largely restates the schema, so the added value is modest but real.

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 first sentence states a specific verb and resource ('Scan a repository's open issues') plus the outcome ('recommend the GO ones'), so the agent knows exactly what the tool produces. It does not, however, contrast itself with the siblings check_issue and discover_candidates, so routing between them is left to inference.

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 implied by 'the best candidates to volunteer for come first' and 'prefer the safest issues to adopt', which signals the contribute-to-a-repo scenario. But there is no explicit when-to-use statement, no when-not-to-use, and no mention of the sibling tools, so an agent must guess how this differs from check_issue or discover_candidates.

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