Roles: permissions add

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered; the description then adds genuine behavioral context beyond them: other permissions are retained, already-held actions are skipped (idempotent-like), every user on the role is affected at once, and unmatched actions are reported and skipped. This is meaningful disclosure of side effects and edge-case behavior.

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?

Purpose is front-loaded in the first sentence, followed by focused behavioral detail. Four sentences, all relevant, with no filler; slightly more verbose than strictly necessary but each sentence carries information.

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 mutation tool with no output schema and full schema coverage, the description covers the important gaps: what changes, what is preserved, what is skipped, and the blast radius across users. An agent has enough to call it correctly, though it never addresses authentication/permission requirements.

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 coverage is 100% and the schema already enumerates the allowed actions and the default. The description largely restates this (read/create/update/delete, default read) with only marginal additions like 'on one entity', so it does not materially exceed the structured field documentation.

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 (add) and resource (entity permissions to a role), and clarifies scope (one entity, one or more actions). It does not explicitly name the sibling it contrasts with (roles_permissions_remove / roles_permissions_list), so it stops short of full sibling differentiation, but the purpose is immediately clear.

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?

Usage is implied rather than stated: it describes what adding does but gives no explicit when-to-use/when-not guidance or direction to roles_permissions_remove for the inverse. An agent can infer intent from the name and description, but no conditions or exclusions are spelled out.

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