Audit CMS Page Blocks

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral detail beyond annotations by specifying the internal parsing of block_id references and the reporting of counts, which are not conveyed by the annotations alone. This enriches understanding of what the tool does internally.

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 two sentences with zero filler. The main action and scope are front-loaded in the first sentence, and the second sentence adds a practical output summary and the tool's value proposition. Every clause earns its place, making it concise and well-structured.

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?

Given the output schema exists (which explains return structure), the description already covers the key outputs: block identifiers, titles, is_active status, and active/inactive counts. The annotations cover safety, and the parameters are fully documented. Nothing an agent needs to decide whether to call the tool or interpret its results 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 all three parameters are fully documented in the schema. The description adds little beyond restating that the tool uses the identifier to load a page, which the schema already describes. It does not provide additional semantics or usage nuances for the parameters, so the baseline score of 3 is appropriate.

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 uses specific verbs: 'Loads', 'parses', 'reports' and names the exact resource (CMS page by identifier). It clearly distinguishes from siblings like get_cms_page (which fetches a page) by being an audit action that analyzes embedded blocks and returns counts, making its purpose unmistakable.

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 implies when to use it ('replaces manual SQL + regex parsing') and its scope (audit embedded blocks), but it does not explicitly name which sibling alternatives to avoid or when to prefer one over another. The context is clear enough for an agent to infer usage, but a direct reference to alternatives would elevate it.

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