identity_patch_user_service_roles_in_organization

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, so the safety profile is covered; the description adds real value on top with deprecation status, the authorization matrix, and the constraint that a user belongs to exactly one organization. It does not describe add-vs-remove merge semantics or what happens to roles not listed, which for a PATCH tool is a notable remaining gap.

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 body then mixes a markdown access table, a consumer-facing API URL, and a raw 'PATCH /csp/gateway/...' path that merely repeats the annotation title. For a tool the agent is being told not to call, the text is heavier than it needs to be.

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?

With no output schema and fully covered nested parameters, the description supplies the pieces the schema cannot: deprecation, authorization requirements, and the single-organization constraint. An agent has enough to decide not to call it or to call it correctly if forced, though the absence of add/remove merge semantics leaves one behavioral hole.

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 userId, orgId, body, rolesToAdd, rolesToRemove and the deprecated name-based fields are all documented in the schema. The description adds no syntax, format, or interaction detail (e.g. whether add and remove are applied atomically), so it sits at the baseline for a fully-documented schema.

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 ('Edit the user's service roles') and flags the tool as deprecated up front, so an agent can immediately tell it is a legacy variant of the role-editing family. It does not name the sibling that supersedes it (identity_patch_user_roles_in_organization), so differentiation is by context rather than by explicit routing.

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?

Gives an explicit alternative endpoint ('Use this API instead: /cloudapi/1.0.0/users/{{userUrn}}') plus a full access-policy table stating which roles may call it (Platform operator yes, Org Member no). What it lacks is naming of the concrete sibling tools an agent should switch to, so the guidance is clear but not directly actionable within this toolset.

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