identity_patch_user_roles_on_organization

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

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world behavior; the description adds the deprecation status and the authorization matrix, which are the two facts an agent most needs before invoking a privileged mutation. It does not explain what happens to roles omitted from the request or how failures are reported, but it goes meaningfully beyond the annotations.

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 deprecation warning is correctly front-loaded, but the access-policy table is rendered with escaped HTML entities and the PATCH path is restated even though it already appears in the title and annotations. Usable, but not tightly packaged.

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, authorization-sensitive mutation with a nested request body and no output schema, the description supplies the replacement path, the caller requirements, and the endpoint. Remaining gaps about add/remove merge semantics and response behavior are tolerable given the complete body schema.

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 body's nested serviceRoles/organizationRoles, rolesToAdd/rolesToRemove, and deprecated roleNames fields are already documented. The description only echoes the path parameters via the endpoint template and adds no semantics (e.g. whether removals apply when the role is absent), so 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 user roles in organization') plus the exact endpoint, so the operation is unambiguous. It does not, however, distinguish itself from close siblings like identity_patch_user_service_roles_in_organization or identity_patch_org_roles, which an agent would need to choose between.

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?

Strongly signals that this tool is deprecated and points to a replacement API path, and the access-policy table enumerates exactly which roles (Platform operator, Organization Owner) may call it. The gap is that the recommended alternative is given as a REST URL rather than a sibling tool name, so the agent must infer which tool implements it.

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