enable_user_totp

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description needs to add context such as admin-only access or lockout risk. Instead it only repeats an HTTP endpoint, which is not behavior an agent can act on, and gives no warning that this changes a user's security configuration.

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?

It is short and front-loaded with the verb, but the brevity comes from omission rather than economy: the REST path is arguably wasted space while operational context is missing.

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 destructive, non-idempotent, open-world mutation with no output schema and undocumented parameters, the agent needs to know permission requirements, whether the user must already have generated a TOTP secret, and the effect (possible lockout). None of that is present.

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 0% for the single user_id parameter. The description only embeds {user_id} in the path template, adding no meaning beyond the schema — no indication of whose ID it is (admin rights required, must be an existing user) or what happens on invalid input.

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 sentence "Enable Totp" restates the tool name almost verbatim, and the only added information is the REST endpoint path. It does not explain what enabling TOTP means for the user (e.g., turning on 2FA enforcement) or how it relates to siblings like disable_user_totp and get_user_totp_qr.

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 when-to-use, prerequisites, or alternatives are given. The existence of a paired disable_user_totp and a get_user_totp_qr tool is not acknowledged, so the agent gets no routing help at all.

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