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

Annotations already disclose destructiveHint=true, readOnlyHint=false, idempotentHint=false, openWorldHint=true. The description adds valuable scope-limiting context beyond those flags: it names the only mutated field (display_name) and explicitly states that roles, passwords and email addresses are untouched. It doesn't cover what happens on an invalid id or the openWorld reach, so it's not a full 5.

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?

Four sentences, front-loaded with the list-then-update split, zero filler. The exclusion guarantee ('Roles, passwords and email addresses are not touched') is the right thing to keep because it drives the destructiveHint safety decision.

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?

The tool is dual-mode (read + write), has an output schema (so return format need not be described), and the description covers the read path, the write path, and the write's blast radius. It under-documents site_url and first/last_name, but the essential call semantics are present.

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 five parameters (id, site_url, first_name, last_name, display_name) are undocumented in the schema. The description compensates for two: id and display_name, with their combined semantics. It says nothing about site_url or the first/last name parameters, leaving a real gap even though the overall shape is inferable.

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+resource ('List the users of a connected WordPress site') and a second distinct action ('change the name a user is shown under'). It also names the fields returned, so an agent can distinguish this from siblings like wordpress_list_posts or wordpress_search_content.

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?

Explicitly states the no-argument case ('Call with no arguments to list users') and the mutation case ('Pass id together with display_name to fix a byline'). It even carves out exclusions – roles, passwords, email addresses are not touched – which is exactly the when/when-not guidance the dimension asks for.

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