Set a user's access (groups and/or permissions)

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

Even with annotations indicating destructive and idempotent behavior, the description adds critical specifics: FULL REPLACE semantics, omitted lists untouched, the exact environment variable, the confirm flag requirement, dry_run capability, and safety guard against self-lockout. It goes far beyond what annotations provide, explaining exactly what happens to each portion of the access definition.

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?

Two efficient sentences carry all the essential information: the action, the semantics, and the safety requirements. It is front-loaded with the most critical behavior (FULL REPLACE) and uses the second sentence for critical constraints. The only minor issue is the typo 'PORTALLOW' instead of 'PORTAL_ALLOW', which could cause confusion but does not detract from overall clarity.

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, write-operation tool with 6 parameters and no output schema, the description covers all the key behaviors an agent needs: replacement semantics, requirements, dry run, and self-lockout protection. It doesn't explain return values, but that is absent from annotations yet likely not essential given the operation-focused nature. The safety and idempotency aspects are sufficiently addressed. The description is both complete and safe.

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?

The input schema already has 100% parameter description coverage with each parameter clearly documented (e.g., 'Complete list of group ids... full replace'). The description adds value by synopsizing the relationship between groups and permissions and clarifying the interaction with confirm and dry_run. It slightly exceeds the baseline by clarifying the high-level contract, though the schema already does most of the heavy lifting.

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?

The description clearly states the tool replaces a user's group membership and/or permission set, using the strong verb 'Replace' and the resource (user's access). It distinguishes itself from read-only siblings like get_user_access by explicitly framing it as a mutation. The core behavior of full replacement is front and center, making the tool's purpose immediately obvious.

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 description gives strong usage context: requiring admin writes (PORTALLOW_ADMIN_WRITES=1) and confirm:true, plus explaining dry_run for safe preview and self-lockout protection. It clearly implies when to use this tool (to change access) versus alternatives through its explicit scope. However, it does not explicitly name a sibling tool for comparison or state when NOT to use it, so it misses the highest tier.

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