gitlab_get_user_open_issues

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool retrieves issues 'across all accessible projects' (scope), uses 'intelligent priority sorting' (sorting logic), returns a 'prioritized issue list' with detailed fields (output structure), and supports pagination via per_page and page parameters. It also mentions filtering capabilities and default values. While it doesn't cover rate limits or authentication needs, it provides substantial behavioral context beyond basic functionality.

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 well-structured with clear sections (purpose, usage, returns, use cases, parameters, example) and front-loads the core functionality. However, it includes some redundancy (e.g., listing parameters that are fully documented in the schema) and the 'Use cases' section, while helpful, adds length without critical new information. Most sentences earn their place, but minor trimming could improve efficiency.

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 the tool's moderate complexity (7 parameters, no output schema, no annotations), the description provides strong contextual completeness. It covers purpose, usage, behavioral traits, output structure, use cases, and parameters with an example. The main gap is the lack of an output schema, but the description compensates by detailing the return format ('Returns prioritized issue list with...'). It could be more explicit about error handling or permissions, but overall it's highly informative.

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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema: it clarifies that either user_id or username can be used ('use either user_id or username'), provides an example usage, and lists parameters with brief notes. However, it doesn't explain parameter interactions or add significant semantic context that isn't already in the schema descriptions, meeting the baseline for high schema 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 clearly states the specific action ('List open issues assigned to or created by a specific user') and resource ('issues'), distinguishing it from sibling tools like gitlab_get_issue (single issue) or gitlab_list_issues (general listing). It explicitly mentions the scope ('across all accessible projects') and purpose ('see what issues a user is currently working on or responsible for'), providing excellent differentiation.

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 provides clear context for when to use this tool ('Use this tool to see what issues a user is currently working on or responsible for') and lists specific use cases (personal dashboard, workload management, SLA tracking, sprint planning). However, it doesn't explicitly state when NOT to use it or name alternative tools for similar purposes, such as gitlab_get_user_reported_issues or gitlab_get_user_resolved_issues, which could help avoid confusion.

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