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

Annotations cover the safety profile (destructive, idempotent, non-read-only), and the description adds substantially beyond them: the two-phase preview/confirm protocol, token expiry (~minutes) and single-use semantics, replay behavior returning status 'applied' with replayed: true, and stale_revision handling. It also discloses the prompt-injection posture for CRM field values.

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 and the all-important confirmation protocol are front-loaded, and most sentences carry distinct operational information. It is on the long side for a single tool, and the trust-boundary and replay-caveat sentences could be tightened, but nothing is idle filler.

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 destructive, multi-workspace mutation with a nested object parameter and no output schema, the description covers impact, authorization limits, the confirmation workflow, error/replay modes, and untrusted-content handling. Nothing an agent needs to invoke it safely is missing.

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 each parameter is already documented, which sets a baseline of 3. The description adds real meaning on top: a concrete allow/deny example for the access map and the provenance constraint that object keys come from get_permission_catalogue or list_objects, which clarifies how to construct valid keys.

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 with its exact scope: allow or deny one action on one object for every member of a role. The concrete example ({"products.view": false} hides products) and the note that members' own exceptions stay in place distinguish it from the per-member override sibling without the agent needing to open a schema.

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 precise preconditions ('Only actions the role has can be ruled on', 'You cannot change a role you belong to') and a full when-to-use sequence: call first without confirmationToken to preview, get explicit go-ahead in the same turn, then re-call with identical arguments plus the token. It also names the re-preview conditions (changed arguments, expired token, stale_revision).

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