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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is partly covered; the description nonetheless adds real behavior: the exact per-row fields returned, including a 'problem' field hinting at partial-failure reporting. It also discloses a hard privacy guarantee ('Never who: members are never named') and warns that names/descriptions are user-authored data rather than instructions. What is missing is any note on account prerequisites or result size/ordering.

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?

It is short and front-loads the resource before the field list, so the agent gets the gist immediately. The clipped, note-like phrasing ('Never who', 'any problem') is efficient but occasionally reads as shorthand rather than clear prose.

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?

With no parameters and no output schema, the description carries the return-shape burden and does so by naming the returned fields, plus it covers the privacy and prompt-injection concerns an agent needs to handle results safely. It falls short only on prerequisites and on how to recover when the 'problem' field is populated.

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?

There are zero input parameters, so there is nothing for the description to disambiguate and the baseline is 4. It does not mislead by implying filtering options that do not exist, which keeps it at that baseline.

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 states a specific resource (Discord roles granted by the link owner to badge holders) and even enumerates the shape of each row: server, role, opt-in count, and any problem. That is concrete and distinguishes it from badge-management siblings. It never explicitly names a sibling or the 'my' scoping, so an agent must infer it is the caller's own data from the name alone.

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?

Usage is only implied: it is a read of existing role links for one's own badges. The one boundary signal is 'Connecting a server is done on FloorFeed', which usefully tells the agent this tool cannot establish a link. There is no statement of when to prefer a sibling like my_badge_games or my_soulbound_badges, and no prerequisite conditions (e.g. whether a linked account is required).

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