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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds real context beyond that: the result set is limited to stored active theme mods and may omit registered settings, which prevents false-negative conclusions. It does not describe return shape or ordering, so it stops short of a 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?

Two dense sentences with the scope constraint front-loaded and no filler; every clause carries routing or caveat information. The closing instruction about inspecting theme-rendered source is somewhat abstract but still occupies only one sentence and adds workflow value.

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 single-parameter, read-only list tool with a fully documented schema and clear annotations, the description covers the main risk (assuming completeness) and the fallback tool. Minor gaps remain around whether results are paginated or what per-mod fields are returned, but these are low-stakes for a read-only listing.

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?

Only one parameter (site_id) and the schema description already covers it at 100%, including the 'call list_sites first, do not use a URL or post ID' guidance. The description adds no further meaning about site_id, so the schema-heavy baseline of 3 applies.

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 ('Lists stored active theme mods') and immediately bounds scope with 'not every Customizer setting,' which tells an agent exactly what this returns versus the broader Customizer surface. It also names the sibling to use when a setting is out of scope, so disambiguation is possible without opening schemas.

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?

Explicit routing: for native Astra Header Builder or other registered settings missing here, use wp_list_customizer_settings. It also adds a workflow condition ('Inspect theme-rendered source state before choosing a mutation path'), giving both when-to-use-this and when-to-use-the-alternative guidance.

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