infomaniak_list_database_users

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the operation's safety is known. The description adds value by disclosing the data structure: each user has its own password, a permissions array for databases, and WordPress users are marked protected: true. This goes beyond the annotations and helps the agent set expectations about the response.

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 exactly two sentences, front-loaded with the core purpose, and includes necessary nuance about passwords, permissions, and WordPress protection. Every sentence earns its place with no redundancy or filler.

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 simple (one parameter), has rich annotations (read-only, open-world, idempotent), and an output schema exists. The description explains what the list contains and the special WordPress case, which is sufficient for an agent to invoke the tool correctly. No critical details are missing.

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?

The only parameter is hosting_id, which the schema defines as an integer. The description references 'web hosting' in the first sentence, making it inferable that hosting_id refers to that web hosting. However, there is no explicit mapping or guidance on how to obtain a valid hosting_id (e.g., from list_hostings). Given 0% schema description coverage, the description partially compensates but could be more explicit.

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 tool's function: 'List the MariaDB-level user accounts attached to a web hosting.' The verb 'List' is specific, the resource is well-defined (MariaDB-level user accounts, distinct from hosting users), and it differentiates itself from sibling tools like infomaniak_list_hosting_users by explicitly noting 'MariaDB-level' and mentioning the permissions array and protected flag.

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 on when to use this tool: when you need database-level user accounts for a web hosting, each with its own password and permissions. It does not explicitly name alternatives, but the scope (MariaDB-level vs hosting-level) implicitly guides the agent away from or toward sibling tools. It also adds a WordPress-specific nuance that aids usage decisions.

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