list_issues

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the 'does not mutate GitLab data' sentence aligns and adds value beyond the annotation. Additionally, it discloses the error behavior for missing resources, invalid identifiers, insufficient permission, and rate limits, which is valuable context not present in annotations. It also notes that when project_id or group_id is accepted, the caller must provide numeric ID or URL-encoded path as per schema. This goes beyond annotations. No contradiction: the description says read-only, and annotation says readOnlyHint=true. This is consistent and transparent.

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 description is a single paragraph of moderate length but packs essential information: primary purpose, default scope, usage guidance, read-only nature, error behavior, and parameter clarification. It front-loads the most important info (default scope, collection vs single) and then covers safety and parameter details. It could be broken into two sentences for readability, but it is not overly verbose. Every sentence adds value. Slightly long but acceptable for 21 parameters.

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?

Given that the tool has 21 parameters with 100% schema coverage, the description doesn't need to explain each parameter, and the schema already does that. The description covers the critical usage distinctions (collection vs single, scope default, error behavior, identifier format) that are not in the schema. It doesn't describe return format or pagination specifics, but with no output schema, the description could have mentioned typical response structure, but the error behavior and scope guidance cover the main operational needs. Missing explicit rate-limit handling beyond 'returned as errors', but that is a minor gap. Overall, well-covered for a complex list 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?

Since schema coverage is 100%, the baseline is 3, and the description adds value by explaining the default scope and the use of required identifiers and pagination fields. It also explains the context for project_id and group_id acceptance, which clarifies the semantics beyond the schema descriptions. The description highlights the mutual exclusivity of author_id/author_username and assignee_id/assignee_username, which is already in the schema but reinforces it. It also mentions the pagination fields 'as documented', which adds a hint. This goes beyond the bare schema, so a 4 is appropriate.

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 ('List') and a resource ('issues'), and immediately clarifies the default scope (created by current user) and the key scope distinction ('all'). It also differentiates itself from the corresponding get tool, and given siblings like list_merge_requests, get_issue, my_issues, this is a clear collection-style listing tool for issues. The name 'list_issues' is directly explained and the main variation (scope) is called out.

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 explicitly says to use this for collections and to choose the corresponding get tool when a single resource is already known, which directly guides the selection between this and get_issue. It also explains that missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors, which sets expectation for error handling. However, it doesn't explicitly enumerate all alternative tools or conditions—like when to use my_issues versus this—but the scope parameter and the mention of project_id/group_id covering cross-project listing provide adequate context. No explicit 'when not to use' beyond the single-resource example, but the guidance is strong.

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