add_role

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

With no annotations, the description carries the full behavioral burden. It adds meaningful context by explaining what each modelPermission value permits (Read=query only, ReadRefresh=query+refresh, etc.) and clarifies that row-level filters and members are handled elsewhere. It does not disclose idempotency, required permissions, or return behavior, so not a 5.

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 sentences, front-loaded with the core purpose. Every sentence earns its place: the first states it, the second explains the most important parameter and gives next-step guidance. No verbosity or redundancy.

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 simple 3-param creation tool, the description covers purpose, permission semantics, and the role-creation workflow. It doesn't mention return values or error conditions, but given the tool's simplicity and the explicit next-step pointers, it is adequately complete.

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 only 33% (only modelPermission has a description, and it's a bare list). The description compensates by providing semantic explanations for each permission value. The remaining params (name, sessionId) are self-explanatory or context-dependent, so the tool's key parameter is well-explained.

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 opens with 'Create a security role', a specific verb+resource statement. It clearly distinguishes this from sibling tools like set_rls and add_role_member by positioning it as the first step in role creation, while those tools handle filters and members respectively.

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 provides explicit sequence guidance: after creating the role, use set_rls for row-level filters and add_role_member for members. This implies when to use this tool, though it doesn't mention alternatives like set_role_permission for updating an existing role, which would be useful.

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