Update Password

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

The annotations already indicate destructiveHint=true, and the description states 'Update or set' which implies a change. However, the description does not disclose any side effects, such as whether the change invalidates existing tokens or sessions, or whether the currentPassword is actually required for verification (schema lists it as optional). Since the annotations cover the destructive nature, the description adds only minimal behavioral transparency.

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 a single, concise sentence that conveys the core purpose without any unnecessary verbiage. It is well-structured and easy to parse, making it efficient for an agent to process.

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?

While the tool is simple, important context is missing: there is no mention of output or return value (no output schema), no mention of whether the operation requires authentication, and no indication of potential consequences like session invalidation. The description is adequate for a trivial mutation, but given the security-sensitive nature, more context would be beneficial.

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 schema includes newPassword (required) and currentPassword (optional), but the description provides no explanation of their purpose or constraints. There is no mention that currentPassword might be needed for security verification, nor any clarification of the password strength requirements beyond the minLength/maxLength in the schema. With parameter coverage at 0% in the description, this is a significant gap.

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 action ('Update or set the password') and the target resource ('for the current user'). It is distinct from sibling tools like checkPassword (which likely validates password strength) and setMfa (which manages multi-factor authentication), so an agent can easily identify when this tool is appropriate.

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 does not provide explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., being authenticated) or caveats (e.g., that changing the password may invalidate existing sessions). The agent must infer usage from the tool name and schema, which is insufficient for a security-sensitive operation like password changes.

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