List roles

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it discloses the fallback behavior between the companion plugin and standard WordPress roles, which could affect output. This is valuable because the openWorldHint is true but the description clarifies a specific environmental dependency.

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 with no filler. The first sentence states the core action and purpose, and the second covers the fallback mechanics. Everything earns its place, and the most important purpose is front-loaded.

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 read-only list tool with no required parameters, high schema coverage, and destructive/read-only annotations already provided, the description is complete. It explains the output scope (roles and capabilities), the fallback behavior, and the intended usage context. No other information an agent needs to call this correctly is missing.

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 sole parameter site_id is fully described in the schema (coverage 100%), including its optionality and behavior with multiple sites. The description adds no additional parameter-specific semantics (e.g., format or examples), so the baseline of 3 applies since the schema handles the explanatory burden.

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 specific verb-resource pair ('List the roles registered on the site') and includes their capabilities. It also gives the practical purpose ('so you can pick the right role before creating or updating a user'), which distinguishes it from sibling tools like list_users or get_user by linking it to user creation/update workflows.

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?

It explicitly indicates when to use the tool: before creating or updating a user, which is a clear context. However, it does not explicitly contrast with alternative tools (e.g., list_users) or state when not to use it, but the guidance is strong enough to route the agent appropriately.

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