WordPress: Wp user list

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

Annotations only declare readOnlyHint=true; the description adds real context beyond that: a minimum Bridge version (v2.11.0+) and the manage_options capability, which tells the agent an auth failure is plausible before the call. It also discloses the pagination ceiling of 200 per call. Gaps remain around result ordering, total-count behavior, and error modes.

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 compact sentences with no filler: capability/return fields first, then filters, pagination, and prerequisites. The phrase 'paginated up to 200 per call' is slightly ambiguous about whether it bounds per_page or total results, but nothing is wasted.

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 output schema, the description compensates by enumerating the returned fields, and it discloses the permission and version requirements an agent needs before calling. The notable hole is the required `site` parameter, which is left entirely to the bare schema, plus no mention of pagination metadata for walking multiple pages.

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 0%, so the description must carry all parameter meaning, and it only partially does. It explains `role` and `search`, and gives a cap for paging (200 per call, implying per_page), but the required `site` parameter is never mentioned and `page` semantics are only implied.

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 ('List') and resource ('WordPress users') and enumerates the returned fields (id, username, email, display name, roles, registration timestamp), so an agent knows exactly what it gets back. The resource is unique among the sibling tools (cron, menu, plugin, theme, db, option), so no disambiguation sentence is required.

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 implies usage by mentioning optional role and search filters, which hints at filtered lookups, but never says when to reach for this versus another discovery path or what happens when filters are omitted. The prerequisites (Bridge v2.11.0+, manage_options) are useful gating information but are not usage guidance.

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