Get role members

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

The readOnlyHint=true annotation already tells the agent this is a safe read with no mutation, so the description is only obliged to add context beyond that — permissions needed, whether nested role inheritance applies, pagination behavior. It adds none of that. For a lookup whose correctness depends on whether inherited/nested roles are included, the description provides nothing beyond the annotation.

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?

A single short sentence with zero filler and the key constraint (current membership) front-loaded, so nothing needs trimming. It is arguably over-compressed rather than verbose — brevity is achieved by omitting verb and scope qualifiers the agent would want. Efficient, but economy at the cost of 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 simple 3-parameter read with 100% schema coverage and readOnlyHint supplied, the definition covers the central question of what data returns. What is missing is modest: whether nested/inherited role members are included, how the default guild is resolved, and pagination guidance for the limit cap. None of these are schema-explained, but their absence is a small gap for a tool of this complexity.

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 role, guild, and limit are already documented in the schema (including the maximum of 100 and default of 50), which sets the baseline at 3. The description adds only the "currently hold" temporal qualifier and supplies no syntax detail for role or guild name-vs-ID resolution beyond what the schema states. It neither compensates for nor erodes the schema's coverage.

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 identifies a specific resource (role members) and a filtering constraint ("currently hold"), which is more informative than the bare title. However, it is an incomplete sentence fragment with no verb (e.g., "returns"/"lists"), and it does not distinguish the tool from the sibling list_members or search_members, which could plausibly return overlapping data. An agent knows roughly what data comes back but not how this read differs from its siblings.

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?

There is no when-to-use guidance at all: no statement of when to pick this over list_members, list_thread_members, or search_members, and no mention that it is role-centric (an admin/audit use case) versus a plain member listing. The only implicit signal is the required role parameter in the schema. Exclusions and alternatives are entirely absent.

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