combell_mysql_users_list

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds minimal behavioral context beyond the annotations by stating the output includes rights and status, but it does not disclose behavior such as behavior on a non-existent database, pagination, or ordering. No contradiction with annotations.

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?

A single sentence that front-loads the verb and resource, then appends exactly the distinguishing detail (rights and status). Every phrase earns its place, and there is zero redundant wording.

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 low-complexity read-only tool with a single parameter and a full safety profile in annotations, the description is nearly complete. It tells the agent what will be returned (users with rights and status) even though no output schema exists. Only minor details like pagination or empty-result behavior are absent, which is acceptable for a list operation.

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 0%, so the description carries the burden of explaining database_name. It partially compensates: 'users of a MySQL database' conveys that database_name identifies which database's users to list. However, it stops at that level and provides no format, validation, or prerequisite details. The parameter name is self-descriptive, which softens the gap, but the description adds only minimal semantic value.

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 uses a specific verb ('List') with a clear resource ('users of a MySQL database') and specifies the returned content (rights: read_and_write or read_only, plus status). This distinguishes it from user-management siblings like combell_mysql_users_create, combell_mysql_users_set_status, and combell_mysql_users_delete, as well as from combell_mysql_databases_list.

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 usage context is implied by the verb and resource ('List the users of a MySQL database'), so an agent can reasonably infer when to call it versus the user create/update/delete siblings. However, there is no explicit when-to-use language, no exclusions, and no named alternative for cases where rights or status detail is needed differently.

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