List Issues

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds no behavioral context beyond what annotations declare, such as pagination, result format, or that it returns a list. No additional value.

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 concise (4 words) and front-loaded, but it is too sparse to be useful. It sacrifices informativeness for brevity, and each word doesn't earn its place because it doesn't help the agent understand the tool's functionality.

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 21 parameters, no schema description, and no output schema, the description is woefully incomplete. The agent has no information on how to filter, paginate, or what the response structure is. This is a complex tool with zero contextual completeness.

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 schema description coverage at 0% and 21 parameters, the description provides no parameter meanings. The phrase 'in project' hints at project_id but gives no details on filters, pagination, or required fields. The description fails to compensate for the low coverage.

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 'List issues in project' clearly states the verb (list) and resource (issues). It distinguishes from siblings like gitlab_get_issue (single issue) and gitlab_list_work_items (different entity type), though it doesn't explicitly differentiate from gitlab_my_issues or other list tools.

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?

No guidance on when to use this tool versus alternatives (e.g., gitlab_my_issues for personal issues, gitlab_get_issue for a single issue, or filtering options). The description implies listing in a project but doesn't specify prerequisites or context.

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