Create a user

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

With only idempotentHint:false in annotations, the description carries useful behavioral weight: it explains the invitation-vs-password path and that an account in no group can log in but see nothing. This goes beyond the schema. It does not mention permissions, duplicate handling, or what the response contains, but the annotation already signals non-idempotency.

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?

Three sentences, no filler. The core action is front-loaded, followed by the two most consequential decisions (password vs invitation and group assignment behavior). Every sentence earns its place.

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 tool with 8 parameters, no output schema, and minimal annotations, the description covers the key operational decisions and a notable behavioral consequence (blank visibility without groups). It omits a few details like must_change_password and confirmation-token usage, but the schema already documents several of those, so the overall context is sufficient for correct invocation.

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 75%, so the schema already documents most parameters. The description adds valuable semantics for groups (IDs come from list_groups) and send_welcome_email (it replaces password for local accounts). However, it does not explain must_change_password or the exact confirmation-token flow, though the schema partially covers that.

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 opens with a specific verb and resource: "Creates an account." It additionally clarifies the local-versus-invitation creation paths and the role of group IDs, so an agent can clearly distinguish this creation operation from the many user-management siblings like update_user, delete_user, and list_users.

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 gives clear context for when to use it and how to make key choices: supply a password for a local account, or set send_welcome_email for an invitation. It also points to list_groups for group IDs, which is helpful routing guidance. It does not explicitly name alternatives or state when not to use create_user, so it falls short of a 5.

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