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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description's read-only claim is partly redundant. However, it adds two genuinely useful facts not in the annotations: results are public data only, and each request costs 1 credit. It omits pagination behavior and result-shape details, keeping it below 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?

Three short, front-loaded sentences with no filler; the purpose comes first and the cost note last. The read-only sentence largely restates the annotations, which is minor redundancy rather than bloat.

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?

This is a complex 18-parameter tool with nested date-range objects and no output schema, yet the description never describes what a result contains or how pagination works beyond the schema's cursor field. It covers safety and cost adequately but leaves the agent guessing about return shape for a search-heavy tool.

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%, and each parameter documents its GitHub search qualifier mapping (repo:, state:, author:, etc.), date ranges, and defaults. The description adds nothing beyond the schema for any of the 18 parameters, so the baseline 3 applies.

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 ("Search GitHub issues"), which is enough for an agent to separate it from sibling search tools such as github_search_pull_requests or github_search_code by name. It does not explicitly name those siblings or clarify whether PRs are included, so it falls short of a 5.

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 guidance on when to choose this tool over github_search_pull_requests, github_search_discussions, or github_list_repositories, and no exclusions or prerequisite conditions are stated. The only implied usage cue is the word "issues" combined with the filtering parameters in the schema.

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