list_members

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description's one contribution is the required OAuth scope, which is genuinely additive and not expressible in the schema. However it says nothing about pagination, ordering, or what a member entry contains, so it does not rise above adequate.

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, zero waste, with the resource statement front-loaded and the auth requirement following. Every sentence earns its place.

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 no-parameter read tool with full annotation coverage, the description plus annotations give an agent enough to call it correctly. The remaining gap is that no output schema exists and the description does not hint at what a returned member record or list shape looks like, including whether the list is paginated.

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 tool takes zero parameters and the schema is fully closed (additionalProperties: false), so there is nothing for the description to clarify. A 4 is the baseline for a parameterless tool, and the description correctly avoids inventing parameter talk.

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 ("List team members") that an agent can immediately distinguish from the nearest sibling, list_member_usage, which is about per-member usage data rather than roster membership. It falls short of a 5 because it never names that sibling or any boundary explicitly.

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 a prerequisite (scope `team:read`) but no guidance on when to choose this versus alternatives such as list_member_usage or list_invites. The use case is implied by the name and is fairly self-evident, which fits a 3.

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