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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds nothing beyond the user fields, but with annotations covering the safety profile and the schema documenting the structure, the description doesn't contradict and doesn't need to repeat. It adds marginal value by naming common fields, but doesn't mention permissions, duplicate-login behavior, or password policy.

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?

Two tight sentences, front-loaded with the action and required field. Zero waste.

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 tool is a create mutation with openWorld and no idempotency. The description names common fields but omits duplicate-user behavior, required permissions, and validation semantics. With annotations covering safety and an output schema present, the description is adequate but leaves behavioral gaps for an agent creating a real user.

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 coverage is 100% with the nested input object described as 'User fields'. The description adds field names (name, realname, firstname, password, email via _useremails) which is useful context beyond the opaque schema, but the schema itself is flexible (additionalProperties: {}) so the description is doing important work naming the key fields. However, it doesn't explain the _useremails array structure or required constraints beyond 'name (login)'.

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 (Create) and resource (GLPI user), clearly distinguishing it from glpi_update_user and glpi_get_user siblings. Lacks explicit differentiation phrasing but the operation is unambiguous.

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 vs glpi_update_user or glpi_search_user_by_email, no prerequisites, no mention of what happens if the login already exists. The agent is left to infer usage context entirely.

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