auth_update_profile

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It correctly indicates the mutating nature of the operation and flags the conditional requirement that currentPassword must accompany password changes. However, it doesn't disclose consequences like whether all fields are updated atomically, whether omitted fields are left unchanged or reset, or whether the quiet-hours default (true per schema) applies when the field is not provided when updating other fields.

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, efficient sentence that front-loads the core action and follows with the enumerable fields in parentheses. It's compact with no wasted words. It could be slightly more structured (perhaps splitting the password caveat into its own sentence), but overall it earns its space without bloat.

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 an 8-parameter mutation tool with 100% schema coverage and no output schema, the description covers the primary intent and the critical password coupling. However, it doesn't explain partial-update semantics (e.g., whether passing one field leaves others untouched), which matters for a multi-field update tool, nor does it clarify the exact meaning of 'preferences' beyond what the schema offers. Given the tool's complexity, a bit more context on update semantics would help.

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 100%, so the schema already documents all 8 parameters well. The description adds meaningful value beyond the schema by summarizing which fields are updatable and explicitly highlighting the password/currentPassword coupling. It also adds the quiet-hours timing clarification (22:00-08:00) that is in the schema as well. The description doesn't duplicate every parameter but adds the aggregate purpose, which 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 states a clear action ('Update the authenticated user's profile') with a specific resource (the authenticated user's profile) and enumerates the updatable fields (name, phone, timezone, quiet-hours preference, preferences, or password). It doesn't explicitly differentiate from sibling auth tools like auth_me or auth_update_password, but the verb+resource combination distinguishes it well from the general tool landscape.

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 implies the tool is for updating the current user's own profile, distinct from admin/user management tools. It notes a password-specific requirement (requires currentPassword when changing password), which is a useful conditional guideline. However, it doesn't explicitly state when NOT to use this tool (e.g., for other users' profiles, or when to prefer auth_forgot_password/auth_reset_password for password changes), leaving some ambiguity.

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