identity_update_user_profile

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the description need not restate safety. It adds real value beyond them: deprecation status and an explicit access-policy table showing all roles (Platform operator, Org Owner, Org Member, whitelisted Service Account) may call it. It does not explain PATCH partial-update semantics or what happens to fields omitted from the body.

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?

Front-loads the deprecation warning, which is the single most decision-relevant fact, then the endpoint and access matrix. Short and well ordered, with no redundant prose beyond the boilerplate access table.

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 deprecated single-nested-body mutation tool with no output schema, the description covers deprecation and authorization. What is missing is disambiguation for the agent: the replacement is not named as a sibling tool, and partial-update behavior for a non-idempotent PATCH is unexplained.

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%: locale, language, metadata, defaultOrgId and preferredTheme are each documented in the nested body schema, so the schema carries the burden. The description contributes nothing about these fields, so the baseline 3 applies.

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?

States a specific verb and resource: update the logged-in user's profile attributes via the logged-in-user profile endpoint. The DEPRECATED marker further distinguishes it from active siblings such as identity_update_user_preferences or provider_update_user. It loses a point because the recommended replacement is given as a raw HTTP path rather than a sibling tool name, leaving the routing ambiguous.

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 deprecation notice plus 'use this API instead' gives a clear signal to prefer the alternative, which is meaningful guidance. However, the alternative is an endpoint path an agent cannot map directly to a callable tool, and there is no statement of the narrow case (if any) where this tool is still needed, such as updating locale/theme/metadata together.

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