Create user

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the basic safety profile is covered. The description adds nothing beyond that – notably no mention that creating users typically requires admin privileges, whether a password is required or generated, or what happens on duplicate email/username.

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 single sentence is short but not concise in the useful sense – it is under-specified rather than economical. There is no front-loaded guidance because there is nothing of substance to front-load.

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 32-parameter, non-idempotent mutation with no output schema and no enum or description coverage, four words of description are wholly inadequate. An agent cannot determine required fields, side effects, or return shape from what is given.

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 32 parameters at 0% schema description coverage, the description carries the full burden of parameter meaning and provides none of it. It doesn't identify which fields (name, username, email, password) are actually needed to create a user, nor explain how list-oriented parameters like page, per_page, sort, order_by, created_after or max_pages relate to a create operation.

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 restates the tool name and title almost verbatim ("Create a new user"), which is a tautology rather than an explanation of scope. It does identify the resource, so an agent can tell it apart from gitlab_create_project, but nothing about what creating a user entails or how it differs from related user 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?

There is no statement of when to use this versus gitlab_update_user, gitlab_get_users, gitlab_delete_user, or the generic gitlab_api_request. No prerequisites, permissions, or exclusions are mentioned, leaving an agent to infer everything from the tool name alone.

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