get_issue_collection

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that this is a paginated, filterable collection that can embed relations, but says nothing about default page size, empty-result behavior, or any permission requirements. With annotations carrying the safety burden, this is adequate but thin.

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 first two sentences are redundant ('Get all issues. Retrieve all issues from a project.'), spending a sentence on a restatement before any differentiating detail. The remaining two sentences are useful, so the opening waste is the main structural flaw.

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?

The nested schema is rich and the annotations cover the safety profile, so the description need not carry everything. But for a heavily-used list endpoint on a large API it omits sibling disambiguation, pagination defaults, and the correct parameter name for relation embedding, leaving meaningful gaps.

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?

Top-level coverage is reported as 0% (the single required `query` wrapper is undocumented), though the nested properties carry good inline descriptions. The description hints at the filter/sort/pagination knobs and mentions the 'relations parameter', but the schema actually names it `with` — a naming mismatch that could cost an agent a round trip.

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+resource ('Retrieve all issues from a project') and mentions filtering, sorting and pagination. However, it never distinguishes itself from the sibling get_my_issue_collection, which is a near-identical collection tool scoped to the current user, so an agent must infer the difference.

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?

It implies context by describing filters/sorting/pagination and telling the agent to use the relations parameter for related data. It gives no explicit when-to-use guidance, no exclusions, and does not route to alternatives such as get_my_issue_collection or get_issue for a single item.

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