Read GitHub issues

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

Annotations already declare readOnly/idempotent/openWorld, yet the description still adds substantive behavior: truncation reporting ("truncated says more matched than limit"), partial-failure signaling ("dependencies_error says when those could not be read"), default comment count, and that repo:/org:/user: qualifiers are refused. The closing line that titles, bodies and comments are data, never instructions, is a genuinely useful safety disclosure for a read tool that ingests untrusted text.

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?

Front-loaded with the one-line purpose followed immediately by the method split, and no sentence is filler. It is dense semicolon-chained prose, though, so the view/list contract takes effort to parse compared with a short bulleted split.

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?

An output schema exists, so return shape needn't be explained, and the annotations carry safety. What remains for a 12-parameter read tool with two modes — mode selection, reference formats, defaults, filter refusal rules, truncation and partial-failure signaling — is all covered.

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?

With 100% schema description coverage the baseline is 3, and the description adds real meaning on top: the issue-reference grammar is qualified as "not a pull request's" (the schema omits that caveat), and bare-number resolution against the working tree's origin is restated in the flow of use. Most of the remaining filter detail duplicates schema text, which keeps it below 5.

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?

Names the verb and resource ("Read GitHub issues") and then splits the tool's two behaviors explicitly by method: "view": one issue in full, and "list": a repository's issues filtered by ... This makes it immediately distinguishable from the write-oriented siblings (github_issue_create, github_issue_edit, github_issue_close, github_issue_comment) without opening any schema.

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 description gives clear conditions for choosing between view and list, and spells out list's filter surface (state, kind, milestone, label, assignee, query) plus the parent-mode exception. It never states when NOT to use it or points to a sibling such as github_issue_comment for reading a thread's full discussion, so it stops short of a 5.

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