List block templates

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond the annotations: it warns that classic themes return nothing from this tool and clarifies that only block themes are in scope. This helps an agent predict the outcome before calling the tool.

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 focused sentences convey scope, examples, limitations, and an alternative without fluff. The main definition is front-loaded, and the caveat about classic themes is positioned exactly where an agent will notice it.

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 simple read-only listing tool with fully documented parameters and safe annotations, the description is complete. It explains what the tool lists, what kind of themes it applies to, what happens for classic themes, and where to go instead. No output schema is present, but the description's scope and behavioral caveats give enough context for correct selection and invocation.

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?

The input schema fully documents both parameters, including the kind enum and the site_id behavior, so schema coverage is 100%. The description adds no parameter-level detail beyond naming template parts, so it does not need to compensate. A baseline of 3 is appropriate when the schema already carries the semantic weight.

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 names a specific verb and resource: it lists a block theme's templates or template parts, with concrete examples like front-page, single, archive, header, and footer. It also distinguishes itself from related tools by explicitly carving out classic themes, so an agent can tell it apart from list_themes and the theme file tools.

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 when-to-use guidance ('Block themes only') and when-not-to-use guidance ('a classic theme returns nothing here'), and points to an alternative tool category ('you should use the theme file tools instead'). This is exactly the kind of routing an agent needs to avoid wasted calls.

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