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

With readOnlyHint/idempotentHint already declared, the description still adds substantial unseen context: updates_reported: false means 'not known rather than none waiting', must-use plugins and drop-ins are never update-checked so their staleness is unknown, and ignored updates remain listed with their ignore scope and reason. These are interpretation rules an agent could not infer from the annotations or schema and that change how results get reported.

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?

Front-loaded with the action and return content, and every clause (must-use/drop-ins, ignored-update semantics) carries decision-relevant information. Structure suffers slightly from being one long semicolon-chained paragraph, which makes the caveats harder to scan than a short list would.

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?

There is no output schema, and the description compensates fully by explaining the returned fields, the updates_reported flag, the not_update_checked category, and the ignored-annotation shape. An agent can both call this and correctly interpret ambiguous results without further documentation.

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?

One optional parameter with 100% schema description coverage, so the schema already carries the meaning and the baseline is 3. The description's 'default every connected site' adds only marginal value over the schema's 'Omit for every eligible site' and even introduces a slight wording drift ('connected' vs 'eligible').

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 the plugin updates waiting on each chosen site') plus the exact per-plugin fields returned, so the agent knows this is fleet-wide pending-update inspection, not general plugin listing. It never names a sibling (e.g. fleet__list_plugins or single-site wp_list_plugin_updates) to draw the boundary explicitly, so it stops short of the top band.

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?

Gives clear scope defaults ('Optional site_ids (default every connected site)') and an explicit behavioral exclusion ('don't suggest or plan ignored updates unless the person asks'). It does not route between alternatives (e.g. when to use this versus a per-site plugin update tool), so the guidance is contextual rather than comparative.

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