Inspect options and transients

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's job is to add context — and it does substantially. It discloses that owner attribution is a heuristic ('guessed from installed plugin/theme slugs' with inactive/uninstalled owners flagged), that WordPress 6.6 autoload values (on/auto-on/auto) are honored, and that the tool 'Needs the companion plugin' — a critical dependency. These are genuine behavioral disclosures beyond the annotations, and there is no contradiction with readOnlyHint.

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?

The description is long (~70 words) but every clause carries a distinct report feature: the threshold comparison, owner guessing, rollup, transient hygiene metrics, WP 6.6 compatibility, usage guidance, and the plugin dependency. It is dense and information-efficient, though it runs as one extended sentence that would benefit from structural breaks. Given there is no output schema, the enumeration earns its length.

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 carries the burden of explaining return values — and it does so in detail: total bytes, largest options with owner flags, per-owner rollup, and transient metrics (count, bytes, expired rows, orphaned timeout rows, largest entries). Prerequisites ('Needs the companion plugin') and workflow placement ('before cleanup_options') are covered. Nothing an agent needs to invoke this safely 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?

Schema description coverage is 100%, so the baseline is 3. Both limit and site_id are already well-documented in the input schema, including the 'up to 20' transient cap and the single-site default behavior. The description adds nothing beyond the schema about parameters, so it neither needs to compensate nor does it exceed the 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 opens with a specific verb+resource ('Report where the options table carries weight') and enumerates the exact scope: autoloaded bytes vs Site Health's 800 KB threshold, largest autoloaded options with owner guesses, per-owner rollup, and transient hygiene. It differentiates from siblings by naming cleanup_options as the downstream action and get_options-style tools are implicitly distinct since this reports aggregate weight rather than single option values.

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 gives explicit usage context: 'Use it before cleanup_options to decide what to change.' This anchors the tool in a decision workflow and names the related sibling. It does not, however, state when NOT to use it or route to alternatives like get_options or set_option for single-value lookups, so it stops short of full when/when-not coverage.

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