reset_password

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

With no annotations, the description provides the key caller-relevant behavior: it is a privileged operation with two distinct flows, self-service with current password vs. admin API flow. It stops short of disclosing side effects such as session invalidation or password-policy enforcement, but it does not contradict any annotation and adds meaningful authentication context.

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 short sentences with no filler: the action is front-loaded and the only necessary invocation nuance follows immediately. Every word 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 three-parameter mutation with no output schema, the description plus schema gives an agent enough to invoke it correctly: target user, new password, and the current-password/admin condition are all covered. It could add side-effect or failure-mode context, but nothing essential to a first correct call is 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?

Schema coverage is 100%, so the schema already documents uid, new_password, and current_password. The description reiterates the conditional current_password rule and adds the admin API flow context, but it does not materially expand on what the parameters mean beyond the structured definitions, so the baseline score of 3 is appropriate.

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 an unambiguous verb and resource, 'Reset a FreeIPA user's password,' which clearly distinguishes this from sibling account-management tools like enable_user, disable_user, and delete_user. There is no ambiguity about what operation is exposed.

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?

It gives a concrete invocation condition: a current password is required unless the call is made by an admin with sufficient privileges via the admin API flow. This helps an agent decide whether to supply current_password, although it does not explicitly discuss alternatives or when-not-to-use cases beyond that condition.

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