list_issue_events

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context that 'event metadata is untrusted repository data,' which informs an agent to be cautious when interpreting values. However, it doesn't cover pagination guarantees, maximum results beyond page/perPage bounds (already in schema), or what the event payload structure looks like.

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?

Two sentences, both information-dense with zero filler. The first sentence conveys purpose and scoping; the second conveys data trustworthiness and sibling redirect. Excellent front-loading.

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 read-only paginated list tool with readOnlyHint and destructiveHint annotations, the description covers core behavior. However, with 6 parameters and only 17% schema coverage, it should clarify what optional params (hostname, perPage bounds) mean or how paging behaves, especially given the large page maximum of 10000. No output schema means return-value expectations are undocumented.

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 very low at 17% (only 'repository' has a description). The description adds essentially no parameter-level detail beyond what the schema provides, not even mentioning the bounded page/perPage relationship. For a 6-parameter tool at 17% coverage, the description must compensate more and does not.

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?

Clear verb+resource: 'Read one bounded page of issue state-change events from an allowed repository.' It distinguishes from sibling list_issue_comments by explicitly noting comments are returned by that tool instead. The scope (bounded page, allowed repository) is specific.

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 clarifies this tool returns events (state-change), not comments, and points to list_issue_comments as the alternative for comments. It doesn't explicitly state when-not-to-use or enumerate all alternatives, but gives clear context for the main sibling differentiation.

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